adr
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 ex
SKILL.mddot_claude/skills/adr/SKILL.md
GitHubADR
References:
- https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions — Nygard, original.
- https://adr.github.io/madr/ — MADR, structured variant.
- https://adr.github.io/ — umbrella, organisational guidance.
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.mdnames 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 —
Proposedinitially; user promotes toAccepted. Don't pre-markAccepted. Later values: Accepted ADRs. - 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.
Accepted ADRs
An Accepted ADR is fixed. Its only edit is a Status transition:
Superseded by NNNN— the decision changed. Write the new ADR through Procedure; set this Status on its predecessor in the same change.Deprecated— the decision no longer applies and nothing replaces it, such as a dropped technology. This is the whole change.
Its facts record the state at decision time. A fact that has since changed routes to a new ADR or a transition.
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.mdfirst (the meta-ADR establishing the practice itself).
Procedure
- A request about an Accepted ADR ("update ADR N to reflect X"):
pick its transition from Accepted ADRs before opening the file.
Deprecatedstops here. - 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.