| name | adr-template |
| description | Architecture Decision Record template + when to write one. An ADR is a short markdown record of a significant architectural decision, its context, and its consequences — durable history that answers "why is it like this?" months later. ROUTE BY INTENT — load when making a non-obvious architectural decision ("이걸 왜 이렇게 했지?" later, "should we use X or Y for..."), when a decision is hard to reverse, or when you need to look up why a past choice was made. NOT for implementation details (that's code comments) or ephemeral task notes (that's a spec). |
ADR template — record decisions that outlive the moment
An ADR (Architecture Decision Record) answers: "Why did we choose this, given what we knew then?" It's not a design doc, not a spec — it's a decision snapshot. Future-you (or a new contributor) reads it to understand a choice that isn't obvious from the code alone.
When to write an ADR
Write one when a decision is:
- Hard to reverse (data model, public API, framework choice, auth strategy)
- Non-obvious (the code alone doesn't explain why; a reasonable reader would ask "why?")
- Contested (alternatives were seriously considered and rejected)
Do NOT write an ADR for:
- Implementation details (use code comments)
- Ephemeral task state (use a spec)
- Obvious conventions (use a style guide)
- Every small choice (ADR ceremony on trivia is noise)
File location and naming
docs/adr/
├── 0001-use-fastapi-over-flask.md
├── 0002-worktree-per-task.md
├── 0003-no-premature-done-claim.md
└── ...
- Zero-padded 4-digit number, kebab-case description.
- Next number = highest existing + 1. (Script:
ls docs/adr/ | sort | tail -1 to find the max.)
- One decision per file.
Template
# ADR <number>: <decision title in imperative or declarative mood>
Date: <YYYY-MM-DD>
Status: <Proposed | Accepted | Superseded by ADR NNNN | Deprecated>
## Context
<What is the issue / force / situation that motivates this decision? 1-3 paragraphs.
Be concrete: what problem were we trying to solve, what constraints were in play,
what alternatives were on the table.>
## Decision
<What we decided. 1-2 paragraphs, declarative. "We will..." / "We adopt...">
State the decision plainly before justifying it.>
## Consequences
<What follows from this decision — positive, negative, neutral. Be honest about
trade-offs: what becomes easier, what becomes harder, what risk we accepted.>
## Alternatives considered
<For each serious alternative: name it, state why we rejected it. This is the
most valuable section for future readers — it shows the decision was considered,
not default.>
Style
- Past tense, decided mood. "We chose FastAPI because..." not "We should choose FastAPI."
- Concrete over abstract. "SessionEnd hook misses 54.5% of sessions" beats "hooks are unreliable."
- Name the measurement. If a number drove the decision, include the number.
- Short. An ADR is 1-2 pages. If it's longer, the decision is probably a design doc, not an ADR.
- Never retro-edit for clarity. An ADR is a snapshot of what was decided then. If the context changes, write a NEW ADR that supersedes it (and update the Status line of the old one).
Superseding
When a later decision reverses an earlier one:
- Write the new ADR with its own number.
- In the new ADR's Context, cite the old: "Supersedes ADR 0007."
- Update the old ADR's Status:
Status: Superseded by ADR 0014.
- Do NOT delete or rewrite the old ADR — it's history. A reader following the supersede chain sees how thinking evolved.
Anti-patterns
- ADR-as-design-doc — 10 pages of architecture. Split: the decision is the ADR; the design is a separate
design.md.
- ADR-without-alternatives — "We chose X." Why? What else? Without alternatives, it reads as rationalization.
- Retro-active ADRs — writing an ADR months after the decision, reconstructed from memory. The value is in capturing the decision WHEN MADE; a retro-ADR is fiction.
- Too many ADRs — one per trivial choice. If the decision is obvious, code comments suffice. An ADR should feel worth the reader's time.
