Architecture Decision Records: The Why Behind the System
An ADR captures one decision, its context, and its consequences in a short versioned file, so future engineers inherit reasoning instead of rumours.
Definition
An architecture decision record is a short, immutable document that states a significant technical decision, the forces that shaped it, the alternatives considered, and the consequences accepted, stored alongside the code it affects.
Context and scope
Systems outlive the people who designed them; without records, teams re-litigate settled questions or repeat experiments that were already rejected.
Common misconceptions
- ADRs are design documents — they record a single decision, not a whole design
- ADRs must be approved by architects — ownership sits with the team making the decision
- Accepted decisions cannot change — they are superseded, not rewritten
Anti-patterns
- Writing ADRs months after the decision, reconstructing a rationale nobody remembers
- Recording decisions with no consequences or rejected options
- Editing accepted records instead of superseding them
Related concepts
Authoritative source
One decision per record
An ADR answers a single question: why did we choose this, given what we knew? It is short by design, usually one page, and it lives in the repository next to the code it constrains. A decision that needs ten pages is usually several decisions that should be recorded separately, each with its own status.
What a good record contains
Context describes the forces, not the solution. The decision states what was chosen in one or two sentences. Consequences list what becomes easier, what becomes harder, and what is now hard to reverse. Alternatives belong in the record, because the rejected options are what future engineers most want to understand.
# 0012 Queue-based order processing
Status: accepted (2026-09-14)
Context: checkout latency spikes when the warehouse API is slow.
Decision: publish order events to a queue; consumers retry independently.
Consequences: checkout no longer blocks; duplicates must be handled downstream.
Alternatives: synchronous retries (rejected: latency), circuit breaker only (rejected: drops orders).Lifecycle and supersession
Records move from proposed to accepted, and later to superseded or deprecated. Never edit an accepted record to reflect a new opinion; write a new one that references it. That history is the point: it shows when assumptions changed and what prompted the change, which is often more valuable than either decision alone.
Where records live
Keep ADRs in the repository they affect, indexed by a README. Cross-team decisions can also live in a central archive, but the copy near the code should be authoritative. Review new records in the same pull request as the change, so the decision and its implementation ship together.
Compared to design documents
A design document describes a solution in full before it exists. An ADR records a commitment after weighing options. Design documents go stale quickly; ADRs stay true because they describe a moment and its reasoning. Teams need both, but only one of them can be written in twenty minutes.