Architecture Decision Record: How to Write One That Lasts

An architecture decision record (ADR) is a short document that captures one significant technical decision: the context, the options you weighed, what you chose, and what follows from it. Martin Fowler describes it as a short document that explains a single decision relevant to a product or ecosystem. Written well, it answers the question every engineer eventually asks of old code: why on earth did we do it this way?

This guide covers what goes in an ADR, a template you can copy, how the lifecycle works, where teams go wrong, and how to keep a log alive past the first enthusiastic month.

TL;DR

• An ADR records one decision, its context, the alternatives considered, and the consequences. It is short, dated, and never rewritten after the fact.
• The real value is in the writing. Putting reasoning on paper before committing surfaces disagreement early and limits hindsight bias later.
• Most public ADRs are thin on alternatives and decision drivers, and many teams quit after a few records. Add a confidence level and a review date to make yours useful.
• The same format works for non-technical calls such as pricing, hiring and strategy.
• Keep records in the repo for code decisions. Use a shared decision journal when the decisions reach beyond engineering.

What an architecture decision record actually is

The format is usually credited to Michael Nygard, whose widely copied version has five parts: title, status, context, decision, and consequences, as one practitioner summary of the template puts it. The ADR community site defines an architectural decision as a justified design choice that addresses a functional or non-functional requirement that is architecturally significant.

Two words matter in that definition: justified and significant. An ADR is not a changelog. It does not record every library bump or naming convention. It records the choices that are costly to reverse and that a future engineer will want explained: the database, the messaging pattern, the auth model, the build-versus-buy call, the monolith-versus-services boundary.

The record is also meant to be stable. According to AWS Prescriptive Guidance, ADRs are kept as lightweight Markdown files in the code repository, typically in a doc/adr directory, and move through states such as Proposed, Accepted and Superseded. When a decision changes, you write a new record that supersedes the old one. You do not edit history.

Why the writing matters more than the document

Most teams assume the point of an ADR is the archive. Fowler and AWS both point somewhere else: the act of writing it. Drafting a record forces the author to name the options, and it exposes different mental models among the people involved before the decision is locked in. That is cheaper than discovering the disagreement six months into the build.

There is research behind the cost of skipping this. A controlled experiment on decision recovery notes that architectural decisions are regularly documented after the fact, and that missing or late documentation creates knowledge gaps. Reconstructing a rationale afterward means you are reconstructing it with knowledge of how things turned out, which is where hindsight bias does its damage.

There is also a teaching effect. Researchers including Rebekka Wohlrab argue that ADRs help seniors mentor juniors and let new hires understand the reasons behind a legacy codebase quickly. A new engineer who reads ten good records learns how your team weighs trade-offs, not just which tools it picked.

What to put in an ADR

Start with Nygard’s five fields, then add the ones most teams forget.

The last row is not part of the classic template, and it is the one we would add first. More on that below.

The gap in real-world ADRs

A text-mining study of more than 4,300 ADRs across 550 open-source projects found that records often capture technology and process choices, while explicit alternatives, decision drivers and long-term quality concerns stay under-documented. In plain terms: people write down what they chose, and skip why the other options lost. That is exactly the part a future reader needs.

A related finding in the original MADR format paper explains part of the reason. Less experienced engineers can hesitate over the options section because they fear criticism for alternatives they did not think of. The fix is cultural: treat a missing option as a teaching moment in review, not a failure by the author.

A copyable ADR example

Here is a compact record in the Markdown style most repos use. Adapt the wording, keep the structure.

0007. Use PostgreSQL for the event store instead of a dedicated streaming platform

