Architecture decision record
The lightest spec in the gallery — and the one future you will thank you for. An ADR captures a single significant decision: the context that forced it, the options weighed, what was chosen, and what it costs.
Technology choices, architectural patterns, build-vs-buy calls, data-store selections, and any decision that will be expensive to revisit. Rule of thumb: if someone will ask "why did we do it this way?" in a year, write the ADR now while the answer is fresh.
Section-by-section, annotated
§1 Status & metadata
Title, date, status (proposed / accepted / superseded), deciders. ADRs are immutable once accepted — a changed decision gets a new ADR that supersedes the old one. Good looks like: a numbered sequence you can browse like a log.
§2 Context
The situation forcing the decision: the problem, constraints, stakeholders, and what happens if no decision is made. This is the section future readers need most. Good looks like: someone in two years understands why this was even a question.
§3 Options considered
Every serious alternative, with honest pros and cons — including "do nothing." The rejected options are as valuable as the chosen one: they stop the debate from restarting. Good looks like: at least two real alternatives, steelmanned.
§4 Decision
What was chosen and why, in one clear paragraph. Links to the reasoning in §3, not new reasoning. Good looks like: a single sentence a new hire could quote.
§5 Consequences
What gets better, what gets worse, and what would cause this decision to be revisited. Honest consequences are what make ADRs trustworthy. Good looks like: at least one negative consequence named explicitly.
Copy it, decide, record
# ADR-NNNN: [Short decision title] | Field | Value | |----------|----------------------------------------| | Status | Proposed / Accepted / Superseded | | Date | [YYYY-MM-DD] | | Deciders | [Names] | | Tags | [e.g. database, auth, infra] | _Superseded by: [ADR-NNNN — only if applicable]_ ## Context [The situation forcing this decision. What problem are we solving? What constraints apply — budget, timeline, compliance, team skills? Who is affected? What happens if we decide nothing?] ## Options considered ### Option A: [Name] - **Pros:** [Honest advantages] - **Cons:** [Honest disadvantages] - **Cost:** [Rough: build time, money, operational burden] ### Option B: [Name] - **Pros:** [Honest advantages] - **Cons:** [Honest disadvantages] - **Cost:** [Rough] ### Option C: Do nothing - **Pros:** [No change cost] - **Cons:** [The problem persists; quantify it] ## Decision [What we chose and why, in one clear paragraph. Reference the reasoning above rather than introducing new reasoning.] ## Consequences **Positive:** - [What gets better] **Negative:** - [What gets worse — name at least one] **Neutral / operational:** - [New runbooks, monitoring, skills the team must acquire] **Revisit when:** - [The conditions under which this decision should be re-examined, e.g. "when request volume exceeds X" or "at the next contract renewal"]
Keep ADRs in your repo at docs/adr/, numbered sequentially (adr-0001-...), and never edit an accepted ADR — write a new one that supersedes it. The sequence is your architecture's diary.
| Rev | Date | Description |
|---|---|---|
| 1.0 | 2026-09-20 | Initial publication. |