ADR Generator
Fill in the decision, get a clean Nygard, MADR 4.0 or Y-statement architecture decision record — copied or downloaded as markdown.
Decision Records·Last reviewed · revision 1
Inputs
Template
The original five headings. Shortest to write, easiest to get a team to adopt.
Runs entirely in your browser. Nothing is uploaded, stored, or sent anywhere.
Generated ADR
0001-use-postgresql-as-the-primary-data-store.md
# 0001. Use PostgreSQL as the primary data store
Date: YYYY-MM-DD
## Status
Proposed
## Context
We need a primary transactional store for the ordering service. The team is small, the access patterns are still moving, and we expect under 2,000 writes per second for at least eighteen months.
The forces at play:
- Operational simplicity
- Transactional integrity across entities
- Hiring and on-call familiarity
Options considered: PostgreSQL, DynamoDB and MongoDB.
## Decision
We will use **PostgreSQL**. It satisfies every driver, the access patterns are still changing and relational schemas absorb that better, and the team already runs it in two other services.
## Consequences
What becomes easier:
- Ad-hoc queries stay possible while the model is unsettled
- One operational runbook instead of two
What becomes harder:
- A single primary caps write throughput; revisit above ~2,000 writes/sec
- Horizontal scale requires a later sharding or migration decision
Nothing is sent anywhere — the file is assembled in your browser and saved locally. Commit the result next to the code it governs, in docs/adr/, so it is reviewed in the same pull request as the change it describes.
An ADR is worth writing for the context you will not have in two years — the constraints, the options that were live, and the downside you accepted. Use Y-statements by default, Nygard when the context needs a paragraph, and MADR when two people disagree. Store them in the repository they govern, and supersede rather than edit.
Which template
Three formats, and the choice matters less than the habit. Pick one, use it for everything, and change only when the format is actively costing you.
| Template | Best for | Cost |
|---|---|---|
| Nygard | Getting a team started. Five headings, ten minutes, fits on one screen. | Thin on rejected options — the part future readers most want |
| MADR 4.0 | Contested decisions with several credible options and stakeholders who need to see the comparison | Longer to write; overkill for "we'll use the standard library" |
| Y-statement | A decision that is real but small. Fits in a commit message, a slide, or a Slack pin. | No room for nuance, and none for the discarded options |
A practical policy: Y-statement by default, Nygard when the context needs a paragraph, MADR when two people disagree. Escalating format with contention keeps the cost proportional to the stakes.
What makes an ADR worth writing
The value is not the record of what you chose. Anyone can read the code and see what you chose. The value is the context you no longer have access to in two years — the constraints, the alternatives that were live, and the thing you were worried about.
Four properties separate an ADR that gets read from one that gets skipped:
Written before or at the decision, not after. A retrospective ADR is documentation. It reads as justification, it omits the option that nearly won, and everyone can tell.
Names the rejected options and why. This is the single highest-value section and the one most often left empty. The question an ADR gets opened to answer is almost always "did they consider X?" — and if the answer is not on the page, the answer is functionally no.
States the negative consequences. A decision with no downside was not a decision, it was a preference. The negatives are also the trigger conditions for revisiting: "this caps writes at 2,000/sec" is a number someone can later measure against.
Immutable once accepted. You do not edit an accepted ADR. You write a new one that supersedes it and link them. The history of the reasoning is the asset; overwriting it destroys exactly what you were trying to keep.
Where to put them
docs/adr/ in the repository the decision governs, numbered sequentially, reviewed in the same pull request as the change itself.
Not a wiki. Not a shared drive. Not a ticket. The ADR should move with the code, be diffable, and be discoverable by someone who has cloned the repository and nothing else. A decision record that requires a login to find will not be found.
For decisions spanning repositories, keep one architecture repository and link to it — but the default is local.
What deserves an ADR
Anything that is expensive to reverse or that a future engineer would reasonably question.
Write one for: the choice of a data store, a language or runtime, an integration protocol, an auth model, a deployment topology, a public API shape, a build-versus-buy call, a consistency guarantee, a partitioning key, a decision to accept known technical debt.
Do not write one for: a library with three viable equivalents, formatting, folder layout, anything reversible in an afternoon, or anything already settled by an existing ADR. A repository with two hundred ADRs has the same discoverability problem as one with none.
A rough test: if you would be annoyed to discover there was no explanation, write one.
Making them stick
Teams abandon ADRs for predictable reasons, and each one has a mechanical fix.
| Failure | Fix |
|---|---|
| "Nobody writes them" | Add the template to the pull-request checklist for changes touching infra/, schema/ or dependency manifests |
| "Nobody reads them" | Link the ADR from the code it governs, in a comment at the top of the module |
| "They go stale" | Do not edit — supersede. A stale ADR with an accurate date is still a true record of what was decided then |
| "They're too long" | Drop to Y-statements. A one-sentence record beats an unwritten essay |
| "We disagree in the ADR review" | Good. That is the ADR working — the disagreement was going to surface eventually, and it is cheaper here |
The deeper version of this is in architecture decision records people actually maintain.
Structured fields, for tooling
If you are generating or parsing ADRs programmatically, MADR's YAML frontmatter is the interoperable option:
---
status: accepted # proposed | rejected | accepted | deprecated | superseded by ADR-0021
date: 2026-08-28
deciders: platform guild
consulted: security, data
informed: engineering all-hands
---That is enough to build the two things worth building: an index page that lists every decision by status, and a fitness function that fails the build when an accepted ADR is superseded without a link, or when a directory named in an ADR changes without one.
Sources
- Documenting Architecture Decisions — Michael Nygard (verified )
- MADR — Markdown Any Decision Records — adr.github.io (verified )
- Y-Statements: A Light Template for Architectural Decision Capturing — Olaf Zimmermann (verified )
Frequently asked
What is an architecture decision record?
A short document capturing one significant architectural decision: the context that forced it, the options considered, the option chosen, and the consequences accepted. Its value is not the record of what was chosen — the code shows that — but the reasoning and the rejected alternatives, which are otherwise lost within a year.
What is the difference between Nygard, MADR and Y-statement formats?
Nygard is the original five-heading format — status, context, decision, consequences — and is the easiest to adopt. MADR 4.0 adds explicit decision drivers, per-option pros and cons, and a confirmation section, which suits contested decisions. A Y-statement compresses the whole thing into one structured sentence that fits in a commit message.
Where should ADRs be stored?
In docs/adr/ inside the repository whose code the decision governs, numbered sequentially and reviewed in the same pull request as the change. Not a wiki, drive or ticket system. The record should move with the code, be diffable, and be findable by someone who has only cloned the repository.
Should you edit an ADR after it is accepted?
No. Write a new ADR that supersedes it and link the two. The history of reasoning is the asset, and editing in place destroys the thing you were trying to preserve. A stale ADR with an accurate date is still a true record of what was decided at that time.
Which decisions deserve an ADR?
Anything expensive to reverse or that a future engineer would reasonably question: data store choice, language or runtime, integration protocol, auth model, deployment topology, public API shape, build versus buy, consistency guarantee, partitioning key, or accepting known technical debt. Not library swaps, formatting, folder layout, or anything reversible in an afternoon.
Why do most ADR practices die?
Because nothing prompts the writing and nothing surfaces the reading. Fix the first with a pull-request checklist triggered by changes to infrastructure, schema or dependency manifests, and the second by linking the ADR from a comment at the top of the module it governs. If length is the barrier, drop to Y-statements — a one-sentence record beats an unwritten essay.
Revision history
First publication. Three templates (Nygard, MADR 4.0, Y-statement) with markdown download, plus guidance on which decisions warrant a record and how to keep the practice alive.