Architecture Decision Record
Create and maintain ADRs for significant technical decisions.
When to Create an ADR
- Choosing between technologies or frameworks
- Defining architectural patterns
- Making trade-offs with long-term implications
- Decisions that are hard to reverse
- Choices that affect multiple teams or systems
Process
1. Research Context
- Review existing architecture and decisions
- Identify constraints (technical, business, regulatory)
- Gather requirements and quality attributes
- Consult with stakeholders
2. Evaluate Options
For each option:
- List concrete pros and cons
- Consider maintenance and operational impact
- Evaluate against quality attributes
- Estimate effort and risk
3. Make and Document Decision
Use the template below to capture the decision.
ADR Template
# ADR-[NUMBER]: [TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Date
[YYYY-MM-DD]
## Context
[What is the issue? What forces are at play?]
- Business context
- Technical constraints
- Quality requirements
## Decision
[What is the change we're making?]
We will use [decision] because [primary reason].
## Options Considered
### Option 1: [Name]
**Description:** [Brief explanation]
**Pros:**
- Pro 1
- Pro 2
**Cons:**
- Con 1
- Con 2
**Effort:** [Low | Medium | High]
### Option 2: [Name]
[Same structure]
### Option 3: [Name] (if applicable)
[Same structure]
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Drawback 1 and how we'll mitigate]
### Neutral
- [Side effect that's neither good nor bad]
## Implementation Notes
- [Key implementation considerations]
- [Migration steps if applicable]
- [Monitoring/validation approach]
## References
- [Link to related ADRs]
- [Link to documentation]
- [Link to relevant discussions]
File Naming Convention
docs/adr/
├── 0001-use-nextjs-for-frontend.md
├── 0002-adopt-drizzle-orm.md
├── 0003-aws-ecs-for-deployment.md
└── README.md (index of all ADRs)
Review Checklist
- Context clearly explains the problem
- All viable options are considered
- Pros/cons are concrete, not vague
- Decision rationale is clear
- Consequences are honest (including negatives)
- Implementation path is outlined