adr-template

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:

1. Write the new ADR with its own number.
2. In the new ADR's Context, cite the old: "Supersedes ADR 0007."
3. Update the old ADR's Status: Status: Superseded by ADR 0014.
4. 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.