Architecture Decision Records preserve why a team chose one approach over another. They help future developers understand constraints that may not be obvious from the code.
Keep each record focused
A useful ADR includes a title, status, context, decision, alternatives considered, and consequences. Explain the forces behind the choice, such as operational capability, compatibility, security, cost, or team expertise.
Record tradeoffs honestly
Avoid presenting the chosen option as perfect. State what becomes easier, what becomes harder, and which risks remain. This helps future teams decide whether the original context still applies.
Keep history append-only
When a decision changes, create a new ADR that supersedes the earlier one rather than silently rewriting history. Link related records and code changes where helpful.
Avoid documenting every minor choice
Use ADRs for decisions with meaningful long-term impact: database selection, integration boundaries, authentication architecture, deployment topology, or major data-model choices.
Checklist
- Capture context and constraints.
- Compare realistic alternatives.
- State consequences and known risks.
- Record status and decision date.
- Supersede old decisions rather than erasing history.