What is an ADR?
An Architecture Decision Record (ADR) is a short document that captures a significant architectural decision, the context in which it was made, the options considered, and the rationale for the choice.
The key insight behind ADRs: future engineers will make worse decisions if they don’t understand why past decisions were made.
When to write an ADR
Write an ADR when:
- The decision affects more than one team
- The decision is hard to reverse
- You’re choosing between multiple reasonable options
- Future engineers will wonder “why did they do it this way?”
Don’t write an ADR for:
- Implementation details within a team’s service
- Decisions with obvious rationale
- Small, easily reversible decisions
ADR format
# ADR-[number]: [Short title]
**Status**: [Proposed | Accepted | Deprecated | Superseded by ADR-X]
**Date**: YYYY-MM-DD
**Deciders**: [Who made this decision]
## Context
What is the issue motivating this decision? What is the problem we're solving?
Include relevant constraints, forces at play, and the technical and business context.
## Options considered
### Option 1: [Name]
Brief description.
**Pros**: ...
**Cons**: ...
### Option 2: [Name]
Brief description.
**Pros**: ...
**Cons**: ...
## Decision
We chose Option X because...
## Consequences
What becomes easier or harder as a result of this decision?
What are the risks?
What are the follow-up decisions that need to be made?
Where to store ADRs
In the repository they apply to, in a docs/decisions/ directory. Name files NNNN-short-title.md where NNNN is a zero-padded sequential number.
For cross-system decisions: a dedicated architecture-decisions repository.
ADR anti-patterns
The retrospective ADR: Written after the fact to justify a decision already made. These read like arguments, not reasoning. They capture the conclusion but not the real tradeoffs.
The too-detailed ADR: ADRs should capture the decision and its rationale, not replace detailed design documents.
ADRs with no follow-through: If the ADR leads to consequences (follow-up decisions, risks to monitor), those need to be tracked somewhere. An ADR is not a substitute for execution.