adr-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# ADR conventions

An **Architecture Decision Record** captures one decision, at the moment it is
taken, and is then frozen. It answers a question no other file can: *what did
we know, what else was on the table, and why did we pick this?*

**Always in English**, like every other document in the repository.

## The split with `ARCHITECTURE.md`

These two are complementary and must not drift into each other:

| | `ARCHITECTURE.md` | `docs/adr/` |
| --- | --- | --- |
| **Tense** | present — what *is* | past — what was decided, then |
| **Scope** | the whole system, coherent | one decision, isolated |
| **Lifecycle** | rewritten as the system changes | immutable once accepted |
| **History** | never | that is the point |

`ARCHITECTURE.md` is where history is banned precisely *because* the ADRs hold
it. Without them, the pressure to narrate the past leaks into the design doc
and rots it (see `architecture-conventions`).

**A decision that changes the design updates both, in the same change**: the
ADR records what was decided, and `ARCHITECTURE.md` — created if the project
has none yet — is rewritten to describe the new state as though it had always
been that way. `ARCHITECTURE.md` may link an ADR as the record; it must never
narrate the change.

## When to write one

The hard part, and where most ADR practices die — either nobody writes any, or
everything gets one and nobody reads them. **The second failure is the common
one**, and it is the expensive one: a repository with forty ADRs has no ADRs,
and since they are immutable, nobody can quietly tidy them away afterwards.

**The gate is architectural impact, not interestingness.** An ADR is for a
decision that changes the *shape* of the system: what the components are, what
each owns, how they talk to each other, what the whole thing depends on. The
test is blunt — **would someone drawing the architecture diagram have to redraw
it?** If not, then however good the decision is, however hard the call was,
however credible the alternative, it is not an ADR.

Write one when, and only when, the diagram changes because:

- a component, a datastore, or an external service or system the project
  depends on is added or removed — a library is not one;
- how the parts talk changes — protocol, sync to async, who owns what data;
- a constraint from outside — org policy, a platform limit, a quota, a
  compliance rule — forces the design to bend around it.

**When an ADR does carry a diagram, it is Mermaid** — the decision here is
usually a shape, and two small diagrams (the option taken, the one rejected)
argue it better than a page of prose. Never ASCII art, never a committed image:
an ADR is immutable, so a diagram nobody can edit is one nobody can ever fix.
See `diagram-conventions`.

**Do not write one for anything that leaves the diagram unchanged**: an
endpoint or a screen, a dependency bump, a refactor with no interface change, a
naming or ergonomics choice, a default value, a config or file format, a CLI
flag, an error-handling policy, a library picked over a near-identical one, or
a deliberate deviation from one of these conventions. Those are real decisions
and their reasoning is worth keeping — it goes in **`ARCHITECTURE.md` as
standing rationale, in the present tense** (see `architecture-conventions`;
create the file if the project has none yet), in
a code comment where it is genuinely farfelu, or nowhere.

**When it is not clear-cut, ask — and do not write it meanwhile.** How
load-bearing and how permanent a decision feels is a judgement about *this*
project, which the user holds and the diff does not. One question costs a
sentence; a directory of ADRs nobody asked for costs every future reader's
attention, permanently. **Never write an ADR unasked unless it is
unambiguously one of the three cases above** — and never write a batch of them
to document a project retrospectively.

## Files

- **`docs/adr/NNNN-kebab-case-title.md`** — four-digit zero-padded sequence
  from `0001`, allocated in order and **never renumbered**, never reused. A
  number is a permanent address: it is cited from `ARCHITECTURE.md`, from
  commit messages, from other ADRs.
- **The title states the decision, not the topic.**
  `0007-store-sessions-in-redis.md`, not `0007-session-storage.md`. Someone
  scanning the directory should read the decisions, not the agenda.
- **`docs/adr/README.md`** — the index: a table of number, title and status,
  updated in the same change. Undiscoverable ADRs get rewritten by accident.

## Template

```markdown
# NNNN. <the decision, as a sentence>

- **Status**: accepted
- **Date**: YYYY-MM-DD

## Context

What forced a decision: the constraint, the problem, what was already true.
Enough that someone who was not there can weigh the options themselves — and
no more. Facts, not the narrative of the meeting.

## Decision

What was decided, in the active voice: "we store sessions in Redis". A few
lines. This is the part people come back for.

## Consequences

What this makes easy, what it makes hard, and what it commits us to. The
negative half is not optional — an ADR listing only benefits is an
advertisement, and it is the part a future reader needs most.

## Alternatives considered

Each credible option, and the specific reason it lost. "Postgres: another
service to operate for a workload that fits in memory." One or two lines
each; an option nobody seriously weighed does not belong here.
```

From leroyguillaume/claude, MIT.

More from leroyguillaume/claude