Someone joins the team, reads the code, and asks why it uses an unusual approach for something with an obvious standard solution. Nobody knows. The people who decided have moved on, and the decision looks arbitrary — so it gets changed, and three months later the original constraint reappears as an incident.
An architecture decision record prevents that specific and very common waste.
What changed in 2026
- Onboarding value became the main argument. With teams changing composition faster, the case for written rationale shifted from documentation hygiene to practical onboarding speed.
- Records became context for AI assistants. Coding agents reading a repository benefit from stated rationale in the same way new engineers do, which gave ADRs a second audience.
- Lightweight formats won. Short, structured records displaced heavyweight design documents, which were written less often and read less still.
- Supersession became better understood. Treating records as immutable history rather than living documentation clarified how to handle changed decisions.
What a record contains
| Section |
Content |
| Title and date |
What was decided and when |
| Status |
Proposed, accepted, superseded by which record |
| Context |
The situation, constraints, and forces at the time |
| Decision |
What was chosen, stated plainly |
| Alternatives considered |
What else was evaluated and why it was rejected |
| Consequences |
What this makes easier and harder |
Context and alternatives carry the value. The decision itself is usually visible in the code — you can see which database was chosen. What you cannot see is that the team had a two-week deadline, existing operational expertise in one system, and a data volume projection that turned out to be wrong. That is what makes a decision comprehensible later, and it is what tells a future reader whether the reasoning still applies.
The consequences section is the honest one. Every architectural decision makes some things easier and others harder, and writing the harder part down at the time is far more credible than reconstructing it later.
Keeping them useful
Keep them short. A page is enough. Long records do not get written, and when they do they do not get read.
Store them with the code. In the repository, in version control, reviewable in a pull request alongside the change they describe. A wiki elsewhere becomes stale and undiscoverable.
Supersede rather than edit. When a decision changes, write a new record referencing the old one and mark the old one superseded. Editing history destroys the thing that makes the record valuable — knowing what was true when.
Write them for consequential decisions. Choosing a database, a communication pattern between services, an authentication approach, a deployment model. Not for every library choice. Mandating a record for everything produces perfunctory records and trains people to skip reading them.
Write them at the time. Reconstructed rationale is rationalization. The value comes from capturing the actual reasoning while the constraints are live.
They pair well with the debt argument in tech debt tracking, since a record explaining why a shortcut was taken is exactly what makes the eventual cleanup case.
Common mistakes
- Editing accepted records. Destroys the historical value.
- Long design documents instead. Written rarely, read less.
- Storing them outside the repository. Undiscoverable and stale.
- Requiring one for every decision. Perfunctory records, ignored process.
- Omitting rejected alternatives. The most useful section, most often skipped.
- Writing them retrospectively. Produces justification rather than reasoning.
FAQ
When should a decision get a record?
When reversing it would be expensive, when the choice is non-obvious, or when someone will ask why later. Those overlap heavily.
Who writes them?
Whoever made the decision, usually as part of the pull request implementing it.
What if the decision was wrong?
Leave the record and add a superseding one explaining what changed. A record of a decision that turned out badly is more instructive than one that turned out well.
Do they replace design documents?
For discrete decisions, largely. Larger design work may still warrant a longer document, with ADRs recording the specific choices within it.
Where to go next
For related modelling practice, read the C4 model explained and event storming guide. For the debt these decisions sometimes create, tech debt tracking.