Architecture Decision Records

Capture the why behind significant decisions in short, immutable records future teams can read.

“It's better to avoid either blind acceptance or blind reversal.”
— Michael Nygard, “Documenting Architecture Decisions” (2011)

Each significant decision gets a short record of why, and later decisions supersede it rather than rewrite it.

To an executive

People move on and the reasons for big decisions go with them. A short written record stops us repeating old debates or undoing choices that were sound.

To an engineer

Write a short numbered record per significant decision, with context, choice and consequences. Keep it in the repository and supersede it rather than rewriting it.

The idea

Michael Nygard proposed recording each architecturally significant decision as a short document with a title, context, decision, status and consequences. Records are numbered in sequence, kept with the code, and never rewritten: when a decision is reversed, the old record stays and is marked superseded.

His aim was to prevent two failure modes in people who join later: blindly accepting past decisions they don't understand, or blindly reversing them. Both happen when the reasoning has been lost. Nygard suggested each record be one or two pages at most.

Why it works

The code shows what, never why. Anyone can read how a system is built. The forces, constraints and rejected options vanish unless someone writes them down at the time.

Short records get written. Large architecture documents go stale and unread. A page per decision is cheap enough to write during the work and quick enough to read before changing something.

Immutability keeps history honest. Because records are superseded rather than edited, you can see what was decided, when, and what replaced it, without anyone rewriting the past to look wiser.

Consequences make trade-offs visible. Listing the negative and neutral effects, not only the benefits, tells future readers which pain was accepted on purpose.

Where it applies

One-way-door decisions, such as data stores, public contracts, security boundaries and platform choices.
Design reviews, where an ADR gives reviewers a concrete proposal to challenge.
Team changes and onboarding, where newcomers need the reasoning behind what they inherit.
Audits and incident reviews, where people ask why the system is the way it is.

How to apply

Write the context neutrally: the forces at play, including technical, political and project constraints.
State the decision in active voice, starting with "We will…", and note the main alternatives considered.
List the consequences: positive, negative and neutral.
Keep it in the repository, numbered, beside the code it affects, and review it like code.
Supersede, don't edit. When the decision changes, write a new record and link the two.

Example scenario

A new lead wanted to replace an event store with a relational table, seeing it as needless complexity. Before starting, the team searched the repository's decision records.

The ADR showed the event store had been chosen to meet a regulatory audit requirement, which the table would not satisfy, and that a simpler option had been considered and rejected for that reason. The change was dropped in a five-minute conversation, and the lead wrote a short new record noting the requirement was still in force.

Questions to ask

Will someone joining in two years understand why we did this from what we write today?
Have we recorded the alternatives we rejected and the consequences we accepted?
Which earlier decision does this one supersede, and have we marked it?

When not to use it

Easily reversible choices, such as library versions or folder layout, where the cost of writing a record exceeds the cost of getting it wrong.
Decisions already captured elsewhere in a form people actually read, such as a well-maintained RFC process.

How it misleads you

Writing ADRs for trivial choices, or after the fact to justify decisions already made. A record written to defend a decision hides the real trade-offs. Keep them few, honest and timely, and remember that a record is not the decision: the conversation that produced it matters more.