Architecture Decision Records

An ADR captures why we made an expensive-to-reverse decision, so the next person does not relitigate it. ADRs live in each repo at /docs/adr, not in this wiki — this page is the template and the guidance.

stateDiagram-v2
  [*] --> Proposed
  Proposed --> Accepted
  Proposed --> Rejected
  Accepted --> Accepted: amended (dated, append-only)
  Accepted --> Superseded: decision reversed
  Accepted --> Deprecated
  Superseded --> [*]
  Deprecated --> [*]

When to write one

Write an ADR for expensive-to-reverse decisions:

• A database, message broker, auth model, or major framework.
• A cross-cutting pattern — multi-tenancy, caching strategy, API versioning, a data-ownership boundary.
• A deliberate deviation from a company default.

Do not write one for a library swap, a naming tweak, or a local refactor. If reversing it is a small PR, skip the ADR.

The granularity test: if the next revision would change a number, it is calibration, not a decision. Record it in the feature’s design doc. One ADR per boundary — a seam, a dependency, an ownership rule — never one per iteration behind that boundary. Bug fixes are never ADRs.

Where they live

• One Markdown file per decision: /docs/adr/NNNN-short-title.md, numbered sequentially.
• Every /docs/adr carries a README.md index — one row per ADR: number, title, status, state, scope. Updated in the same PR that adds or supersedes one. A folder of 26 files with no index is a folder nobody reads, and a stale index is a review blocker.
• A playbook is not an ADR. If a document tells you how to build something, it is a playbook and lives in /docs/playbooks/. If it records why a choice was made and what it costs, it is an ADR. One shape per folder.

Template

# NNNN. Short decision title

Status: Proposed | Accepted | Superseded by NNNN | Deprecated
State: Current | Approved Intent | Target
Date: YYYY-MM-DD
Scope: which module or subsystem this governs
Supersedes / Amends / Extends: NNNN (links, when applicable)
Enforcement: the committed test, analyzer, or linter rule that fails the
             build — or the word `Review-only`

## Context
The forces at play: the problem, constraints, and options considered.
Facts only — no decision yet.

## Decision
The choice we made, in active voice: "We will ...".

## Rules
The imperatives a reader must follow. "Do not merge the two contexts."

## Consequences
What becomes easier and what becomes harder, including new risks
and follow-up work.

• Scope tells a reader in one line whether the ADR applies to them.
• Enforcement must name a check that exists on the branch that merges the ADR — a declared check nobody writes is how a convention quietly stops being one. Say Review-only honestly rather than naming a test you intend to write.
• State is not Status: Status says whether the decision is agreed, State whether it is built. Nothing marked Approved Intent or Target may be described as implemented — not in a doc, not in a PR, not in an agent’s answer.

Amend or supersede

ADRs are append-only, not frozen.

• Amend when the decision is sharpened or recalibrated: append a dated ## Amendment — YYYY-MM-DD section, or prepend a dated status banner. Never rewrite the original Context or Decision text.
• Supersede only when the decision is reversed: a new ADR, with links in both directions.
• A superseded ADR is never deleted — its history is the point.

Review

• An ADR merges in the PR that implements it, linked to the work item. An ADR written after the merge is documentation, not a decision.
• The PR’s reviewers approve the ADR and the code together. The CTO approves any ADR that deviates from a company default.

See also: Examples · AI Agent Context · Engineering Standards.