What an ADR is, when to write one, Nygard or MADR Intermediate
Estimated reading time: 3 min read
This page answers: what an ADR is (and isn’t), which decisions deserve an ADR, and which template to start with.
What an ADR is and isn’t
Section titled “What an ADR is and isn’t”Per adr.github.io, an ADR “captures a single architectural decision and its rationale”, along with trade-offs and consequences. The collection of a project’s ADRs is its decision log.
| An ADR is | An ADR is not |
|---|---|
| One decision, one file, 1–2 pages (Nygard) | A 20-page design document |
| The context at the time of the decision | A description of the current system, edited constantly |
| Immutable once accepted; changing your mind means a new ADR | A wiki page anyone overwrites |
| Honest about bad consequences | A pitch “selling” a solution |
| Written for an engineer two years from now, in full sentences | Meeting minutes in clipped bullets |
Nygard stresses that each ADR should read like a conversation with a future developer. Write sentences and paragraphs; bullets are for presentation, not a substitute for sentences.
When to write an ADR, and when not to
Section titled “When to write an ADR, and when not to”Two questions filter almost every case: is it hard to reverse? and will others wonder about it?
Loading diagram…
| Worth an ADR | No ADR needed |
|---|---|
| Using a transactional outbox instead of publishing after commit | Renaming a variable, extracting a function |
| Keeping a modular monolith, not splitting into microservices yet | Bumping a library’s patch version |
Bounded context boundaries: Shipping has its own Order model |
Picking a log format (a shared convention already exists) |
Decrementing stock with READ COMMITTED + SELECT ... FOR UPDATE instead of SERIALIZABLE (see isolation levels) |
Adding an index (the migration is enough) |
| Choosing PostgreSQL over MongoDB for orders | Conventions already in the linter / style guide |
| Not doing something everyone assumes you should (e.g., not caching balances) | Implementation details inside one module |
“Won’t do” decisions are often the most worth recording. They are invisible in code, so they are the ones proposed again most often.
Nygard vs MADR
Section titled “Nygard vs MADR”Two popular templates. The section names below match Nygard’s original post and the MADR 4.0.0 template (released 2024-09-17).
| Nygard (2011) | MADR 4.0.0 | |
|---|---|---|
| Sections | Title, Context, Decision, Status, Consequences | Title, Context and Problem Statement, Decision Drivers*, Considered Options, Decision Outcome (Consequences*, Confirmation*), Pros and Cons of the Options*, More Information* |
| Metadata | Status is a section | YAML front matter*: status, date, decision-makers, consulted, informed |
| Rejected options | No dedicated section (usually written in Context) | Considered Options must be listed |
| Compliance check | None | Confirmation: design review, automated tests |
| Suggested statuses | proposed, accepted, deprecated, superseded | proposed, rejected, accepted, deprecated, superseded by ADR-NNNN |
| File location | doc/arch/adr-NNN.md |
docs/decisions/NNNN-title-with-dashes.md |
| Fits | Small teams that want to start in 10 minutes | Many competing options, audit needs |
* = optional in the MADR template.
Loading diagram…
Suggested default: use Nygard and add a short “Options considered” part inside Context. When the team starts arguing about rejected options, switch to MADR. Don’t spend a sprint picking a template.
Next: Writing a good ADR.