Architecture Decision Records: Why and How to Use ADRs
Vote for this post
Click the arrows to vote • 1 vote per logged in user
Login to Vote
Architecture Decision Records: Why and How to Use ADRs
Every software project accumulates architectural decisions. Why did we choose this database? Why is the service split this way? Why was that library picked over the obvious alternative? Without a record, the answers live only in the heads of the people who were there – and leave with them when they move on. Architecture Decision Records solve this problem with almost no overhead.
An ADR captures not just what was decided, but why – the context, the alternatives considered, and the consequences accepted.
What Is an ADR?
An Architecture Decision Record is a short document that captures a single significant architectural decision: the context that made a decision necessary, the options that were considered, what was chosen, and what consequences follow from that choice. ADRs are typically stored as plain text or Markdown files directly in the project repository – alongside the code they describe, versioned with it, and visible to everyone working on the project.
The concept was formalised by Michael Nygard in 2011, and the format has been widely adopted in software teams ever since. The appeal is simplicity: an ADR is not a specification document or an architecture diagram. It is a lightweight record of a moment of decision, written at the time the decision was made, when the context and reasoning are still fresh.
Why ADRs Matter
Knowledge Transfer
When a team member leaves or a new developer joins, architectural context is the hardest thing to hand over. ADRs make that context explicit. A new developer reading the ADR log understands not just what the codebase looks like, but why it ended up that way – which decisions were deliberate and which constraints were real at the time.
Avoiding Revisited Debates
gaaWithout a record, the same architectural discussions happen repeatedly as team membership changes. ADRs close that loop. When someone proposes revisiting a past decision, the team can read the original reasoning, understand what was considered, and evaluate whether the context has genuinely changed – rather than relitigating from scratch.
Audit and Governance
For teams working under compliance or governance requirements, ADRs provide a traceable record that architectural choices were made deliberately and reviewed. They demonstrate that alternatives were weighed, that standards were considered, and that decisions were not made by default or oversight.
The Structure of an ADR
Most ADR formats follow the same five fields, which Nygard's original template established. The exact wording varies between teams, but the underlying structure is consistent across nearly every implementation in use today.
| Field | What It Contains |
|---|---|
| Title | A short, descriptive name for the decision. Often numbered: ADR-001: Use PostgreSQL as the primary database. |
| Status | The current state: Proposed, Accepted, Deprecated, or Superseded (with a reference to the ADR that replaced it). |
| Context | The forces and constraints at play when the decision was made – the problem, the pressures, the non-negotiables. This is the most valuable section for future readers. |
| Decision | What was chosen, stated clearly and without ambiguity. Not a justification – that belongs in Context. Just the decision itself. |
| Consequences | What becomes easier, what becomes harder, and what new decisions this one creates. Both positive and negative consequences should be recorded honestly. |
An ADR is typically a short Markdown file stored in an adr/ or docs/decisions/ folder within the project repository.
ADRs and Agile Teams
ADRs fit naturally into Agile workflows because they impose almost no overhead. Writing an ADR takes fifteen to thirty minutes at the point when the decision is being made and the context is already in the team's head. That investment pays back every time a new sprint begins with a question about why something works the way it does – and someone can answer it by pointing to a file rather than reconstructing the reasoning from memory.
The most effective teams write ADRs at decision time, not retrospectively. A decision documented a month after it was made loses the context that makes it useful. The format works precisely because it is written while the reasoning is fresh, committed alongside the code it governs, and never revised retroactively – if a decision changes, a new ADR is written that supersedes the old one. The history of the project's thinking is preserved, not overwritten.
The Real Value Is the Context, Not the Decision
Anyone reading the codebase six months later can see what was decided – the code itself is the record of that. What they cannot see, without an ADR, is why it was decided: what alternatives were rejected, what constraints made the obvious choice impossible, what the team accepted as a trade-off. That context is what disappears when people leave, and what ADRs preserve.
Teams Without ADRs vs. Teams With ADRs
- New developers spend days asking why things are built the way they are – and get different answers from different people
- The same architectural debate is relitigated every time a new team member arrives with a different background
- A decision is reversed because nobody remembers why it was made – and the original problem resurfaces six months later
- Compliance reviews require tracking down the original author to explain an architectural choice made two years ago
- A new developer reads the ADR log on day one and understands the key trade-offs the team has made without a single meeting
- A proposed change triggers a review of the relevant ADR – the team evaluates whether the original context still holds, rather than debating from scratch
- When a decision is superseded, a new ADR records why – the full history of the team's thinking is preserved in version control
Further Reading
The resources below include Michael Nygard's original article, the most widely used ADR tooling, and the scrum-master.org article that this post draws from.
- Michael Nygard – Documenting Architecture Decisions (the original 2011 article)
- adr.github.io – ADR tools, templates, and community resources
- Ahmed Ben Salem – Architecture Decision Record: How and Why Use ADRs? (scrum-master.org) Note: Thanks to Ahmed upon which this shorter blog has been based.
Leave a Comment