What Is an Architecture Decision Record (ADR)?
A short note, written the moment a big decision is made, explaining what was decided and why. That is the whole idea. Simple to describe, and yet it quietly saves teams from repeating the same arguments and the same mistakes, over and over again.
The Big Idea, in One Breath
A ship’s captain keeps a logbook. Every important decision gets a short, dated entry. Years later, a completely new crew can read it and understand. An ADR is that logbook entry for software.
Picture the captain of a ship keeping a logbook. Every time something important happens — a storm forces a change of course, a decision is made to take on extra supplies — the captain writes a short, dated entry: what happened, what was decided, and why. Years later, a completely different crew can open that logbook and instantly understand decisions they weren’t even present for.
Software teams face the same challenge without the ocean. Big decisions get made all the time — which database to use, whether to split a service in two, why a particular security rule exists — and without a logbook of their own, that reasoning quietly disappears the moment the meeting ends. An Architecture Decision Record, or ADR, is exactly that logbook entry: a short, dated note capturing one important decision, written down while the reasoning is still fresh.
Think of a family recipe card tucked in a kitchen drawer, with a handwritten note in the corner: “Grandma always used less sugar because Dad doesn’t like things too sweet.” That one sentence explains a choice that would otherwise look like a mistake to anyone following the recipe years later. An ADR is that handwritten note, but for a software decision instead of a dessert.
What an ADR Really Is
A short document capturing one architecturally significant decision — its context, choice, and consequences. Popularised in 2011, still one of the most widely adopted habits in software teams.
An Architecture Decision Record is a short, focused document that captures one significant architectural decision — the situation that led to it, the choice that was made, and the consequences that followed. It is usually just a page or two, written in plain language, and stored somewhere easy to find later.
The word “architecturally significant” matters here. Not every decision deserves an ADR — choosing a variable name doesn’t need one. An ADR is reserved for decisions that shape the system in a lasting way: which database technology to use, how two services should communicate, whether to accept a security trade-off for the sake of speed.
If someone asks “is there an ADR for this?”, they are really asking: “Did someone already write down why we do it this way, so I don’t have to guess or track down whoever remembers?”
The idea was popularised in 2011 by software engineer Michael Nygard, who noticed a very human problem: new team members were constantly baffled by decisions nobody could explain anymore. His proposed fix — a simple, lightweight written record for each important decision — has since become one of the most widely adopted habits in modern software teams.
Why Teams Write Them
Verbal reasoning fades fast. Three quiet reasons a written record earns its keep long after the meeting that produced it is forgotten.
Most architectural decisions get made verbally — in a meeting, a chat thread, or a hallway conversation. That works fine in the moment, but it fades fast. A month later, nobody quite remembers who suggested what, or why the losing option was rejected. An ADR exists to catch that reasoning before it evaporates.
There is a quieter benefit too: the simple act of writing an ADR forces clearer thinking. It is much harder to hand-wave a weak decision when you have to write down the alternatives you considered and explain, in plain sentences, why you rejected them.
What’s Actually Inside One
Five simple parts — title, status, context, decision, consequences — are the beating heart of nearly every ADR ever written, regardless of format.
The classic ADR format, based on Michael Nygard’s original proposal, keeps things deliberately short — five simple parts that together tell the whole story of a decision.
A short, clear name
A brief phrase describing the decision itself, not the problem — like “Use PostgreSQL for the order service.”
Where it stands
Proposed, accepted, deprecated, or superseded — a quick label showing whether the decision is still active.
What led here
The situation, pressure, or problem that made this decision necessary in the first place, described fairly and neutrally.
What was chosen
A clear, confident statement of the choice made — written as “we will,” not “we might.”
What follows
The trade-offs, both good and bad, that come from this decision — nothing is ever entirely free.
Some teams add small extras — links to related decisions, names of people involved, or dates — but the five parts above form the true heart of almost every ADR ever written, regardless of format.
The Life of a Decision
Proposed. Accepted. Superseded. Deprecated. One quiet rule keeps the whole collection honest: never edit an accepted ADR — supersede it with a new one instead.
An ADR isn’t a static document — it moves through a small number of clear stages over its lifetime, much like a proposal moves from an idea to a law. Understanding this lifecycle is what keeps a whole collection of ADRs trustworthy instead of confusing.
This “never edit, only supersede” habit is one of the most important rules in the whole practice. If a decision changes, the right move isn’t to rewrite the old ADR — it is to write a brand-new one, mark the old one as superseded, and link the two together. That way, anyone reading the old record still sees exactly what was decided at the time, and why it later changed.
A Worked Example
A short, realistic ADR — roughly a paragraph per part — that shows exactly what “finished” looks like. Brevity is intentional; the fifteen-minute ADR gets used, the ten-page report doesn’t.
Reading about the format only goes so far — it helps to see a short, realistic example pulled together to show what a finished ADR actually looks like in practice.
Title
Use a message queue for order confirmation emails
Context
Sending confirmation emails directly during checkout was occasionally slowing down the checkout process itself, and a failed email server once caused failed orders. The team needed a way to send emails reliably without blocking the checkout flow.
Decision
We will place email requests onto a message queue during checkout, and a separate background worker will send them independently.
Consequences
Checkout no longer waits on email delivery, and a slow email server can no longer break an order. In exchange, emails may arrive a few seconds later than before, and the team now needs to monitor the health of the queue itself.
Notice how short this is — barely more than a paragraph for each part. That brevity is intentional. An ADR that takes fifteen minutes to write and two minutes to read gets used. A ten-page decision report usually doesn’t.
ADRs vs. Other Kinds of Documentation
General documentation describes the destination. ADRs describe the individual turns taken to get there — and why each turn was chosen.
ADRs are just one piece of a bigger documentation picture, and it helps to know where the boundaries sit.
| Question | ADR | General Architecture Docs |
|---|---|---|
| Covers what? | One specific decision | The whole system’s structure |
| How long is it? | Usually one or two pages | Can span many pages or diagrams |
| How often is it written? | Every time a significant decision is made | Updated periodically as the system evolves |
| Is it ever edited later? | No — superseded instead of changed | Yes — kept current through regular updates |
General documentation describes the destination. ADRs describe the individual turns taken to get there — and why each turn was chosen.
When (and When Not) to Write One
A useful test: would a thoughtful engineer, joining a year from now, be confused by this decision without any explanation? If yes, write an ADR.
Not every choice deserves the ceremony of a written record. A useful test: would a thoughtful engineer, joining the project a year from now, be confused or surprised if they stumbled onto this decision without any explanation? If yes, it is probably worth an ADR.
Good Candidates
- Choosing a database, messaging system, or major framework
- Deciding to split, merge, or restructure services
- Accepting a trade-off between security, speed, and cost
- Rejecting a popular or “obvious” approach for a specific reason
Usually Not Needed
- Naming conventions for individual variables
- Minor bug fixes with no lasting structural impact
- Personal formatting or styling preferences
- Temporary experiments not yet meant to be permanent
When in doubt, a short rule of thumb helps: if reversing this decision later would be expensive, risky, or slow, it is architecturally significant enough to deserve a record.
Where They Live
An ADR nobody can find is barely better than no ADR at all. Four common homes — and one linking habit — keep them genuinely useful.
An ADR that nobody can find is barely better than no ADR at all. Most teams settle on one of a few common homes for their growing collection of records.
Inside the repository
Stored as plain text files right next to the code they describe, so both move and change together over time.
Shared knowledge space
Kept in a wiki or internal knowledge base, making them easy for non-developers to browse as well.
Purpose-built viewers
Small tools exist purely to list, search, and publish a project’s growing collection of decision records.
One simple index
Many teams keep a single index page listing every ADR by number, title, and current status, for quick scanning.
Whatever the chosen home, a linking habit makes ADRs far more useful in practice: leaving a short reference near the relevant piece of code, pointing back to the ADR that explains why it exists. Without that link, even a well-written ADR can sit forgotten, unread by the very people who need it most.
Benefits and Trade-offs
ADRs are lightweight but not entirely free. Understanding both sides helps a team adopt them sensibly — the writing is cheap; the ongoing discipline is where the real work lives.
ADRs are a lightweight habit, but they are not entirely free — and understanding both sides helps a team adopt them sensibly.
Strengths
- Captures reasoning while it is still fresh, not months later from memory
- Speeds up onboarding dramatically for new team members
- Reduces repeated arguments over decisions already settled once
- Creates an honest historical record, including decisions that didn’t work out
Trade-offs
- Requires ongoing discipline — easy to start, easy to quietly abandon
- Adds a small amount of upfront writing time to each big decision
- Provides little value if never linked from the code or read by anyone
- Can become clutter if used for every trivial choice, not just big ones
Teams that stick with the habit almost always say the same thing: the writing itself is the cheap part. The hard part is the discipline to keep doing it, decision after decision, long after the initial enthusiasm fades.
Common Pitfalls
Three recurring traps — late writing, quiet editing, and ADRs nobody reads — each of which quietly turns a helpful habit into paperwork.
Writing Them Too Late
An ADR written six months after the decision, from fading memory, tends to lose the honest tension of the original discussion. The best ADRs are written within days of the actual decision, while the reasoning is still sharp.
Editing Instead of Superseding
Quietly rewriting an old ADR to match a new decision erases useful history and can confuse anyone who read the earlier version. A new, linked record almost always serves the team better.
Nobody Reads Them
An ADR buried in a folder nobody opens provides no value at all. Linking ADRs from the code, and mentioning them naturally during reviews, is what keeps the habit genuinely useful rather than symbolic.
Turning ADRs into a bureaucratic approval gate that slows teams down. The goal is a quick, honest note — not a lengthy report that discourages anyone from ever writing one.
Key Takeaways
If you remember only these six ideas from the whole guide, you’ll be able to introduce, defend, and sustain the ADR habit anywhere.
Remember This
- One decision, dated. An ADR is a short, dated record capturing one significant architectural decision, its context, and its consequences.
- Five parts. The classic format — title, status, context, decision, consequences — is kept short on purpose.
- Never rewrite. Decisions move through a lifecycle (proposed, accepted, superseded, deprecated); old records are never rewritten.
- Save it for significant. Not every choice needs one; save ADRs for decisions that would be expensive or confusing to reverse later.
- Findable and linked. ADRs are most useful when they are easy to find and linked directly from the code they explain.
- The habit is the value. The real value isn’t the document itself — it is the habit of capturing reasoning before it quietly disappears.