| name | adr |
| description | Use when making significant technical decisions that should be documented — framework choices, architecture patterns, trade-offs, and migration decisions |
Architecture Decision Records
Overview
Document why you chose one approach over another. Future you (and future Claude sessions) need this context.
Core principle: Decisions without documented reasoning get relitigated endlessly. Write it down once.
When to Use
- Choosing a framework, library, or tool
- Deciding on architecture patterns (monolith vs microservice, sync vs async)
- Making trade-offs (consistency vs availability, simplicity vs flexibility)
- Changing an existing decision
- Any decision someone might ask "why did we do it this way?"
ADR Format
# ADR-[NNN]: [Decision Title]
**Status:** [Proposed | Accepted | Deprecated | Superseded by ADR-NNN]
**Date:** [YYYY-MM-DD]
**Deciders:** [who was involved]
## Context
[What is the situation? What forces are at play? What problem are we solving?]
## Decision
[What did we decide to do?]
We will use [choice] because [primary reason].
## Alternatives Considered
### Alternative A: [name]
- **Pros:** [list]
- **Cons:** [list]
- **Why not:** [decisive reason]
### Alternative B: [name]
- **Pros:** [list]
- **Cons:** [list]
- **Why not:** [decisive reason]
## Consequences
### Positive
- [benefit 1]
- [benefit 2]
### Negative
- [trade-off 1]
- [trade-off 2]
### Risks
- [risk 1] — mitigated by [how]
## Review Triggers
Revisit this decision when:
- [condition 1, e.g., "team grows beyond 5 engineers"]
- [condition 2, e.g., "traffic exceeds 10k req/sec"]
File Organization
docs/
adr/
001-use-fiber-over-echo.md
002-clean-architecture.md
003-offset-pagination.md
004-generic-validation.md
005-monolith-first.md
Common ADR Topics
| Decision | Key Trade-offs |
|---|
| Framework choice | Ecosystem, performance, learning curve, community |
| Monolith vs microservices | Complexity, deployment, team size, scaling |
| SQL vs NoSQL | Consistency, query flexibility, schema evolution |
| REST vs GraphQL | Client flexibility, caching, complexity |
| Sync vs async processing | Latency, reliability, complexity |
| Build vs buy | Cost, customization, maintenance burden |
| Offset vs cursor pagination | Simplicity vs performance at scale |
Anti-Patterns
- No alternatives listed — if you didn't consider alternatives, you didn't make a decision
- No consequences — every decision has trade-offs, document them
- Too vague — "we chose the best option" explains nothing
- Never updated — mark old ADRs as deprecated/superseded, don't delete them
Chains
- REQUIRED: Update CLAUDE.md if decision changes architecture or conventions (
claude-md)
- After:
system-design decisions, data-model schema decisions
- Reference: During
go-refactor / py-refactor to understand original intent
