Architecture Decision Record (ADR) Template and Example

October 27, 2026 · 6 min read

An architecture decision record (ADR) is a short document that captures one decision, the options that were considered and the reasons for the choice. The compact version has five parts: title, status, context, decision and consequences. Below are two templates you can copy, a worked example, and a simple rule for deciding which decisions deserve a record.

What an ADR is

The ADR collection of a project is its decision log. The ADR site describes an ADR as a document that captures a single architectural decision and its rationale, with the trade-offs and consequences (adr.github.io). The idea was popularised by Michael Nygard in 2011 in a post called "Documenting Architecture Decisions", which proposed a short record for each significant decision (Nygard, 2011).

Nygard's template has five parts: a short noun-phrase title, a context that describes the forces in play, the decision, a status (proposed or accepted, and later deprecated or superseded) and the consequences, good and bad. He suggests that a record should fit on one or two pages, that records are numbered sequentially and never reused, and that a reversed decision stays on file, marked as superseded.

The value is not in the form. It is in the answer to the question that always comes later: "Why did we do it this way?" Without a record the reasons live in someone's memory, and when that person leaves, the next team either repeats the debate or keeps a choice it does not understand.

When to write one

Not every choice needs a record. A rule of thumb is to write an ADR when at least one of these is true:

The decision is hard or expensive to reverse, such as the platform, the main data store or a key provider.
It affects more than one team or several requirements.
There were real alternatives and people disagreed.
It limits future choices, for example by committing you to a provider.
Someone will reasonably ask "why this and not that?" in six months.

Skip a record for choices that are easy to change in an afternoon, for style conventions that a linter already enforces, and for anything that nobody would question later. If you write an ADR for every library, they will not be read.

In discovery, the choices that usually qualify are the big shape of the system (build on an existing system or replace it), how the app is delivered (native, cross-platform or web), where data is stored and how conflicting changes are resolved.

Compact template

This is the smallest version that still works. It follows Nygard's five parts, so it can sit in a wiki or a repository file:

# ADR-NNN: Short noun-phrase title

Status: Proposed | Accepted | Superseded by ADR-NNN

## Context
The forces at play: the requirement, the constraint, the situation.
Neutral wording; no argument for the answer yet.

## Decision
We will ... (full sentence, active voice).

## Consequences
What becomes easier, what becomes harder, what we must now do.
Include the negative effects.

Full template

In a client project, the decision is often reviewed by people who were not in the room, so a longer version helps. It adds who decided, the options and the links to the requirements the decision affects:

# ADR-NNN: Short noun-phrase title

Status: Proposed | Accepted | Superseded by ADR-NNN
Date: YYYY-MM-DD
Deciders: names and roles
Requirements covered: REQ-003, REQ-010
Related: diagram or decision links

## Context
What problem or requirement forces a choice, and what limits apply.

## Options considered
| Option | Pros | Cons | Cost (S/M/L) |
|---|---|---|---|
| Option A (chosen) | ... | ... | M |
| Option B | ... | ... | L |
| Option C | ... | ... | S |

## Decision
We will use Option A because ...

## Consequences
- What this makes easier
- What this makes harder
- Follow-up actions, with owners

## Review
When this should be reconsidered, or what would trigger a new record.

The options table is the part most often skipped. A decision recorded without the alternatives looks arbitrary, and it hides the reason why the other options lost.

An example

The example below is invented. It belongs to Fieldwise, an imaginary app for field technicians who work in basements and rural areas with poor coverage.

# ADR-002: Cross-platform mobile app

Status: Accepted
Date: 2026-10-05
Requirements covered: REQ-003 (work without coverage), REQ-010

## Context
Technicians use both Android and iOS phones, and the team is small.
The app must work for a full day without a network.

## Options considered
| Option | Pros | Cons | Cost |
|---|---|---|---|
| One cross-platform codebase (chosen) | One team, one release | Slightly less polish on each platform | M |
| Two native apps | Best platform fit | Double the effort and testing | L |
| Progressive web app | No store review | Weak offline support on iOS | S |

## Decision
Use one cross-platform codebase for Android and iOS.

## Consequences
- Offline storage and background sync need an early technical spike.
- Platform-specific features are limited to what the framework supports.
- Revisit if the spike shows that sync cannot be made reliable.

The same record, as it appears in the example report with its options compared and the requirements it addresses:

Decisions list from the Fieldwise example report, invented project: three architecture decisions, with the cross-platform decision expanded to show context, three options compared with pros, cons and cost, the decision, consequences and linked requirements

Notice three things. The context contains facts, not the argument for the answer. The consequences include a cost, the spike, rather than only benefits. And the record names what would make it worth revisiting.

Where to keep them

Pick one place and keep it findable:

In the repository, next to the code. Nygard suggests a folder such as doc/arch/ with files named adr-NNN.md, in a lightweight markup like Markdown. This works well once a team is building, because a change to the code and its record can be reviewed together.
In the discovery document, linked to the requirements and diagrams. This suits client work, where the people who sign off do not read the repository.
In both, with the repository copy as the long-term home. Move the decisions at handoff, so the build team starts with the reasons, not just the choices.

Whichever you choose, apply a few rules: number records in sequence and never reuse a number, never delete a reversed decision, and link each record to the requirements and diagrams it affects. A decision that is not linked to a requirement is hard to judge, and a requirement that depends on an unrecorded decision is a risk. The software requirements document template shows where requirements and decisions meet.

Decisions also feed the plan: a choice that needs a spike belongs in the roadmap as an early milestone. You can see a full set of invented decisions, diagrams and requirements together in the example report.