Insights · Architecture Governance
How to write an ADR: a practical guide to architecture decision records
One short document per significant decision: context, options, decision, consequences. Review it like code; supersede, never edit.
This is the mechanics guide: what goes on the page, field by field, and the habits that keep a record useful three years later. For the governance side — who writes, who reviews, how the practice survives contact with an organization — read Making ADRs work: governance engineers actually follow. The two fail together, but the page format is where everyone starts, and it is where most people start wrong.
What an ADR is (and what it is not)
Michael Nygard introduced the format in 2011 as a lightweight response to heavyweight architecture documentation: one document per architecturally significant decision, a page or two long, “a conversation with a future developer”. Each record captures the forces at play, the choice made, and the consequences — including the negative ones. The format spread because it solved the real problem: six months after the decision, nobody can reconstruct why the queue, the mesh, or the gateway was chosen, and every staff rotation restarts the argument.
Three boundaries keep it honest:
- One decision, one record. A record that covers four decisions governs none of them.
- A decision, not a design. The ADR says why we chose mTLS-by-default; the detailed design lives elsewhere and links to the record.
- Significant, not every. Write a record when the choice affects structure, key quality attributes, dependencies, or interfaces — and when two or more viable options existed. If there was only one realistic option, write a comment, not an ADR.
The template that works
Start from Nygard’s five fields, extended with the one section every mature practice adds: options considered. A template that survives real use:
# ADR-014: Default-strict mTLS for east–west traffic
Date: 2026-03-12
Status: Accepted
## Context
Forces at play, in value-neutral language. What problem forces
this decision now? Constraints (regulatory, deadline, platform),
quality attributes at risk, who is affected.
## Options considered
1. Option A — what it is, what it costs, why it loses.
2. Option B — same. The rejection reasons are the payload:
"we chose X" is trivia; "we rejected Y because Z" is
institutional knowledge.
## Decision
We will … (active voice, one paragraph, no hedging).
## Consequences
What becomes easier, what becomes harder, what we now accept.
Include the costs, not just the benefits.
## Links
Supersedes ADR-009. Related: design doc, runbook.
The two dominant published templates differ mainly in how explicit they force you to be about alternatives. Nygard’s original carries Title, Context, Decision, Status, Consequences. MADR (Markdown Architecture Decision Records) adds Decision Drivers, a dedicated Considered Options section with pros and cons per option, and a Confirmation section describing how you’ll verify the decision held. MADR’s verbosity is a feature for contentious decisions and a tax for obvious ones — which is exactly why it ships in full, minimal, and bare variants.
Which template should you pick?
There is now controlled-experiment evidence instead of taste. Nogueira, Silva and Conte compared Nygard-style and MADR templates with 33 practitioners across comprehension, usability and ease of adoption (arXiv, 2026): the Nygard format scored significantly better overall, while MADR ranked best for capturing rationale depth. Their conclusion is the sane one: there is no universal template — pick per project, based on scale and time constraints. My rule of thumb after running an ADR catalogue through a national platform program: start minimal (Nygard-style), and require the options-considered section always. If a record needs MADR’s full pros-and-cons table, write MADR for that one decision.
Where ADRs live (and why not in a wiki)
Every authoritative guide converges on the same answer. Google Cloud’s Architecture Center tells you to store ADRs “close to your application code, ideally in the same version control system” as Markdown. AWS Prescriptive Guidance prescribes the record contents and the review loop — a 10–15 minute silent read, then a decision — for the same reason. Microsoft’s Well-Architected Framework puts it structurally: “The ADR serves as an append-only log. Don’t go back and edit accepted records. If a decision changes, write a new record that supersedes the original and link the two together.”
Version control is not pedantry; it is what makes the practice govern:
- Numbering is identity.
docs/adr/adr-014-mtls-east-west.mdmeans something when cited in a design review. “The Kafka one” doesn’t. Numbers are sequential and never reused. - Review rides existing rails. The record is proposed as a pull request; approval is a commit. No separate tool, no separate login, no forgotten wiki namespace.
- Discovery is grep. Engineers find records from code and pull requests, which is how records get read.
- Tooling is optional and cheap. adr-tools automates numbering and supersession links; a directory convention works without it. ThoughtWorks has had lightweight ADRs on Adopt in the Technology Radar since 2017, with the plain verdict: “For most projects, we see no reason why you wouldn’t want to use this technique” — and the explicit instruction to store them in source control, not a wiki.
The lifecycle: proposed, accepted, superseded
Status is where naive practices die. Three states and one iron rule:
- Proposed — under review. The pull request is the review.
- Accepted — governs. Immutable from here on. AWS’s guidance is blunt: accepted records are not edited; superseding records replace them, and the old record is marked Superseded with a pointer to its replacement.
- Superseded — still valuable. The constraint that forced the old decision, and the reason it no longer holds, are exactly what a successor needs to judge the new decision honestly.
Rejected options stay recorded too. A rejected record documents why the obvious-looking path was closed — knowledge that prevents the same debate from being re-litigated with fresh personnel. Nygard’s original framing already had this: superseded records are kept, not deleted, because decisions that can’t be superseded openly get ignored instead.
When to write an ADR (and when not)
The trigger question is simple: were there two or more defensible options, and does the choice bind future work? Concrete cases that earn a record:
- Selections that shape the platform: API management, service mesh, message backbone, observability stack, CI/CD.
- Security posture defaults: gateway policy, mTLS east–west, secrets management — including interim arrangements, because transitional choices without records become permanent ones.
- Cross-cutting conventions: error models, ID formats, event schemas, retention periods.
- Migration control surfaces: traffic splitting between old and new systems before any traffic moves.
Tyree and Akerman made the case for capturing decisions — issue, assumptions, constraints, positions, alternatives — back in IEEE Software in 2005; the ADR format made it cheap enough to actually happen. What hasn’t changed is the scope discipline: anything with one viable option and no lasting consequence is a commit message, not a record.
Before you mark a record Accepted: context states the real constraints; at least two options appear with rejection reasons; the decision is one imperative paragraph; consequences include a cost; status and links are set; the file is numbered and merged beside the code it governs.
Four ways the page format goes wrong
- The essay standard. Records that take a week to write arrive after the decision and get written by the few, for the few. One focused page in the meeting’s aftermath beats a masterpiece next month.
- Options deleted. The highest-value section is the first one people cut. A record without rejected alternatives is a press release.
- Edited history. The moment an accepted record is quietly rewritten, the catalogue stops being evidence and starts being marketing. Append-only, always.
- Records far from code. In a wiki or a deck, records compete with nothing and link to less; they decay into archaeology.
On the E-Tax modernization, 15 records governed more than 30 technology selections — gateway security, mTLS defaults, secrets, the event backbone, traffic splitting — and the format earned its keep precisely because each one was short enough to be written by the people doing the work, in the repository those people already lived in.
Stand up your decision practice
Sources
- Michael Nygard, “Documenting Architecture Decisions” (Cognitect, 2011)
- MADR — Markdown Architecture Decision Records (template and variants)
- Google Cloud Architecture Center, “Architecture decision records overview”
- AWS Prescriptive Guidance, “Architectural decision record process”
- Microsoft Azure Well-Architected Framework, “Maintain an architecture decision record (ADR)”
- ThoughtWorks Technology Radar, “Lightweight Architecture Decision Records” (Adopt)
- Jeff Tyree & Art Akerman, “Architecture Decisions: Demystifying Architecture”, IEEE Software 22(2), 2005
- Nogueira, Silva & Conte, “One Size Fits All? An Empirical Comparison of ADR Templates regarding Comprehension, Usability, and Ease of Adoption” (arXiv, 2026)
- Joel Parker Henderson (ed.), “Architecture decision record” — templates and examples
- Nat Pryce, adr-tools — numbering and supersession tooling