Architecture Decision Records: Why and How to Use ADRs

By markjc Mon Jul, 2026 (0)

Architecture Decision Records: Why and How to Use ADRs

0

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.

Architecture Decision Records – capturing the why behind technical choices

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

gaa

Without 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.

Example ADR document structure showing the five fields in a Markdown file

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