ADR
References:
Is one warranted?
- Yes: architecturally significant and hard to reverse — sets
precedent others will follow, locks in a dependency, shapes a public
API, picks between non-trivial alternatives.
- No: tactical implementation choice, easily reversed, personal style,
framework-default behaviour. A commit message or PR description
carries it better.
- If not warranted, say so and stop. ADR sprawl makes the collection
worth less.
Template
Detect, don't impose:
- If the repo already has ADRs (
docs/adr/, doc/adr/,
docs/decisions/, docs/explanation/adr/), read one and match
shape.
- If repo-local
CLAUDE.md names a template ("ADRs use MADR"),
respect it.
- Otherwise: Nygard for a single decision; escalate to MADR
only when alternatives analysis is genuinely load-bearing (3+
options worth comparing across multiple drivers). Call that case a
comparison ADR.
Nygard skeleton
- Title —
# N. <imperative phrase> (e.g. "Use PostgreSQL").
- Status —
Proposed initially; user promotes to Accepted,
Superseded by NNNN, or Deprecated. Don't pre-mark Accepted.
- Context — forces in play, constraints, what made this a
decision.
- Decision —
We will <do X>. Active voice.
- Consequences — what becomes easier and harder; positive,
negative, neutral.
MADR
Use the upstream template at https://adr.github.io/madr/; don't
re-derive it here. Sections that earn their weight: Decision Drivers,
Considered Options (with pros/cons), Decision Outcome.
Decompose and verify
Comparison ADRs only; a single-decision Nygard record skips it.
A comparison ADR that starts from an inherited conclusion
reverse-justifies it with abstract drivers ("cross-surface leverage",
"maintenance burden") and never examines the facts that decide it. Run
this interview with the user before any Context, driver, or outcome
prose exists:
- Options — name the concrete candidates under comparison.
- Requirements — get the targets from the user, enumerated. Not
from memory, not inferred from the options.
- Option × requirement — for each pair, state the fact and where
it came from. Reachability, feasibility, and cost decide most tool
choices; verify those pairs first. Anything assumed, recalled, or
unchecked is a blocker: search it before continuing, and never
write the Decision Outcome over an open one.
- Inherited answer — name the option that arrived pre-chosen, if
any. Check whether each driver tests that option or flatters it; a
driver only the pre-chosen option satisfies is there to justify it.
- Draft — every Decision Driver cites a verified fact from step
- Cut any driver that can't; don't hedge it.
Location and filename
- Default
docs/adr/ for new repos. Match existing layout if present.
- Filename:
NNNN-kebab-title.md, NNNN is the next 4-digit sequence
(0001, 0002, ...).
- If no ADRs exist yet, scaffold
0000-record-architecture-decisions.md
first (the meta-ADR establishing the practice itself).
Procedure
- Decide warranted vs. not. If not, stop.
- Detect template and location from existing ADRs or repo
CLAUDE.md.
- For a comparison ADR, run Decompose and verify before drafting.
- Compute next sequence number. If first ADR, scaffold the meta-ADR
too.
- Surface chosen template, location, and a one-line decision summary
before drafting full content. Apply after agreement.
- Default Status to
Proposed. The team promotes it after the
decision is actually made.
1---2name: adr3description: Audit, write, or revise Architecture Decision Records (ADRs), including the decision of whether one is warranted. Use when an architecturally significant decision needs recording, when reviewing an existing ADR collection, or when adding ADRs to a project that has none. Detects existing template (Nygard or MADR) and defaults to Nygard for new repos. Gates comparison ADRs through a decompose-and-verify interview before drafting.4---56# ADR78References:910- <https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions> — Nygard, original.11- <https://adr.github.io/madr/> — MADR, structured variant.12- <https://adr.github.io/> — umbrella, organisational guidance.1314## Is one warranted?1516- Yes: architecturally significant *and* hard to reverse — sets17 precedent others will follow, locks in a dependency, shapes a public18 API, picks between non-trivial alternatives.19- No: tactical implementation choice, easily reversed, personal style,20 framework-default behaviour. A commit message or PR description21 carries it better.22- If not warranted, say so and stop. ADR sprawl makes the collection23 worth less.2425## Template2627Detect, don't impose:28291. If the repo already has ADRs (`docs/adr/`, `doc/adr/`,30 `docs/decisions/`, `docs/explanation/adr/`), read one and match31 shape.322. If repo-local `CLAUDE.md` names a template ("ADRs use MADR"),33 respect it.343. Otherwise: **Nygard** for a single decision; escalate to **MADR**35 only when alternatives analysis is genuinely load-bearing (3+36 options worth comparing across multiple drivers). Call that case a37 *comparison ADR*.3839### Nygard skeleton4041- **Title** — `# N. <imperative phrase>` (e.g. "Use PostgreSQL").42- **Status** — `Proposed` initially; user promotes to `Accepted`,43 `Superseded by NNNN`, or `Deprecated`. Don't pre-mark `Accepted`.44- **Context** — forces in play, constraints, what made this a45 decision.46- **Decision** — `We will <do X>`. Active voice.47- **Consequences** — what becomes easier *and* harder; positive,48 negative, neutral.4950### MADR5152Use the upstream template at <https://adr.github.io/madr/>; don't53re-derive it here. Sections that earn their weight: Decision Drivers,54Considered Options (with pros/cons), Decision Outcome.5556## Decompose and verify5758Comparison ADRs only; a single-decision Nygard record skips it.5960A comparison ADR that starts from an inherited conclusion61reverse-justifies it with abstract drivers ("cross-surface leverage",62"maintenance burden") and never examines the facts that decide it. Run63this interview with the user before any Context, driver, or outcome64prose exists:65661. **Options** — name the concrete candidates under comparison.672. **Requirements** — get the targets from the user, enumerated. Not68 from memory, not inferred from the options.693. **Option × requirement** — for each pair, state the fact and where70 it came from. Reachability, feasibility, and cost decide most tool71 choices; verify those pairs first. Anything assumed, recalled, or72 unchecked is a blocker: search it before continuing, and never73 write the Decision Outcome over an open one.744. **Inherited answer** — name the option that arrived pre-chosen, if75 any. Check whether each driver tests that option or flatters it; a76 driver only the pre-chosen option satisfies is there to justify it.775. **Draft** — every Decision Driver cites a verified fact from step78 3. Cut any driver that can't; don't hedge it.7980## Location and filename8182- Default `docs/adr/` for new repos. Match existing layout if present.83- Filename: `NNNN-kebab-title.md`, NNNN is the next 4-digit sequence84 (`0001`, `0002`, ...).85- If no ADRs exist yet, scaffold `0000-record-architecture-decisions.md`86 first (the meta-ADR establishing the practice itself).8788## Procedure89901. Decide warranted vs. not. If not, stop.912. Detect template and location from existing ADRs or repo `CLAUDE.md`.923. For a comparison ADR, run *Decompose and verify* before drafting.934. Compute next sequence number. If first ADR, scaffold the meta-ADR94 too.955. Surface chosen template, location, and a one-line decision summary96 before drafting full content. Apply after agreement.976. Default Status to `Proposed`. The team promotes it after the98 decision is actually made.
alunduil