Decision Records and Supersession
Writing a first architecture decision record is easy. Keeping a decision log useful three years later is harder. Decisions get reversed, refined, or quietly ignored. Someone edits an old record to match today's reality, and the history of why the team once chose otherwise disappears. Or nobody updates anything, and a newcomer follows a record that was abandoned two migrations ago.
The practice that keeps decision logs trustworthy is simple: treat accepted decisions as immutable history, and record changes as new decisions that explicitly supersede old ones. Combined with clear statuses, two-way links, and a few revisit triggers, a decision log becomes a reliable map of how the architecture got to where it is.
TL;DR
- Give every record a status: Proposed, Accepted, Rejected, Deprecated, or Superseded.
- Do not rewrite accepted decisions; write a new record that supersedes the old one.
- Link both ways: "Supersedes ADR-0012" in the new record, "Superseded by ADR-0031" in the old one.
- Small clarifications can be amendments noted with dates; changes in the decision itself need a new record.
- Add revisit triggers — conditions or dates that should prompt reconsideration.
- Keep an index of all records with current status, generated from the files.
Quick Example
The original decision, updated only in its status and link:
The new decision that replaces it:
With adr-tools, adr new -s 12 Use Kafka for order events creates the new record and updates both links.
Core Concepts
Statuses and the Lifecycle
Rejected records are valuable: they answer "did anyone consider X?" before someone spends a week rediscovering why X does not work.
Why Immutability Matters
A decision record captures what was known and decided at a point in time. If it is rewritten when circumstances change, readers lose the context that made the original choice reasonable, and the log stops explaining why systems look the way they do. Old decisions are not mistakes to hide; they are evidence of the constraints the team faced.
Superseding Versus Amending
Partial Supersession
Decisions often bundle several choices. When only one changes — for example, the message broker for events but not for jobs — the new record should say exactly which parts it replaces, and the old record's status note should say "partially superseded by ADR-0031 (event transport only)."
Keeping the Log Useful
Revisit Triggers and Review Dates
Record the conditions that would make the decision worth revisiting: a scale threshold, a contract renewal, a dependency's end of life, a team size. A periodic review — quarterly or at planning — walks through records whose triggers may have fired.
The Decision Log Index
Generate an index page listing number, title, status, date, and supersession links from the records' front matter, so readers see current decisions at a glance. Tools such as Log4brains render a searchable site; a small script in CI works just as well.
Connecting Decisions to Code
- Store records in the repository they govern (for example
docs/adr/), reviewed through pull requests. See Docs as Code. - Reference record numbers in code comments where a non-obvious choice is implemented:
// See ADR-0031: Kafka for order events. - Link pull requests that implement or reverse decisions to the records.
Templates
Popular templates include Michael Nygard's original format (Title, Status, Context, Decision, Consequences) and MADR, which adds considered options, decision drivers, and pros and cons. Adding a Revisit when section is a small change with a large payoff.
Best Practices
Write the Superseding Record Before Changing the System
A reversal is itself a decision with context and consequences. Writing it first forces the team to explain what changed and spot side effects.
Keep Records Small and Focused
One decision per record makes supersession clean. Large records that decide many things become partially obsolete in confusing ways.
Make Status Machine-Readable
Put status, date, and links in front matter so indexes, linters, and dashboards can use them — for example, failing CI if a superseded record lacks a link to its replacement.
Review Rejected and Deprecated Records Too
When a constraint disappears, a previously rejected option may become the best one. Periodic reviews should include them.
Common Mistakes
Rewriting History
One-Way Links
Silent Abandonment
FAQ
What does it mean to supersede an ADR?
To replace an accepted decision with a new decision record. The new record explains the new context and choice and references the old one; the old record's status changes to Superseded with a link to its replacement.
Can I edit an accepted ADR?
For typos, broken links, or clarifications, yes. If the decision itself changes, write a new record that supersedes it, so the original reasoning is preserved.
What is the difference between deprecated and superseded?
Superseded means a specific newer record replaces the decision. Deprecated means the decision is no longer recommended, but there is no single replacement — for example, when the system it governed was retired.
Should rejected decisions be kept?
Yes. They record options that were considered and why they were declined, which prevents repeated debates and helps future teams reconsider when constraints change.
How often should ADRs be reviewed?
Review records whose revisit triggers may have fired during regular planning, and do a broader pass periodically, such as quarterly. Reviews produce new records when decisions change, not edits to old ones.
Related Topics
- Architecture Decision Records — Writing ADRs
- Docs as Code — Keeping records with the code they govern
- Documentation Review and Maintenance — Keeping documentation current
- Architecture — The decisions records capture
- Release Notes and Changelogs — Another append-only record of change