Architecture Decision Records (ADRs)
Significant decisions get written down at the project level, with date and who decided, so the
reasoning survives the people and the calendar. This is mandatory for big decisions — see the trigger
list below — not optional.
What counts as "big" (write an ADR)
- Choosing/replacing/dropping a library, framework, database, or major dependency.
- API contract, data schema, or public interface shape.
- An architectural pattern or boundary (how modules/services are split, sync vs async, etc.).
- Security, auth, privacy, or compliance approach.
- Build, packaging, hosting, or deployment strategy.
- Any decision that is costly to reverse or that a future maintainer will ask "why?" about.
Small, easily-reversed choices do not need an ADR — keep them in code review or project memory.
When unsure whether a decision is big enough, ask the user briefly rather than skipping it.
Where they live
docs/adr/NNNN-kebab-title.md at the repo root (create docs/adr/ if missing). Four-digit
sequential number, starting at 0001. Keep docs/adr/README.md as an index (a one-line link per
ADR); add the new entry when you create one.
Creating an ADR
- Find the next number: highest existing
NNNN in docs/adr/ + 1 (start at 0001).
- Copy
template.md (next to this SKILL.md) to docs/adr/NNNN-<short-kebab-title>.md.
- Fill every field:
- Date — today's actual date,
YYYY-MM-DD. Never guess it.
- Deciders — who actually made the call. Ask the user who to credit if unclear; you may seed
it from
git config user.name / the user's identity, but don't invent names. List everyone
involved, not just the author.
- Status —
Proposed until agreed, then Accepted. Later ADRs may set an old one to
Superseded by ADR-NNNN (never delete or rewrite a decided ADR — supersede it).
- Context, Decision, Consequences, Alternatives considered — see the template.
- Add the one-line entry to
docs/adr/README.md.
- Keep it short: half a page. The value is the why and the trade-offs, not prose volume.
Relationship to other skills
keep-architecture links to ADRs for the "why" behind the structure — cross-reference them.- A one-line pointer in project memory ("Decisions") is fine, but the ADR is the source of truth.
1---2name: adr3description: Record significant project decisions as Architecture Decision Records (ADRs). Use whenever a decision would be expensive to reverse or important to remember — choosing a library/framework/database, an API or schema shape, an architectural pattern, a security or auth approach, a build/deploy choice, or dropping/replacing a technology. Also use when the user says "ADR", "record this decision", or "why did we choose X". Captures date, deciders, context, the decision, and consequences.4---56# Architecture Decision Records (ADRs)78Significant decisions get written down at the project level, with **date and who decided**, so the9reasoning survives the people and the calendar. This is mandatory for big decisions — see the trigger10list below — not optional.1112## What counts as "big" (write an ADR)1314- Choosing/replacing/dropping a library, framework, database, or major dependency.15- API contract, data schema, or public interface shape.16- An architectural pattern or boundary (how modules/services are split, sync vs async, etc.).17- Security, auth, privacy, or compliance approach.18- Build, packaging, hosting, or deployment strategy.19- Any decision that is costly to reverse or that a future maintainer will ask "why?" about.2021Small, easily-reversed choices do **not** need an ADR — keep them in code review or project memory.22When unsure whether a decision is big enough, ask the user briefly rather than skipping it.2324## Where they live2526`docs/adr/NNNN-kebab-title.md` at the repo root (create `docs/adr/` if missing). Four-digit27sequential number, starting at `0001`. Keep `docs/adr/README.md` as an index (a one-line link per28ADR); add the new entry when you create one.2930## Creating an ADR31321. Find the next number: highest existing `NNNN` in `docs/adr/` + 1 (start at `0001`).332. Copy `template.md` (next to this SKILL.md) to `docs/adr/NNNN-<short-kebab-title>.md`.343. Fill every field:35 - **Date** — today's actual date, `YYYY-MM-DD`. Never guess it.36 - **Deciders** — who actually made the call. Ask the user who to credit if unclear; you may seed37 it from `git config user.name` / the user's identity, but don't invent names. List everyone38 involved, not just the author.39 - **Status** — `Proposed` until agreed, then `Accepted`. Later ADRs may set an old one to40 `Superseded by ADR-NNNN` (never delete or rewrite a decided ADR — supersede it).41 - **Context**, **Decision**, **Consequences**, **Alternatives considered** — see the template.424. Add the one-line entry to `docs/adr/README.md`.435. Keep it short: half a page. The value is the *why* and the *trade-offs*, not prose volume.4445## Relationship to other skills4647- `keep-architecture` links to ADRs for the "why" behind the structure — cross-reference them.48- A one-line pointer in project memory ("Decisions") is fine, but the ADR is the source of truth.
soukupl