ADR key facts
- Use one ADR for one decision.
- Preserve accepted ADRs. Supersede them with a new record instead of rewriting history.
- Record decision drivers before comparing options.
- Include negative consequences and follow-up work.
- Link evidence, prototypes, benchmarks, and related decisions.
Copyable Markdown ADR template
# ADR-[number]: [Decision title]
**Status:** Proposed
**Date:** YYYY-MM-DD
**Decision owners:** [Names or team]
**Technical area:** [Area]
## Context
[Problem, forces, constraints, and facts.]
## Decision drivers
- [Reliability, cost, delivery time, compliance, or other driver]
## Options considered
### Option 1: [Name]
- **Advantages:** [Benefits]
- **Disadvantages:** [Costs and risks]
- **Evidence:** [Prototype, benchmark, or source]
### Option 2: [Name]
- **Advantages:** [Benefits]
- **Disadvantages:** [Costs and risks]
- **Evidence:** [Prototype, benchmark, or source]
## Decision
We will [decision].
**Reason:** [Why this option best satisfies the drivers.]
## Consequences
### Positive
- [Expected benefit]
### Negative
- [Accepted cost or limitation]
### Follow-up work
- [ ] [Action] · **Owner:** [Name] · **Due:** YYYY-MM-DD
## Validation
[How the team will confirm the decision works and when it will be reviewed.]
## Related decisions and references
- [ADR, design document, issue, benchmark, or source]
ADR status values
Use a small set such as Proposed, Accepted, Rejected, Deprecated, and Superseded. If superseded, link both records so readers can follow the decision history.
When to create an ADR
Create one when a choice changes architecture, security, data ownership, a long-lived dependency, or a constraint that future maintainers may question. Do not create an ADR for every routine implementation detail.
Write the context as it was known at decision time. Include the constraints that ruled options in or out. The selected option does not need to be perfect; the record should explain why it was the best available trade-off.
Number and store ADRs
Use stable sequential numbers, such as ADR-0042, and keep records in a predictable directory such as docs/adr/. A filename like 0042-use-postgresql-for-orders.md remains readable in search and Git history. Never reuse a number after a proposal is rejected.
Completed ADR example
Suppose a team must choose where to store customer order data. A useful decision section would be direct:
We will use PostgreSQL as the system of record for orders. The ordering workflow requires transactions, relational constraints, predictable recovery and reporting across customers, payments and fulfilment. A document database remains suitable for the product catalog, but it does not satisfy the order-consistency requirements as clearly.
The consequences should state both sides. The team gains transactional integrity and mature backup tooling, but it also accepts schema migrations, connection management and the need to monitor slow queries. Follow-up work might include a restore test, retention policy and load benchmark.
How to write each ADR section
| Section | What to include | What to avoid |
|---|---|---|
| Context | Facts, constraints and the decision that must be made | Rewriting the final decision as if it were inevitable |
| Drivers | The criteria that distinguish the options | Generic goals such as “best” or “modern” |
| Options | Viable alternatives with evidence | Straw-man choices included only to justify one option |
| Decision | The selected option and reason | Implementation detail unrelated to the choice |
| Consequences | Benefits, costs, risks and follow-up | Recording only positive outcomes |
| Validation | What will prove the choice works | “Monitor it” without a metric, owner or review date |
ADR workflow
Draft the record as Proposed, review it with people affected by the decision, and change it to Accepted only after agreement. Treat an accepted ADR as historical evidence. If circumstances change, create a new ADR and mark the earlier one Superseded with a link to its replacement.
This lifecycle matches the guidance from AWS Prescriptive Guidance and the Microsoft Azure Well-Architected Framework.
Common ADR mistakes
- Recording a broad architecture description instead of one decision.
- Omitting options that were seriously considered.
- Using opinions such as “cleaner” without evidence or criteria.
- Rewriting an accepted ADR after the outcome becomes known.
- Leaving follow-up work without an owner.
ADR template FAQ
How long should an ADR be?
Use the shortest record that preserves the context, options, decision and consequences. Many decisions fit on one or two pages. A complex decision can link to benchmarks or a technical design rather than embedding every detail.
Is an ADR the same as a technical design document?
No. An ADR explains why one important choice was made. A technical design document explains how a larger system or change will work and can link to several ADRs.
Can an ADR be changed after approval?
Correct factual errors carefully, but do not rewrite the decision history. Create a new ADR when the team changes direction, then link the old and new records.