How to Write an Architecture Decision Record (ADR), with a Template

Why write an ADR at all

The reasons behind a decision fade within months. An ADR records why a technology was chosen and what was given up, so the same argument does not restart every time someone new joins. Do not edit an accepted ADR; when the decision changes, write a new one that supersedes it.

Write the context and constraints first

Describe the facts that made the decision necessary and the limits you work within: how far a failure can spread, how many engineers run the system. Leave product names out of the context section.

Build the options from what others did

Check what other companies chose at the same decision point. Stripe replaced an off-the-shelf proxy with its own data plane. That case proves “build it ourselves” is a real option, not a hypothetical one.

Record the conditions a choice creates, not only its benefits. Netflix’s tool for measuring the blast radius of library changes is a reminder that a decision about shared code affects every consumer.

When the choice is between two tools, list the structural differences that matter for your workload, such as delivery guarantees and operating burden, and cite where you learned them.

Write the decision and its consequences

Start the decision with “We will…” in one sentence. In consequences, list the costs as clearly as the benefits. An ADR with no listed costs usually describes a decision that will be regretted later.

Template (copy)

# ADR-NUMBER: Title

- Status: Proposed / Accepted / Superseded by ADR-NUMBER

## Context

What situation and constraints led to this decision.

## Options

- Option A: pros, cons
- Option B: pros, cons

## Decision

One sentence on what we decided, and one or two on why.

## Consequences

- What gets better
- What we pay for it
- Conditions that should trigger a new review