Agentient Architectural Decision Records (ADRs)
What is an ADR?
An ADR documents why a significant technical decision was made, not just what was decided.
When to Create an ADR
Create an ADR for:
- ✅ Technology selection (Next.js vs Remix, Zustand vs Redux)
- ✅ Architectural patterns (Server Components default, API design approach)
- ✅ Data modeling decisions (SQL vs NoSQL, schema design)
- ✅ Security patterns (authentication approach, authorization model)
- ✅ Performance trade-offs (caching strategy, bundling approach)
Don't create ADRs for:
- ❌ Routine code changes
- ❌ Bug fixes
- ❌ Refactoring without architectural impact
ADR Template
# 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]
Example ADR
# 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)
ADR Lifecycle
- Proposed - Decision under discussion
- Accepted - Decision approved and being implemented
- Deprecated - Decision no longer valid but kept for history
- Superseded by ADR-XXX - Decision replaced by newer ADR
Store ADRs in docs/adr/ directory with sequential numbering.
For full examples and governance, use /generate-adr command.