Architecture Decision Records
Preserve technical decision context so teams can reason about past tradeoffs.
Recommended approach
Use lightweight ADRs for stack, architecture, and process decisions with lasting impact.
ADR template
- Context: what forced this decision.
- Decision: what was chosen.
- Alternatives: what was rejected and why.
- Consequences: expected outcomes and risks.
- Review date: when to revisit.
Implementation checklist
- Store ADRs in version control.
- Link ADRs from relevant docs pages and PRs.
- Update ADR status when decisions change.
Common pitfalls
- Writing ADRs only for “big” decisions and missing recurring patterns.
- Never revisiting decisions after product scale changes.