Stackbook Logo
← Back to Tracks

Architecture Decision Record Template and Practice

A ready-to-use ADR template, plus a guided track for writing, reviewing and maintaining architecture decision records that teams actually read.

4 min read

An architecture decision record, or ADR, is a short document capturing one significant decision: the context, the options considered, the choice and its consequences. The format was popularised by Michael Nygard. Their value is memory. Months later, nobody remembers why the team picked a message broker or split a service, and without a record the decision is either cargo-culted or reopened endlessly.

Learning goals

  • Know which decisions deserve an ADR and which do not.
  • Write a clear, honest ADR in under an hour.
  • Run a lightweight review and manage ADR status over time.
  • Keep records discoverable and connected to the code.

The template

Store ADRs in the repository, for example under docs/adr/, numbered sequentially. One decision per file.

# ADR-0007: Use PostgreSQL for the order service

- Status: Accepted (Proposed | Accepted | Deprecated | Superseded by ADR-0015)
- Date: 2026-06-01
- Deciders: Order team, Platform architect
- Consulted: Data team, SRE

## Context
What problem are we solving? What forces are at play: requirements,
constraints, quality attributes, deadlines, team skills?
Include measurable facts, such as "peak 800 orders per second".

## Decision drivers
- Strong consistency for order and payment state
- Team already operates PostgreSQL
- Need ad hoc reporting queries

## Options considered
1. PostgreSQL
   - Pros: transactions, mature tooling, team skills
   - Cons: vertical scaling limits, manual sharding later
2. DynamoDB
   - Pros: horizontal scaling, managed
   - Cons: access patterns must be known up front, weaker ad hoc queries
3. Keep the order data in the existing monolith database
   - Pros: no migration
   - Cons: continued coupling and shared failure domain

## Decision
We will use PostgreSQL, deployed as a managed instance with one
read replica.

## Consequences
Positive: simple transactional model, familiar operations.
Negative: write scaling will require partitioning beyond ~5k writes/s.
Risks and mitigations: replica lag may show stale reads, so
read-your-writes paths use the primary.
Follow-ups: define partitioning approach by Q4.

## Revisit when
Sustained writes exceed 3k/s, or the reporting load affects checkout latency.

## References
Load test results, related ADR-0003, relevant paper or vendor docs.

The sections that most often get skipped, and matter most, are the rejected options, the negative consequences and the revisit conditions.

Which decisions need an ADR

Write one when a decision is hard to reverse, affects several teams, sets a precedent, or took meaningful debate. Examples: choosing a datastore, an integration style, an authentication approach, or a service boundary. Do not write one for routine choices that a linter or style guide covers.

A four-week practice plan

Week 1: Write retroactively. Pick three existing decisions in your system, interview the people involved, and record them. This teaches you to separate context from decision.

Week 2: Write prospectively. Choose a live decision and draft an ADR before implementing. Share it as a pull request so discussion happens on the document.

Week 3: Review. Adopt a simple review checklist:

  • Is the problem clear without prior knowledge?
  • Are at least two real alternatives described fairly?
  • Are consequences honest, including negatives?
  • Is there a trigger for revisiting?
  • Can a new hire understand it in five minutes?

Week 4: Maintain. Add an index file listing ADRs by status. When a decision changes, write a new ADR that supersedes the old one and update the old status, rather than editing history.

Exercises

  1. Rewrite a vague ADR saying "we chose Kafka because it is scalable" into one with measurable drivers and a rejected alternative.
  2. Write an ADR with a deliberately reversible decision and one with an irreversible one; compare how much analysis each deserves.
  3. Audit the repository for decisions that should have records and open issues for the top three.

Common mistakes

  • Treating ADRs as approval paperwork rather than a thinking tool.
  • Recording the decision without the alternatives.
  • Writing after the fact with hindsight, hiding the uncertainty that existed.
  • Editing accepted records, which erases the history of reasoning.

Key takeaways

  • An ADR captures context, options, decision and consequences for one significant decision.
  • Keep records in the repository, numbered, short, and immutable apart from status.
  • Always include rejected alternatives, negative consequences and revisit conditions.
  • Review them like code, and supersede instead of rewriting.
  • Use the template as a thinking aid: if you cannot fill a section, you have found a gap in the decision.