An ADR records why, not what.
The code shows what was decided. Only the record shows what was rejected, and why.
An architecture decision record, or ADR, is a short document capturing one significant decision: the context that forced it, the decision itself, the alternatives that were considered and rejected, and the consequences accepted along with it. The convention, introduced by Michael Nygard in 2011, is that ADRs are immutable once accepted. A decision that gets reversed is not edited; a new ADR supersedes it, so the record shows the reasoning history rather than only the current state.
Immutability is the whole mechanism
Editing an accepted ADR destroys the thing it exists to preserve. The value is not knowing that you use Postgres, which is visible from the repository, but knowing that in 2023 you considered a document store, rejected it for a specific reason, and what that reason was. Supersede rather than edit and the file becomes a record of reasoning. Edit it and it degrades into documentation that says what is already obvious.
What makes a decision worth recording
The test is whether reversing it later would be expensive. Choosing a datastore, a boundary between services, a synchronous or asynchronous integration, a language for a new component: these are hard to undo and their reasoning is forgotten fast. Choosing a linting rule is not. Teams that record everything stop reading them, which is the usual failure mode.
Why it belongs beside the code
ADRs are conventionally kept as markdown in the repository, typically under docs/adr, so they are versioned with the code they describe and travel with a clone. A decision record in a wiki decays because it is one more place to remember; one in the repository shows up in a diff when the code it justifies changes.
Where an agent fits
The context section is the part people skip, because writing it means reconstructing what was true at the time. An agent with the repository and its history available can draft that from the actual change, leaving the judgement, what was rejected and what consequence you accepted, to the person who made the decision. That is the half that cannot be automated and should not be.
The conventional sections
| Section | Holds |
|---|---|
| Title | A short noun phrase naming the decision |
| Status | Proposed, accepted, deprecated or superseded |
| Context | The forces that made a decision necessary |
| Decision | What was chosen, in the active voice |
| Consequences | What becomes easier and what becomes harder |
Questions
Related
- What Is Architecture Drift?Nobody decides to let the diagram go stale. It goes stale because nothing in the process notices.
- What Is Diagram as Code?Text in, picture out. Which means the layout engine, not you, decides what it looks like.
- What Is a Sequence Diagram?Time runs down the page. That single convention is what the diagram is for.
- What Is Spec-Driven Development?Review the plan, not the pull request. The plan is a page; the pull request is a thousand lines.
Last updated