Skip to content

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.

Write an Architecture Decision Record (ADR) only when the decision passes three tests:

  1. Hard to reverse — the cost of changing your mind later is meaningful.
  2. Surprising without context — a future reader will ask “why did they do it this way?”
  3. 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.

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.

  • 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.
# 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.
  1. Catch yourself about to document a choice. Run the three tests.
  2. If it qualifies, create docs/adr/NNNN-slug.md with the next number.
  3. Fill the template. Keep it to one page.
  4. Open it as a PR alongside the code change that motivated it — review together.
  5. On merge, the ADR is accepted. To reverse: write a new ADR that supersedes, and mark the old one Status: superseded by NNNN.