An architecture decision record (ADR) is a short document that captures one important technical decision: the problem, the options you looked at, what you chose, and what that choice means for the team. This guide gives you a copy-ready ADR template in Markdown, a complete worked example, and a small tested script that creates numbered ADR files in your repository.
About the examples: the template and the helper script were run on 20 November 2026 on macOS 27.2, with both the system bash 3.2 and bash 5.2, inside a test Git repository. The worked example is a realistic but invented decision; the team, ticket numbers and figures in it are made up for illustration.
TL;DR
- Write an ADR for each decision that is hard to reverse or that people will later ask “why did we do this?” about.
- Keep one decision per file, about one page long, stored in the repository next to the code (for example
docs/adr/). - Use a fixed structure: status, context, decision drivers, options, decision, consequences.
- Number ADRs in sequence and never edit an accepted one. If the decision changes, write a new ADR that supersedes it.
What Is an Architecture Decision Record?
An ADR records a single architecturally significant decision and the reasoning behind it. The format was popularised by Michael Nygard’s 2011 post, which proposed five sections: Title, Context, Decision, Status and Consequences. The idea is simple: code shows what the system does, but not why it was built that way or what alternatives were rejected. Six months later, a new engineer who wants to replace the database should be able to read the ADR and understand the forces that drove the original choice.
A collection of ADRs is often called a decision log. Martin Fowler’s entry on ADRs (updated March 2026) recommends keeping each record short, typically a single page, and storing the records in the source repository in a lightweight markup such as Markdown.
ADRs are not a replacement for architecture documentation. An architecture document describes the current shape of the system; ADRs explain how it got that way, one decision at a time. Our guide on how to write software architecture documentation covers the larger document, and you can link each ADR from the relevant section of it.
When Should You Write an ADR?
Write one when a decision meets at least one of these tests:
- Hard to reverse. Choosing a database, a message broker, a programming language, a cloud provider, or an API style.
- Affects more than one team. Shared libraries, authentication approach, event formats, service boundaries.
- Has real trade-offs. You picked one option knowing it makes something else harder.
- Will be questioned later. If you can imagine someone asking “why on earth did we do this?”, write it down now.
Do not write ADRs for routine choices that are easy to change, such as a variable naming rule or a minor library upgrade. Too many trivial ADRs bury the important ones.
Architecture Decision Record Template (Markdown)
This template combines Nygard’s original sections with the extra fields from MADR (Markdown Architectural Decision Records), whose current version is 4.0.0 (released September 2024): decision drivers, considered options, pros and cons, and a confirmation step. Copy it into docs/adr/template.md. The {{NUMBER}}, {{TITLE}} and {{DATE}} placeholders are filled in by the script further down; replace the angle-bracket text by hand.
# ADR-{{NUMBER}}: {{TITLE}}
- Status: Proposed
- Date: {{DATE}}
- Deciders: <names or team>
- Consulted: <people whose input you asked for>
- Informed: <people who need to know>
- Supersedes: <ADR number, or "none">
## Context
What is the problem, and why does it need a decision now?
Include the forces at play: requirements, constraints, deadlines,
team skills, and anything that rules options in or out.
## Decision drivers
- <driver 1, e.g. "must support 5,000 writes per second">
- <driver 2>
## Considered options
1. <option A>
2. <option B>
3. <option C>
## Decision
We will <chosen option>, because <the main reasons, tied to the drivers>.
## Consequences
Positive:
- <what gets easier>
Negative:
- <what gets harder, what you now have to maintain>
Neutral / follow-up:
- <work this decision creates, with owners>
## Pros and cons of the options
### <option A>
- Good, because <...>
- Bad, because <...>
### <option B>
- Good, because <...>
- Bad, because <...>
## Confirmation
How you will check the decision was carried out and still holds
(a review, a test, a metric, a date to revisit).
## Links
- <tickets, design docs, benchmarks, related ADRs>What Goes in Each Section
| Section | What to write | Common mistake |
|---|---|---|
| Status | Proposed, Accepted, Deprecated or Superseded (with the number of the ADR that replaces it) | Leaving it on Proposed forever after the decision is made |
| Date and people | When it was decided; who decided, who was consulted, who just needs to know | No names, so nobody knows whom to ask later |
| Context | The problem and the forces at play: requirements, constraints, deadlines, team skills | Describing the solution here instead of the problem |
| Decision drivers | The criteria the options are judged against | Drivers written after the choice to justify it |
| Considered options | Every serious option, including “do nothing” if it is realistic | Listing only the winner plus a straw man |
| Decision | One clear sentence starting “We will…”, then the main reasons | Vague wording such as “we prefer” or “we may” |
| Consequences | What gets easier, what gets harder, and the follow-up work it creates | Listing only the positives |
| Pros and cons | Short good/bad bullets per option, tied to the drivers | Pages of feature comparison copied from vendor sites |
| Confirmation | How you will check the decision was carried out and still holds | Skipping it, so nobody ever revisits the decision |
Write the context so a reader who was not in the meeting understands it. Use full sentences, define acronyms once, and link to the tickets, benchmarks or design documents that hold the detail instead of pasting them in.
Architecture Decision Record Example
Here is the template filled in for a realistic decision: a checkout team choosing where to store order data after splitting the checkout service out of a monolith. Notice how every option is judged against the same four drivers, and how the consequences include the downsides the team is accepting.
# ADR-0002: Store order data in PostgreSQL
- Status: Accepted
- Date: 2026-11-20
- Deciders: Checkout team (Priya, Tom, Elena)
- Consulted: Data platform team, SRE on-call lead
- Informed: Payments team, Analytics team
- Supersedes: none
## Context
The checkout service is moving out of the monolith. It needs its own
store for orders, order lines and payment attempts. An order and its
payment attempt must be written together or not at all: today a crash
between the two writes leaves about 30 "paid but no order" tickets a
month for support to fix by hand.
The service must be live by the end of Q1. The team of four has run
PostgreSQL in production for three years and has no MongoDB experience.
Analytics needs to query orders with SQL every night.
## Decision drivers
- Atomic writes across orders and payment attempts
- Nightly SQL reporting without an export pipeline
- The team can operate it on-call from day one
- Ready before the Q1 deadline
## Considered options
1. PostgreSQL (managed, same setup as the user service)
2. MongoDB
3. DynamoDB
## Decision
We will store order data in PostgreSQL, because it gives us multi-row
transactions for orders and payment attempts, Analytics can query it
with SQL directly, and the team already runs it on-call.
## Consequences
Positive:
- Order and payment writes happen in one transaction, so the
"paid but no order" tickets should stop.
- Analytics reads a replica with SQL; no export job to build.
Negative:
- Schema changes need migrations; we must add a migration step to CI.
- If order volume grows past one primary, we will need partitioning
or sharding later. We accept this; current volume is far below it.
Neutral / follow-up:
- Tom adds the migration tool and CI step (ticket CHK-412).
- Elena sets up the read replica for Analytics (ticket DATA-88).
## Pros and cons of the options
### PostgreSQL
- Good, because transactions span orders and payment attempts
- Good, because the team and on-call runbooks already exist
- Bad, because scaling writes past one primary needs extra work
### MongoDB
- Good, because flexible documents suit changing order fields
- Bad, because nobody on the team has run it in production
- Bad, because Analytics would need an export to a SQL store
### DynamoDB
- Good, because it scales writes without managing servers
- Bad, because access patterns must be designed up front, and
ad hoc reporting queries do not fit it well
- Bad, because it adds a second database technology to support
## Confirmation
- "Paid but no order" tickets are tracked weekly; we expect zero
by the end of the first full month after launch.
- Revisit this ADR if peak writes reach 50% of the primary's
tested capacity.
## Links
- CHK-398: checkout service extraction epic
- ADR-0001: Record architecture decisionsA few things make this example work:
- The context states a measurable problem (“about 30 tickets a month”), so the confirmation step has something to check.
- Each driver shows up again in the pros and cons, so the reader can trace why PostgreSQL won.
- The negative consequences are honest: migrations in CI and a future scaling limit. Hiding them would only surprise the next team.
- Follow-up work has owners and ticket numbers, so the decision turns into action.
How to Write an ADR, Step by Step
- Create the file early. Open the ADR with status Proposed as soon as the question comes up, not after the decision is made. It becomes the place where options are compared.
- Write the context and drivers first. Agree on the problem and the criteria before arguing about solutions.
- List the options and their pros and cons. Ask the people who favour each option to write its case.
- Review it like code. Open a pull request with the ADR and ask the deciders and consulted people to comment there.
- Record the decision. Fill in the Decision and Consequences sections, set the status to Accepted, and merge.
- Link it. Reference the ADR from the code, the architecture document and the tickets it created.
Reviewing ADRs as pull requests keeps the discussion in one place and gives you a dated history for free. If your team is new to reviewing docs this way, see our guide to version control and documentation collaboration.
Where to Store ADRs and How to Number Them
Nygard suggested keeping ADRs in the project repository under doc/arch/adr-NNN.md; Fowler mentions doc/adr. Many teams use docs/adr/ or docs/decisions/. The exact path matters less than three rules:
- One decision per file, named with a number and a short slug, for example
0002-use-postgresql-for-order-data.md. - Numbers go up in sequence and are never reused, even if an ADR is rejected.
- Files live next to the code they affect, so they are versioned, reviewed and searched with it.
A small script to create the next ADR
This Bash script finds the highest existing number in docs/adr/, adds one, turns the title into a file-name slug, and fills the template. Save it as new-adr.sh in the repository root and run chmod +x new-adr.sh.
#!/usr/bin/env bash
# Create the next numbered ADR from docs/adr/template.md
# Usage: ./new-adr.sh "Use PostgreSQL for order data"
set -euo pipefail
dir="docs/adr"
title="$*"
[ -n "$title" ] || { echo "Usage: $0 \"Decision title\"" >&2; exit 1; }
last=$(ls "$dir" | grep -E '^[0-9]{4}-' | sort | tail -n 1 | cut -c1-4 || true)
next=$(printf "%04d" $((10#${last:-0} + 1)))
slug=$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')
file="$dir/$next-$slug.md"
sed -e "s|{{NUMBER}}|$next|" -e "s|{{TITLE}}|$title|" -e "s|{{DATE}}|$(date +%F)|" \
"$dir/template.md" > "$file"
echo "Created $file"Running it in our test repository produced this output:
$ ./new-adr.sh "Record architecture decisions"
Created docs/adr/0001-record-architecture-decisions.md
$ ./new-adr.sh "Use PostgreSQL for order data"
Created docs/adr/0002-use-postgresql-for-order-data.md
$ ./new-adr.sh
Usage: ./new-adr.sh "Decision title"
$ ls docs/adr
0001-record-architecture-decisions.md
0002-use-postgresql-for-order-data.md
template.mdIt also worked with the older bash 3.2 that ships with macOS. One limitation: the title is inserted with sed, so avoid the | character in titles. Dedicated command-line tools for creating and linking ADRs also exist; adr.github.io lists several, along with other templates.
How to Supersede or Deprecate an ADR
Once an ADR is accepted, treat it as immutable. Fowler is direct about this: an accepted ADR should not be reopened or changed, it should be superseded. If the checkout team later moves orders to a different store, they write a new ADR (say ADR-0009) and change only one line of the old one:
- Status: Superseded by ADR-0009The new ADR’s Supersedes field points back to ADR-0002. Anyone reading the old record now sees that it no longer applies and where to find the current decision, while the original reasoning stays intact. Use Deprecated instead when a decision simply stops applying, for example because the component it covered was removed.
ADR Best Practices and Common Mistakes
- Keep it to about one page. If it grows longer, move benchmarks and research to linked documents.
- Write for a future reader. Assume they know the codebase but were not in any of the meetings.
- Record rejected options. The options you did not choose are often the most useful part a year later.
- Do not backfill everything at once. Start with the next real decision. Write retroactive ADRs only for decisions people keep asking about.
- Make the first ADR about ADRs. ADR-0001 “Record architecture decisions” tells the team the practice exists and where files live.
- Do not confuse ADRs with requirements. A requirement says what the product must do; an ADR says how the team chose to build it. A product requirements document is the right home for the first.
ADRs sit alongside other short, structured documents that engineering teams keep in the repository, such as runbooks for on-call procedures. If you want a dedicated tool to manage diagrams and decision logs together, our list of software architecture documentation tools compares the main options.
Conclusion
An architecture decision record takes about half an hour to write and can save days of re-arguing a settled question. Start with the template above, keep each ADR to one decision and one page, review it as a pull request, and supersede rather than edit when things change. Your first ADR can be the decision to start writing them.
Frequently Asked Questions
What is an architecture decision record?
An architecture decision record (ADR) is a short document that captures one significant technical decision, the context that led to it, the options considered, and its consequences. ADRs are usually stored as numbered Markdown files in the code repository.
What should an ADR template include?
At minimum: a title, status, date, context, decision and consequences. Many teams also add decision drivers, considered options, pros and cons of each option, the people involved, and a confirmation step, as in the MADR template.
Who writes architecture decision records?
Usually the engineer or architect leading the decision drafts it, and the people affected review it, often as a pull request. Anyone on the team should be able to propose an ADR.
Can you edit an ADR after it is accepted?
Fixing a typo or a broken link is fine, but the decision itself should not change. If the decision changes, write a new ADR that supersedes the old one and update the old one’s status to point to it.
What is the difference between an ADR and a design document?
A design document describes how a system or feature will be built, often covering many decisions. An ADR records one decision and why it was made. A design document can link to several ADRs.
Where should ADRs be stored?
In the source repository, close to the code they affect, for example in docs/adr/. This keeps them versioned, reviewable in pull requests, and easy to find with the code.







