| name | adr |
| description | Record an architecture decision as an ADR in docs/adr/. Use when choosing between frameworks, libraries, databases, or architectural patterns; stating a decision with reasoning ("we decided X instead of Y because..."); or querying past decisions ("why did we choose X?").
|
| allowed-tools | Read, Write, Edit, Glob, Grep, AskUserQuestion |
Architecture Decision Records
You are recording or retrieving an Architecture Decision Record (ADR) for this
project. ADRs live in docs/adr/ at the repo root.
When to record
Record these decisions:
- Technology selections (frameworks, libraries, databases, cloud providers)
- Architectural patterns (state management, caching strategy, API design)
- Data modeling choices (schema design, indexing, query approach)
- Infrastructure and deployment models
- Security, authentication, or testing strategy changes
- Any choice where the "why we didn't pick the alternative" will matter in 6 months
Skip: trivial choices (variable naming, formatting, minor refactors).
ADR template
Every ADR file must include all of these sections:
# ADR-NNNN: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]
## Context
[2–5 sentences describing the situation, constraints, and forces at play]
## Decision
[1–3 sentences stating the change clearly and unambiguously]
## Alternatives Considered
### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific rejection reason]
### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific rejection reason]
## Consequences
### Positive
- [benefit 1]
### Negative
- [trade-off 1]
### Risks
- [risk and mitigation]
Workflow — recording a new ADR
- Scan existing ADRs —
Glob docs/adr/[0-9]*.md to find the highest existing number.
- Assign next ID — next sequential 4-digit number (e.g.,
0003).
- Gather context — ask the user for any missing details: who the deciders were, what alternatives were seriously considered, and what the consequences are.
- Draft the ADR — populate all mandatory sections from the template above.
- Present the draft — show it to the user for review before writing any file.
- Write the file —
docs/adr/NNNN-kebab-title.md (kebab-case title, all lowercase).
- Update the index — append a new row to the
| ADR | Title | Status | Date | table in docs/adr/README.md.
Workflow — reading / querying ADRs
- Check if
docs/adr/README.md exists. If not, offer to start the ADR directory.
- Read the README index table and find entries relevant to the user's question.
- Read the matching ADR file and summarise the Context and Decision sections.
- If no ADR matches, suggest recording one now.
Quality standards
- Each ADR should be readable in under 2 minutes.
- Every rejected alternative must include a Why not reason — "we didn't pick X" without a reason is useless.
- When a decision is superseded, update the old ADR's Status field to
superseded by ADR-NNNN and create the new ADR with a back-reference in its Context.
- Keep one decision per ADR — split if two separate choices are getting conflated.
