ADRs in Practice
Overview
Section titled “Overview”The Architecture Decision Record is the highest-leverage artifact available to an architect with no mandate. It requires nobody’s permission, costs an hour, and is the only document that answers the question that actually recurs: why is it like this?
The format is Michael Nygard’s, from his 2011 note on documenting architecture decisions, and it has four fields. One of them does most of the work and one of them is almost always sanitised.
The four fields
Section titled “The four fields”graph TD A["<b>Context</b><br/>the forces and constraints<br/><i>as they were at the time</i>"] --> B["<b>Decision</b><br/>one statement"] B --> C["<b>Status</b><br/>proposed · accepted ·<br/>superseded by NNN"] C --> D["<b>Consequences</b><br/>including the<br/><b>negative</b> ones"] classDef best fill:#7D9A4E,stroke:#5F7A38,stroke-width:2px,color:#ffffff classDef plain fill:#5B8FB9,stroke:#4A7A9E,stroke-width:2px,color:#ffffff classDef key fill:#D9695B,stroke:#B4483A,stroke-width:2px,color:#ffffff class A best class B,C plain class D key
Four fields. The olive one carries the most value and the terracotta one carries the credibility — and it is the field most often reduced to a list of benefits.
Context is the most valuable field and the one people under-write. It records the forces, constraints and facts as they were at the time — not as they are now. That tense matters: a future reader’s actual question is does this decision still apply?, and they can only answer it by comparing today’s constraints against the ones recorded. A context section that describes the chosen solution rather than the pressures that produced it has failed.
Decision is one statement. If it needs a paragraph, it is more than one decision and should be more than one record.
Status is proposed, accepted, or superseded — and superseded by a specific record, with its number. Not “deprecated”, which tells a reader nothing about where to go next.
Consequences, including the negative ones. This is the rubric item for this module and the field that decides whether anyone trusts the set. A record listing only benefits is a sales document, and an experienced reader discounts the whole thing. The negative consequences are also the most useful content for the future: they tell someone what to watch for, and they are the early warning when a decision has stopped working.
Granularity
Section titled “Granularity”The rubric asks for consistency, and the failure mode is a set mixing “we chose PostgreSQL” with “we renamed a module”.
One test: does this decision constrain other decisions? If satisfying it forces choices elsewhere — Module 2’s architectural-significance test, applied to records — it deserves one. A library choice inside one component with no cross-cutting effect does not.
A practical calibration: a record is worth writing if someone might reasonably propose the opposite in a year. That framing also tells you what to put in it, because what they will need is the reasoning that rules their proposal out.
Supersede, never edit
Section titled “Supersede, never edit”The discipline that keeps the set trustworthy.
An ADR is a record of a decision at a point in time. Editing it to reflect a later change destroys exactly the property that makes the set valuable — you can no longer see what was believed when, which means you can no longer tell whether a decision was wrong or merely overtaken.
So when a decision changes: write a new record, mark the old one superseded with a forward link, and leave it in place. The set grows and never shrinks. A reader following the chain can see the sequence of beliefs, which is far more informative than a single current statement.
The one exception is correcting a factual error in the record itself — a wrong number, a misnamed component — which is a correction rather than a revision.
The use nobody plans for
Section titled “The use nobody plans for”Onboarding. A new engineer reading fifteen ADRs understands a system’s reasoning faster than from any other artifact, including a well-maintained HLD — because the HLD says what the system is and the ADRs say why it is not something else.
This matters more than it sounds for the organisational argument: Module 8 established that at a few hundred engineers nobody holds the whole picture. An ADR set is the cheapest available substitute for the person who used to.
What it costs
Section titled “What it costs”Writing one properly is about an hour, and the week always contains something more urgent. That is the entire reason practices fail to start.
The only defence that works in my experience of how these things go: the decision is not finished until the record exists. Treat it as part of deciding rather than as a follow-up task, which is the same discipline Module 8’s last topic applied to published reasoning.
Feeds the workbook
Section titled “Feeds the workbook”This is the core of your ADR set, and two rubric items land here: every record states consequences including the negative ones, and granularity is consistent across the set.
→ The practice starts now. The decisions started earlier. — ADR recovery