Architecture Practice

ADR (Architecture Decision Record)

Also known as: architecture decision record, ADR

Definition

An ADR is a short, immutable document capturing one architecturally significant decision: its context, the options considered, the choice, and the consequences. Records are never edited after acceptance — a later decision supersedes an earlier one, so the file set becomes a dated record of how the system came to be shaped this way.

Last reviewed · Part of the Architecture Glossary

In practice

The minimum viable ADR is five headings — Nygard's original format, and still the one most teams stick with:

# 0014. Use Postgres for the event store
## Status        Accepted (2026-03-11), supersedes 0009
## Context       What forces are in play, with numbers
## Decision      What we will do, in active voice
## Consequences  What this makes easy, and what it makes hard

Three rules decide whether the practice survives:

  • Immutable. Changing your mind creates ADR 0021 with Supersedes 0014, and 0014 is marked Superseded by 0021. Editing history destroys the only thing an ADR is for.
  • In the repository, beside the code, reviewed in the same pull request. A wiki page is a document; a file in docs/adr/ is part of the change.
  • Consequences must include the negative ones. An ADR that lists only benefits is a sales document, and the next team will not trust it.

The generator produces Nygard, MADR and Y-statement formats if you want the structure without the blank page.

When it matters

Decisions that are expensive to reverse: data stores, boundaries, protocols, auth models, deployment topology, third-party dependencies.

Common mistake

Writing them for everything. Twenty ADRs a month means nobody reads any of them. The test is "would a new architect be confused about why this is the way it is" — that is the whole filter.

See also

Go deeper