Every system is the result of many decisions, and most of the reasons behind them get lost over time. Then a new engineer asks "why is it built this way?" and nobody remembers. An architecture decision record (ADR) is a short document that saves one decision and its reasons. This note covers how to write ADRs, how to present trade-offs, and how much process a decision deserves.
What an ADR is#
An ADR records one significant decision in about one page. Michael Nygard made the format popular in a 2011 blog post. Teams usually keep ADRs as numbered Markdown files in the code repository, for example docs/adr/0007-use-postgres-for-orders.md, so they're reviewed and versioned with the code.
The format stays short because it has a fixed shape. Nygard's template has five parts:
| Part | What it contains |
|---|---|
| Title | A short noun phrase with a number, e.g. "ADR 7: Use PostgreSQL for order data" |
| Status | Proposed, accepted, deprecated or superseded |
| Context | The facts and forces that make a decision necessary, stated neutrally |
| Decision | What the team will do, in active voice: "We will use..." |
| Consequences | What becomes easier and what becomes harder, good and bad |
Notice the "superseded" status in that list. ADRs are immutable (not changed after acceptance). If a later decision replaces an old one, write a new ADR. Then set the old ADR's status to "superseded by ADR 12". The full chain shows how your thinking changed over time.
ADRs vs design docs#
If you've read the previous note, you might wonder how an ADR differs from a design doc. Both record decisions, but they work at different sizes, and many teams use both.
| Design doc | ADR | |
|---|---|---|
| Scope | A whole project or feature | One decision |
| Length | Several pages | About one page |
| When written | Before the build starts | Whenever a significant decision is made |
| After approval | Updated as the plan changes | Never edited; replaced by a new ADR |
| Main reader | Reviewers today | Engineers in the future |
A design doc often produces several ADRs, for example one for the database and one for the message queue. See Writing a Design Doc for the full document.
Presenting trade-offs#
The "Consequences" part of an ADR only works if you compared real options fairly. A trade-off is what you give up to get something else, so every option needs both its gains and its costs. Two formats help.
Comparison tables#
Start with a plain table. Put the options in columns and the criteria in rows, and keep the cells short and concrete.
| Criterion | PostgreSQL | DynamoDB | MongoDB |
|---|---|---|---|
| Transactions across rows | ✓ | Limited | ✓ |
| Team experience | High | Low | Medium |
| Ops effort | Medium (managed) | Low | Medium |
| Flexible queries | ✓ | ✗ | ✓ |
Weighted criteria#
When the table doesn't show a clear winner, give each criterion a weight. Score each option from 1 to 5, multiply by the weight, and add the results.
| Criterion | Weight | PostgreSQL | DynamoDB |
|---|---|---|---|
| Correctness (transactions) | 3 | 5 → 15 | 3 → 9 |
| Team experience | 2 | 5 → 10 | 2 → 4 |
| Ops effort | 1 | 3 → 3 | 5 → 5 |
| Total | 28 | 18 |
Agree on the weights before you score the options. If you choose weights after scoring, the matrix only justifies the answer you already wanted.
A scoring matrix supports judgment; it doesn't replace it. If the result feels wrong, a criterion is probably missing.
One-way and two-way doors#
Comparing options takes time, and not every decision deserves that much care. Jeff Bezos described how to tell the difference in his 2015 Amazon shareholder letter with the "door" metaphor.
- A two-way door is a reversible decision. If it's wrong, you walk back through. Examples: a feature flag default, a library for one service, an internal API that only your team calls.
- A one-way door is an irreversible or very expensive decision. Examples: a public API contract, a primary database, a data format that you store for years.
Match the process to the door. Make two-way door decisions fast, with a small group, and expect to correct some of them. For one-way doors, slow down: write a design doc or ADR, get wide review, and prototype if you can. A common mistake is to treat every decision as a one-way door, which makes a team slow for no benefit.
Disagree and commit#
Even with a good process, people won't always agree, and a review doesn't need full agreement to end. Disagree and commit means you state your objection clearly during the discussion. After the decision is made, you support it fully, even if your view wasn't chosen. Amazon includes the idea in one of its leadership principles.
- Raise your concerns during the review, with evidence, not after.
- Ask that significant objections go into the ADR's consequences or alternatives.
- After the decision, don't slow the work down or say "I told you so".
- If new facts appear, propose a new ADR. Don't quietly work around the decision.
RFC processes in open source#
ADRs are mostly an internal habit. Open source projects face the same problem in public, with contributors who may never meet, so many decide large changes with a public RFC (request for comments) process. The name comes from the RFC series that defines internet standards. The series began in 1969, and the IETF publishes it today.
- An author writes a proposal in a fixed template: motivation, design, drawbacks, alternatives and unresolved questions.
- The proposal is opened as a pull request to a dedicated repository.
- Anyone can comment, and the author revises the text.
- A responsible team decides to accept, postpone or close it, often after a final comment period.
The Rust RFC repository and Python's PEPs (Python Enhancement Proposals) are well-known examples. Reading a few accepted RFCs is a good way to see how strong proposals present trade-offs.
Key takeaways#
- An ADR records one decision in five parts: title, status, context, decision and consequences.
- Never edit an accepted ADR. Supersede it with a new one so the history stays clear.
- Design docs plan a whole project; ADRs save individual decisions for future readers.
- Show trade-offs in comparison tables, and set weights before you score.
- Move fast on two-way doors and slow down on one-way doors.
- Disagree during the review, then commit to the decision.