Template ADR (Architectural Decision)

ADR: capturing the why behind architecture decisions

An ADR — Architecture Decision Record — is a short Markdown document that captures one architectural decision: the context that motivated it, the decision itself, and the consequences that follow. The format was proposed by Michael Nygard in a 2011 blog post titled "Documenting Architecture Decisions", and it quickly became the industry default for one simple reason: months after a decision is made, nobody remembers why. ADRs preserve the reasoning so that future maintainers — who often include the original authors — can understand why the system looks the way it does without having to reverse-engineer it.

The Nygard template has five sections: Title (numbered — "ADR-0007: Use PostgreSQL"), Status (Proposed, Accepted, Deprecated, or Superseded by ADR-N), Context (what forces are at play?), Decision (what did we choose?) and Consequences (what becomes easier and what becomes harder?). The community has since produced refinements — MADR (Markdown Architectural Decision Records, hosted at adr.github.io) is the de facto standard — and a CLI called adr-tools by Nat Pryce automates the boilerplate.

Where ADRs live and how they are numbered

The conventional location is docs/adr/ inside the relevant git repository, with files named 0001-use-postgresql.md, 0002-deploy-to-kubernetes.md, and so on. Numbers are sequential and never reused — even when an ADR is deprecated, its number is retained so cross-references in commits and code comments stay valid. When a new decision replaces an old one, the old ADR's status becomes "Superseded by ADR-0017" and the new ADR's context cites the old one. A healthy team produces roughly one ADR every one or two weeks; long droughts usually mean either no significant decisions are being made or, more likely, decisions are being made without being recorded.

ADR vs RFC vs design doc

An RFC is the proposal stage — open to debate, possibly rejected. A design doc is the detailed plan to implement something already approved, spanning multiple components and decisions. An ADR records exactly one decision that has already been made; it is short (one to two pages is the sweet spot) and immutable once accepted. The natural pipeline is RFC → design doc → ADRs that distil the key choices for posterity. ADRs are also part of the AWS Well-Architected Framework and are used at Spotify, HashiCorp, Zalando and ThoughtWorks.

Anti-patterns and good examples

The common failure modes: ADRs for trivial decisions (the naming of a variable does not need an ADR; the choice of a database does), missing the why (an ADR that lists what was chosen but not what was considered and rejected is half a document), ADRs that are too long (anything beyond two pages probably wanted to be a design doc), and missing decision matrix (when multiple options were considered, a weighted criteria table makes the reasoning auditable). Joel Parker Henderson's architecture-decision-record repository on GitHub is the canonical public collection of examples and templates.

FAQ

When should I write an ADR? When a decision will be expensive to reverse — database choice, public API shape, deployment platform, authentication model, message bus. If the decision is "we will use camelCase", no. If the decision is "we will use event sourcing", yes.

How long should an ADR be? One to two pages. If it grows beyond that, you probably bundled multiple decisions; split it into several ADRs.

Is there a reusable template? Yes — the Nygard template (5 sections) and the MADR template are both public domain and widely adopted. Either is a defensible starting point.

Can ADRs be revisited? The ADR itself is immutable, but its status can change. If a decision no longer holds, write a new ADR that supersedes the old one and update the old one's status to Superseded by ADR-N. Never edit history in place — the historical record is the whole point.