Free template · CSV and Markdown · no email required
Architecture decision record (ADR) template
For engineering teams who record architecture choices next to the code. It keeps Michael Nygard’s five sections and adds the three fields that let a later reader check whether the predicted consequences arrived.
When to use this template
- The choice is structural and expensive to reverse: a datastore, a service boundary, a framework, a hosting model.
- Future engineers will ask why the system looks this way, and the person who knows may have left.
- You want the record to live in the repository and be reviewed in the same pull request as the change.
- A plain decision log would lose the technical context: the forces, the constraints, and the trade-offs you accepted.
The 12 fields
- ADR number
- A sequential number that is never reused, such as ADR-0007.
- Title
- A short noun phrase naming the decision, such as “Use PostgreSQL for the event store.”
- Status
- Proposed, accepted, deprecated, or superseded. Change the status; never delete the record.
- Date
- The date the status last changed, as YYYY-MM-DD.
- Deciders
- The people who made the call, so a later reader knows whom to ask.
- Context
- The forces at play: technical, political, social, and project-specific. Describe them neutrally.
- Decision
- The response to those forces, in active voice: “We will …”
- Consequences
- What becomes easier and what becomes harder. Include the negative and the neutral, not only the benefits.
- Expected consequence
- One consequence stated so it can be checked, with a number or an observable sign.
- Review date
- When that consequence should be visible, usually after the first real load or the first change of owner.
- What actually happened
- Written on the review date. Record the result beside the prediction without editing either.
- Superseded by
- The ADR that replaced this one, if any. Link both ways.
How to use it
- 1
Keep one short file per decision
Store ADRs as numbered Markdown files in the repository so they are reviewed with the code. Nygard suggests one or two pages. MADR (Markdown Architectural Decision Records) is a known variant that adds decision drivers and considered options.
- 2
Write the costs as plainly as the benefits
List what gets harder next to what gets easier. Then pick one consequence you can check and write the date it should be visible.
- 3
Never edit an accepted ADR
If the decision changes, write a new ADR and mark the old one superseded. The history of reversals is part of the architecture.
- 4
Return on the review date
Record what actually happened next to what you expected. A missed prediction tells the next ADR which forces you underweighted.
Illustrative example: ADR-0007 at Larkfield Freight, an invented company
- Title
- Use PostgreSQL for the shipment event store
- Status
- Accepted
- Context
- Shipment events peak at about 40 per second. The team already runs PostgreSQL for billing, and nobody has operated Kafka in production. The client contract requires a seven-year audit trail.
- Decision
- We will store shipment events in an append-only PostgreSQL table, partitioned by month, and revisit if sustained writes exceed 500 per second.
- Consequences
- One database to operate and back up. Replaying events is slower than with a log-based broker. Partition maintenance becomes a monthly task.
- Expected consequence
- p95 write latency stays under 20 ms through the November peak with no new infrastructure.
- Review date
- 2025-12-15
- What actually happened
- p95 held at 14 ms. One monthly partition was missed in October and caught by an alert, so partition creation is now automated.