Skip to main content

Decision records (ADRs)

Decisions get silently reversed when nobody remembers why they were made. In a world where agents generate most of the code, that risk is worse: an agent will happily undo a deliberate choice it can't see the reason for. Architecture Decision Records (ADRs) are the memory that stops this. They are written for humans and read by agents.

When to write one​

Write an ADR for any decision that is costly to reverse or easy to forget the reason for:

  • Architecture — a structural choice, a boundary, a pattern adopted or rejected.
  • Design — a significant UX or data-model direction.
  • Product — a scope or prioritisation call with lasting consequences.
  • Toolkit — adopting, trialling or retiring a tool, framework or model (these also move the tech radar).

You do not need one for routine, easily-reversed choices. If in doubt: would a competent newcomer (or an agent) six months from now waste time re-deriving or wrongly undoing this? If yes, record it.

The standard​

  • One decision per file. Copy the template at toolkit/templates/adr.md into the target repo's decision-record directory (e.g. docs/adr/), named NNNN-kebab-title.md with a zero-padded sequential number.
  • Keep it short. An ADR is a record, not an essay: context, options considered, the decision, the consequences, and a revisit-by date or trigger.
  • Status is explicit: Proposed → Accepted, and later Superseded by ADR-XXXX or Deprecated. Never edit a decision's history — supersede it with a new ADR that links back.
  • Stored in-repo, reviewed in the PR. An ADR lands with the change it justifies.

How agents use them​

  • Agents are instructed to read the ADR directory as context and respect accepted decisions — they will not silently reverse one.
  • When an agent's work implies a new decision of the kinds above, it drafts the ADR; a human accepts it.
  • The Merge gate checks that a PR of a flagged change type carries an ADR.

Why this format​

ADRs (Michael Nygard's pattern, as used in arc42) win because they're lightweight enough to actually write, live next to the code, and diff in review. Heavier decision documentation doesn't get maintained; an undocumented decision is one an agent will eventually undo.