From frontend-tools
Architecture Decision Records (ADRs) format, templates, and best practices for documenting technical decisions. PROACTIVELY activate for: (1) documenting significant technical decisions, (2) recording design trade-offs, (3) creating technology selection rationales. Triggers: "ADR", "decision record", "architecture"
How this skill is triggered — by the user, by Claude, or both
Slash command
/frontend-tools:architectural-decision-recordsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
An ADR documents **why** a significant technical decision was made, not just **what** was decided.
An ADR documents why a significant technical decision was made, not just what was decided.
Create an ADR for:
Don't create ADRs for:
# ADR-[NUMBER]: [Title in Present Tense]
**Date**: YYYY-MM-DD
**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
**Deciders**: [Names]
## Context
[What problem are we solving? What forces are at play? What constraints exist?]
## Decision
[What are we doing? Be specific and concrete.]
## Consequences
### Positive Consequences
- [Benefit 1]
- [Benefit 2]
### Negative Consequences
- [Cost/Risk 1]
- [Cost/Risk 2]
### Mitigation Strategies
- [How to address negative consequence 1]
- [How to address negative consequence 2]
## Alternatives Considered
### Alternative 1: [Name]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]
- **Why Rejected**: [Specific reason]
### Alternative 2: [Name]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]
- **Why Rejected**: [Specific reason]
## References
- [Documentation links]
- [Related ADRs]
# ADR-001: Adopt React Server Components as Default
**Date**: 2025-10-23
**Status**: Accepted
**Deciders**: Engineering Team
## Context
Next.js 14+ offers two component types: Server Components (default) and Client
Components. We must decide which to use as our default pattern.
Our goals:
- Minimize client-side JavaScript bundle size
- Improve page load performance
- Maintain developer productivity
Constraints:
- Team has React experience but limited RSC knowledge
- Some features require client-side interactivity
## Decision
We will use **React Server Components** as the default for all new components.
Client Components (marked with 'use client') will be used only for:
- Interactive UI (forms with local state, buttons with onClick)
- Browser API usage (localStorage, window)
- React hooks (useState, useEffect)
## Consequences
### Positive Consequences
- **50% smaller bundles**: Less JavaScript sent to client
- **Faster page loads**: Server-rendered HTML loads immediately
- **Better SEO**: Pre-rendered content is indexable
- **Direct database access**: No need for API layer in many cases
### Negative Consequences
- **Learning curve**: Team must understand Server vs Client boundaries
- **Debugging complexity**: Errors can occur in different environments
- **Third-party library compatibility**: Not all libraries work with RSC
### Mitigation Strategies
- Provide team training on Server Component patterns
- Create reusable templates for common scenarios
- Document compatible libraries in project wiki
- Use TypeScript strict mode to catch boundary violations early
## Alternatives Considered
### Alternative 1: Client Components Default (Traditional React)
- **Pros**: Team familiar with this approach, no learning curve
- **Cons**: Larger bundles, slower performance, more boilerplate
- **Why Rejected**: Doesn't leverage Next.js 14+ performance benefits
### Alternative 2: Mix without clear default
- **Pros**: Flexibility to choose per component
- **Cons**: Inconsistent codebase, harder to review/maintain
- **Why Rejected**: Need clear patterns for team consistency
## References
- [React Server Components](https://react.dev/reference/rsc/server-components)
- [Next.js App Router](https://nextjs.org/docs/app)
Store ADRs in docs/adr/ directory with sequential numbering.
For full examples and governance, use /generate-adr command.
npx claudepluginhub agentient/vibekit --plugin frontend-tools<!-- AUTO-GENERATED by export-plugins.py — DO NOT EDIT -->
Creates and maintains Architecture Decision Records (ADRs) using templates and best practices. Useful for documenting technical decisions, trade-offs, and architectural reviews.
Documents significant architectural and technical decisions with context, alternatives, trade-offs, and consequences. Creates a decision trail for teams. Use when choosing technologies, making infrastructure decisions, or establishing standards.