| name | architecture-decision-records |
| description | Use when making or recording significant architectural decisions - capture context, alternatives, and rationale as structured ADRs |
Architecture Decision Records
When to Activate
- User chooses between significant alternatives (framework, DB, API design, auth strategy)
- User says "let's record this decision" or "ADR this"
- During planning phases when architectural trade-offs are discussed
- User asks "why did we choose X?"
ADR Format
# ADR-NNNN: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
## Context
[2-5 sentences: the problem motivating this decision]
## Decision
[1-3 sentences: the choice made]
## Alternatives Considered
### Alternative 1: [Name]
- **Pros**: ...
- **Cons**: ...
- **Why not**: ...
## Consequences
### Positive
- ...
### Negative
- ...
Workflow
- If
docs/adr/ doesn't exist, ask user before creating
- Extract core architectural choice
- Document alternatives and why they were rejected
- Assign number (increment from existing)
- Present draft for approval before writing
- Update
docs/adr/README.md index
Categories Worth Recording
| Category | Examples |
|---|
| Technology choices | Framework, database, cloud provider |
| Architecture patterns | Monolith vs microservices, event-driven |
| API design | REST vs GraphQL, auth mechanism |
| Data modeling | Schema design, caching strategy |
| Infrastructure | Deployment model, CI/CD pipeline |
| Security | Auth strategy, encryption approach |
| Testing | Test framework, coverage targets |
| Process | Branching strategy, review process |
ADR Lifecycle
proposed → accepted → [deprecated | superseded by ADR-NNNN]
Quick Reference
- Be specific: "Use Prisma ORM" not "use an ORM"
- Record the WHY, not just the WHAT
- Include rejected alternatives
- Keep under 2 minutes reading time
- Don't record trivial decisions