• Status: Accepted (2026-10-02)
• Context: We expect about 200 events per second at launch and have two engineers who run Postgres in production. We have no on-call coverage for a new data platform.
• Options considered: (1) PostgreSQL with an append-only table. (2) A managed streaming service. (3) A self-hosted log broker.
• Decision: We will use PostgreSQL with an append-only events table and partition by month.
• Consequences: Faster delivery and no new operational surface. Harder to scale past a few thousand events per second, so we will revisit if sustained load passes that point. Replaying events for new consumers will be slower than with a log broker.
• Confidence: 75% that this holds through the next 18 months.
• Review date: 2027-04-01, or when sustained load passes 1,000 events per second.
• What would prove this wrong: Replay jobs regularly take longer than the nightly window.

Notice the last three lines. They turn a record of a choice into a falsifiable bet, which is the difference between documentation and learning.

The ADR lifecycle in practice

AWS recommends keeping review sessions short, about 10 to 15 minutes per record, and that is realistic. A workable flow looks like this:

1. Draft. The person closest to the problem writes the record as Proposed, including the options they rejected.
2. Review. Teammates comment asynchronously first, then settle open questions in a brief meeting. Dissent is invited, not tolerated.
3. Accept. The status changes, the date is stamped, and the record is merged alongside the code it affects.
4. Supersede, never edit. When circumstances change, write a new record that links back. The old one stays, marked Superseded.
5. Review the outcome. On the review date, check whether the consequences you predicted actually showed up.

Step five is the one almost nobody does, and it is where an ADR log becomes a learning system rather than a museum.

Where teams stall

Adoption is fragile. An analysis of public repositories found that about half of the repos that try ADRs contain only one to five records, which suggests many teams treat ADRs as an experiment and drop it. Four habits tend to separate teams that keep going:

• Attach it to a ritual that already exists. Review records in sprint retrospectives or architecture syncs instead of inventing a new meeting.
• Set a threshold. Agree on what counts as significant. A good rule: if reversing it would take more than a few weeks, write it down.
• Keep records short. A page or two. Fowler’s guidance is a couple of pages at most.
• Lint the format. Plain Markdown drifts. Tools such as madr-lint can enforce consistent statuses, ISO-8601 dates and cross-file integrity once you have dozens of records.

Architecture decision log versus ADR: is there a difference?

Not much. The log is the collection; the record is one entry. Some teams keep a simple index file listing every ADR with its number, title and status, so a reader can scan the whole history in a minute. If you are deciding between a folder of Markdown files and something heavier, the question is who needs to read and write the records. Engineers alone are well served by the repo. Product managers, founders and operations leads are not going to open a pull request to record a pricing decision.

Beyond architecture: any decision record

The MADR project, one of the most-used ADR templates, now describes itself as Markdown Any Decision Records: a lean template that began with architecture and grew into a way to capture any decision in a structured way. That matches what we see in practice. Pricing changes, hiring plans, vendor choices and go-to-market bets all benefit from the same discipline of context, options, decision and consequences.

Procurement is a good example. Buying infrastructure or managed services involves the same trade-offs as a technical design choice, and a guide like this IT procurement planning overview for growing firms shows how many moving parts sit behind a purchase that will constrain you for years. Those are decisions worth a record.

If you want a lighter starting point for non-engineering calls, our posts on one-paragraph decision documentation and a decision log template you can copy in ten minutes cover the basics.

Our perspective: an ADR is a bet with a receipt

We build a decision journal, so we read ADRs with a particular bias. Every significant decision is a bet: a commitment made with incomplete information, where the result depends on both the quality of the call and on luck. That idea comes from Annie Duke’s Thinking in Bets, and it changes what a good record looks like.

A standard ADR tells you what was decided and why it seemed right. It rarely tells you how sure the team was, what would change its mind, or when anyone will check. Without those, the log can only teach one lesson: whether the outcome was good. That is resulting, judging a decision by how it turned out, and it teaches the wrong things. A sound choice can lose to bad luck, and a careless one can get away with it.

So when we write or review an ADR, we add three things:

