| name | adr-authoring |
| description | Author MADR-style Architecture Decision Records under `.specs/<feature-id>/adr/`. Use whenever a non-obvious technical decision is made, a default is overridden, or a waiver is granted. |
| when_to_use | ["Phase 3 (Plan) — capturing every design decision that has alternatives.","Phase 6 (Validate) — when waiving a harness gate.","Phase 7 (Code review) — when accepting a finding without fixing it."] |
| authoritative_references | ["https://adr.github.io/madr/",".claude/templates/adr.template.md"] |
ADR authoring
When to write one
Write an ADR if any of:
- The decision has plausible alternatives a future engineer might prefer.
- The decision overrides a default in this toolkit (skill says X, we do Y).
- The decision waives a harness gate (mutation, coverage, OpenAPI breaking, CVE).
- The decision constrains future work (e.g. "we will not use Kafka in this module").
Do not write an ADR for:
- Choices uniquely forced by the source ticket.
- Trivial mechanical decisions (variable naming).
File layout
.specs/<feature-id>/adr/NNN-<slug>.md where NNN is zero-padded and unique per feature.
Required sections (MADR)
- Title — short, decision-shaped: "Use Liquibase for schema migrations".
- Status —
proposed | accepted | rejected | superseded by NNN | deprecated.
- Context — what problem, what constraints, what we know.
- Decision drivers — the forces (perf, team familiarity, cost, security).
- Considered options — at least two.
- Decision outcome — chosen option and one-paragraph justification.
- Consequences — positive AND negative.
- Pros and cons of each option — symmetric table.
- Links — back to
01-spec.md, 03-design.md section, related ADRs, external references.
Naming examples
.specs/shop-1422-gift-card-checkout/adr/
├── 001-use-liquibase-for-migrations.md
├── 002-redeem-balance-stored-as-cents-int.md
├── 003-waive-mutation-on-config-classes.md
└── 004-breaking-api-change-error-envelope.md
Anti-patterns
- ADR with one option (it's a memo, not a decision).
- ADR with no
Consequences section, especially no negatives.
- "We chose X because it's better" — give a driver and a measurable reason.
- ADR written after the code is merged — write it during Plan, refine during Validate.
- Editing an
accepted ADR. Mark it superseded by NNN and write a new one instead.
Status flow
proposed → accepted → (later) superseded
↓
rejected
A proposed ADR is fine to merge; it documents the current direction. A rejected ADR is also valuable — it records why the obvious option was not chosen, saving the next person from re-asking.
