What is an Architecture Decision Record?

An ADR is a short markdown file — typically 100 to 800 words — that captures the why of a meaningful engineering decision. It lives in the same repository as the code it governs. It's read by future you, by the engineer who joins six months from now, and by the reviewer who shows up two years later asking why the system was built this way.

The format originated in Michael Nygard's 2011 essay Documenting Architecture Decisions. Nygard's argument was simple: a codebase only shows the what. The decisions behind it — the constraints, the rejected alternatives, the consequences the team agreed to live with — vanish unless they're written down. ADRs make that knowledge durable and version-controlled.

What an ADR is not

An ADR is not a design doc, not an RFC, not a postmortem. Those are upstream and downstream artifacts. The ADR is the smallest record of what we decided and why — written after the decision, kept forever, never edited (only superseded).

Six rules that work in practice

1. One ADR per decision. If you find yourself writing "and we also decided", stop and split.
2. Numbered, immutable, never deleted. When a decision is reversed, you write a new ADR that says supersedes ADR-NNN. The old one stays.
3. Status is part of the record. Proposed → Accepted → Superseded/Deprecated. The status itself is information.
4. Write the consequences honestly. Both what becomes easier and what becomes harder. The honest second half is where most teams stop, and it's exactly the part future-you needs.
5. Commit them next to the code. /docs/adr/0001-some-decision.md is the right shape. Wikis and shared drives lose them.
6. Pick the smallest template that fits. Heavier isn't better. Lighter isn't sloppier. The right shape is the one that surfaces what a busy reviewer needs to see.

Why have a gallery of templates?

Most teams adopt one ADR template (often Nygard's, sometimes MADR's) and apply it to every decision. That works — until the day a one-line decision needs a lightweight shape, or a one-way door needs more rigor than the standard template gives. A small menu of templates means you can match the shape to the call.

The six templates in this gallery aren't all "best." They're each right for a different shape of decision. The compare view is the fastest way to pick.

Where this fits in the suite

• playbook — frameworks for how to decide (build vs. buy, two-way vs. one-way, scope cuts).
• brief — the public library of decisions other teams have shipped, with the reasoning.
• adr — the formal artifacts engineering teams keep in repos, with the right shape for the right call.
• app — the operator console: stalled decisions, the smallest memo to unblock, routing.