• A probability, not a feeling. “75% this holds for 18 months” can be scored later. “We feel good about it” cannot.
• A falsifier. The specific observation that would show the decision was wrong, written before anyone knows the outcome.
• A post-mortem that separates skill from luck. When the review date arrives, ask what was in the team’s control and what was not, and record one learning that cannot be quietly rewritten in hindsight.

Over a year, that produces calibration. You find out whether your 70%-confident decisions win about 70% of the time. Most teams that look for the first time discover they are more certain than their record justifies. That is useful to know before the next big call.

— Cesar

When a repo is enough and when it is not

Keep ADRs in the repository when the readers are engineers, the decisions are about code, and the review happens in pull requests. The versioning is free, and the record sits next to the thing it explains.

Look for something shared when any of these are true:

• Decisions cross functions: product, growth, finance, hiring.
• You want to track confidence and outcomes over time, not just store rationale.
• Non-engineers need to read and contribute without learning Git.
• You want a structured status review, with stages like idea, running and reviewing, instead of a static folder.

These are different jobs, and many teams reasonably use both: ADRs in the repo for design choices, a journal for the bets that shape the business.

Putting a decision journal behind your ADR habit

Betlog is a decision journal for founders, product leaders and small teams. Each bet records the hypothesis, expected outcome, a confidence level as a probability, the trade-offs you accepted, the metrics that will decide it, and what would prove it wrong. Bets move through Idea, Prioritized, Running, Reviewing and Decided, and close as Won, Killed or Inconclusive with a post-mortem that separates skill from luck. The result is a timestamped record that cannot be edited to flatter anyone later.

It is one plan: 39 USD per month or 390 USD per year. If your ADRs already cover the architecture and you want the same rigor for product, growth and strategy calls, take a look at Betlog.

For a stricter version of the habit, see our guides to a seven-field decision log and a nine-field decision audit that stops you rewarding luck.

FAQ

What is the difference between an ADR and design documentation?

Design documentation describes how a system works and is updated as it changes. An ADR describes why one specific choice was made at a point in time and is not edited afterward. When the choice changes, a new record supersedes the old one. That keeps the original reasoning intact for anyone studying it later.

How long should an ADR be?

One to two pages is the usual guidance. If a record needs more, the decision is probably several decisions, and you should split it. Brevity makes records more likely to be written and read, and it matches the 10 to 15 minute review window AWS suggests.

Which decisions deserve an ADR?

Write one when reversing the decision would be expensive or slow, when several reasonable options exist, or when a future teammate is likely to ask why. Skip routine choices that are easy to change. A simple test: if you would explain it to every new hire, record it.

Can I use the ADR format for non-technical decisions?

Yes. The MADR project now frames its template as a way to capture any decision. Pricing, hiring, vendor and strategy choices all fit context, options, decision and consequences. Adding a probability and a review date makes them easier to learn from.

Why do ADR logs get abandoned?

Usually because the practice is a side project with no home in the team’s rhythm. A public-repository analysis found that roughly half of repos with ADRs hold only one to five records. Tie review to an existing ceremony such as retrospectives, keep records short, and check outcomes on a set date.

Sources

• Architecture Decision Record, Martin Fowler
• Architectural Decision Records, ADR community site
• AWS Prescriptive Guidance: Using architectural decision records
• Basics of Architecture Decision Records (ADR)
• The supportive effect of patterns in architecture decision recovery
• Teaching effect of ADRs, Wohlrab et al.
• A Text Mining and Classification Approach for Analyzing Architecture Decision Records
• Markdown Architectural Decision Records: Format and Tool Support
• ADR Study Dataset, Hagenberg
• madr-lint
• Markdown Any Decision Records

Recommended

• Founders: One Paragraph Decision Documentation and Copyable ADRs
• Decision Log Template for Project Managers You Can Copy in 10 Minutes
• Preserve Institutional Memory: Log the ‘Why’ in 2 Minutes for Founders
• Argument Mapping for Founders: 5–10 Minute Decision Logs