Decision records
A decision record captures why a choice was made, in a form the person joining the team next year can read without a meeting. It is not a design doc, a status update, or a policy — it is one page per decision, written once, rarely edited.
Recommended default
Section titled “Recommended default”Write an Architecture Decision Record (ADR) only when the decision passes three tests:
- Hard to reverse — the cost of changing your mind later is meaningful.
- Surprising without context — a future reader will ask “why did they do it this way?”
- A real trade-off — there were genuine alternatives and you picked one for specific reasons.
If any of the three is missing, skip the ADR. A commit message, PR description, or code comment is enough.
- Store them in the repo.
docs/adr/NNNN-slug.md, numbered sequentially. Not in a wiki, not in Notion — next to the code the decision constrains. - One decision per record. If you’re tempted to bundle two, they’re probably not both ADR-worthy.
- Written when the decision is made, not after. Retrofitting ADRs from memory produces fiction.
- Status: proposed / accepted / superseded. No “draft” state — if it’s not ready to accept, don’t merge it.
- Superseded, not deleted. When a later ADR reverses an earlier one, mark the old one superseded and link forward. History is the point.
Why this is the default
Section titled “Why this is the default”Teams that record every decision drown the load-bearing ones in noise — nobody reads the log, so nobody adds to it. Teams that record none lose the reasoning behind the choices that actually constrain future work, and re-litigate them every 18 months. The three-part gate is the filter that separates “decision” from “ADR-worthy decision.”
Keeping ADRs in the repo means they travel with the code, get reviewed like code, and can’t be quietly edited to rewrite history.
Common mistakes or tradeoffs
Section titled “Common mistakes or tradeoffs”- Documenting every choice. Renamed a variable, picked the obvious library, followed the framework’s default — none of these are ADRs.
- Writing ADRs after the fact. Reconstructed reasoning is retrofitted justification. Write it when the trade-off is live.
- Editing accepted ADRs. If the decision changes, write a new one that supersedes. Never rewrite history.
- ADRs as design docs. Design lives in a doc, a spike, or a diagram. The ADR captures the chosen trade-off — one page, not ten.
- No alternatives section. “We picked X” without naming what X beat is a note, not a decision record.
Template
Section titled “Template”# NNNN — Short title
- Status: accepted- Date: 2026-09-01- Deciders: <names or roles>
## Context
What forced the decision. One paragraph.
## Decision
What we chose. One paragraph, active voice.
## Alternatives considered
- **Option A** — why we didn't pick it.- **Option B** — why we didn't pick it.
## Consequences
What this makes easier, harder, or impossible. Include the cost we're accepting.Step by step
Section titled “Step by step”- Catch yourself about to document a choice. Run the three tests.
- If it qualifies, create
docs/adr/NNNN-slug.mdwith the next number. - Fill the template. Keep it to one page.
- Open it as a PR alongside the code change that motivated it — review together.
- On merge, the ADR is accepted. To reverse: write a new ADR that supersedes, and mark the old one
Status: superseded by NNNN.
Further reading
Section titled “Further reading”- Michael Nygard’s original ADR post (2011) — the format most teams still use, and the source of the “context / decision / consequences” shape.
- MADR (Markdown Architectural Decision Records) — a slightly richer template with an alternatives section, worth borrowing.
- ThoughtWorks Technology Radar on lightweight ADRs — the case for keeping ADRs in-repo rather than in a wiki.