Architecture decision records
An ADR is a short document recording one decision, its context, and its consequences, committed alongside the code. Job descriptions ask for them because the expensive knowledge in a codebase is why, and that is exactly what code cannot express.
The problem they solve
Read a repository and you can recover what it does. You cannot recover why Postgres over DynamoDB, why the retry budget is three, or why a service was split. That reasoning lives in a design review nobody wrote down and in the heads of people who have left.
The cost lands later, when someone reverses a decision without knowing what it was protecting against, and re-learns it as an incident.
The format
One file per decision, numbered, in the repository.
docs/adr/
0001-postgres-over-dynamodb.md
0002-retry-budget-and-timeouts.md
0003-split-billing-service.mdThe content is four sections, and the shape matters more than the template:
# 2. Retry budget and timeouts
Status: Accepted (2026-03-11)
## Context
Checkout calls three services. Cascading retries in a
partial outage tripled load on the slowest one.
## Decision
One retry, 200ms budget, jittered. Retries only on
connect errors and 503.
## Consequences
Fewer self-inflicted outages. Some transient errors
now reach users; the client handles them.Context is the valuable half. A decision without the pressure that produced it is unfalsifiable later - you cannot tell whether the reasoning still holds. Record the constraint (traffic, team size, deadline, an incident), not just the choice.
Consequences must include what you gave up. An ADR listing only benefits is marketing, and the next reader will not trust it.
Status is the mechanism
Proposed, Accepted, Deprecated, Superseded by 0012.
ADRs are immutable once accepted. You do not edit a decision that changed - you write a new one and mark the old superseded. That is what preserves the trail: the sequence of decisions is the history, and rewriting it destroys the record you wrote them for.
What deserves one
The filter is cost of reversal. If undoing the choice is a refactor, it does not need an ADR. If undoing it is a migration, it does.
| Write one | Skip it |
|---|---|
| Datastore, broker | Library or formatter |
| Service boundaries | Directory layout |
| Auth, tenancy model | Naming conventions |
| Public schemas | Anything easily reversed |
Also worth recording: decisions you rejected. “We considered event sourcing and chose not to, because…” saves the next person from re-proposing it.
Teams that write ADRs for everything stop writing them. Ten good ones beat a hundred nobody reads.
Keeping them true
The failure mode is a folder of ADRs describing a system that no longer exists. Three habits prevent it:
- In the repository, in the same pull request as the change they describe. A wiki decays because it is not next to the code and is never reviewed.
- Written when the decision is made, not reconstructed afterwards. A retrospective ADR records what you now believe, not what you knew.
- Linked from the code where the decision is visible - a comment on the
odd-looking retry constant pointing at
adr/0002.
The related discipline is spec-first work: the specification says what will be built, the ADR says why it is built that way, and both precede the code. See AI-assisted development and AI-DLC for why that matters more when generation is cheap - a model can produce a plausible implementation of the wrong decision very quickly.
Related
Interview angle 5
- “What is an ADR?” - a short record of one decision with its context and consequences, numbered and committed with the code. It captures the why, which is the part a codebase cannot express and the part that is expensive to lose.
- “What goes in one?” - context, decision, consequences, status. Context is the valuable half: without the pressure that produced the decision, a later reader cannot judge whether the reasoning still holds. Consequences must name what you gave up.
- “What do you do when a decision changes?” - write a new ADR and mark the old one superseded. They are immutable once accepted, because the sequence is the history; editing in place destroys the record you kept them for.
- “What deserves an ADR?” - anything whose reversal is a migration rather than a refactor: datastores, service boundaries, auth and tenancy models, public schemas. Not library or layout choices. Also record decisions you rejected and why.
- “How do you stop them going stale?” - keep them in the repository and require them in the same pull request as the change, so they are reviewed like code. A wiki decays because nothing forces it to be read.