| name | adr |
| description | Record Architecture Decision Records (ADRs) when significant technical decisions are made. MUST trigger when switching, migrating, or replacing libraries, SDKs, frameworks, databases, or infrastructure. MUST trigger when making decisions that shape how the system works going forward: deployment strategies, service boundaries, data flow patterns, auth models, API design. Also trigger when choosing between alternatives, making trade-offs, or changing a previous approach. Common signals: "let's go with X", "we should use Y", "I've decided to", "switching from X to Y", "the trade-off is", "pros and cons of", "why did we choose X?", or "document this decision". Even if the user doesn't say "ADR", if a decision is being made that future-them would want to remember the reasoning for, this skill applies. Record the ADR proactively, don't wait to be asked.
|
| version | 1.0.0 |
Architecture Decision Records
ADRs capture the why behind significant technical decisions so that future-you (or teammates) can understand the reasoning without re-deriving it.
When to record an ADR
Record one when:
- Choosing between real alternatives - at least two viable options existed and you picked one for reasons
- The decision is hard to reverse - switching later would cost significant effort
- Future-you would ask "why did we do this?" - the reasoning isn't obvious from the code
- Changing a previous decision - especially important to capture what changed and why
Don't record ADRs for: trivial choices (variable names, formatting), obvious decisions (use git for version control), or temporary experiments.
On project start
If docs/adr/ exists, skim the titles to understand past decisions. If you're about to recommend something that contradicts an existing ADR, flag it:
"Heads up: ADR 0003 chose X for Y reason. Are we revisiting that decision? If so I'll record a new ADR."
How to record
Step 1: Find or create the ADR directory
Look for existing ADRs in the project. Default location: docs/adr/. Create it if it doesn't exist.
Step 2: Determine the next number
Read existing ADR files to find the highest number, increment. Files follow this pattern:
NNNN-short-slug.md
Zero-padded to 4 digits. Start at 0001 if none exist. Slug should be lowercase, hyphen-separated, 3-6 words describing the decision.
Examples: 0001-use-postgres-over-dynamodb.md, 0002-monorepo-structure.md
Step 3: Write the ADR
# NNNN. Title of Decision
**Date**: YYYY-MM-DD
## Context
What is the situation? What problem are we solving? What constraints exist?
2-4 sentences. Enough background for someone unfamiliar to understand why
a decision was needed.
## Options Considered
- **Option A**: Brief description. Key trade-off.
- **Option B**: Brief description. Key trade-off.
## Decision
What did we decide and why? Be specific about the reasoning.
Reference concrete evidence (benchmarks, cost calculations,
compatibility requirements) when available.
## Consequences
- What becomes easier or possible
- What becomes harder or impossible
- What we'll need to watch out for
- Any follow-up work this creates
Writing rules
- Be concrete, not abstract. "Postgres handles our query patterns with 2ms p99 vs DynamoDB's 8ms" beats "the relational DB performed better."
- Capture reasoning, not just conclusion. The code shows what; the ADR captures why.
- Include numbers when you have them. Costs, latency, accuracy, memory usage.
- Keep it short. Half a page, not three pages. Link to detailed docs if needed.
Step 4: Summarize
After writing, tell the user:
- The file path
- A one-line summary of what was recorded
- Note it'll be committed with the next git commit
Proactive suggestions
When you notice a decision being made in conversation but the user hasn't asked for an ADR:
"This looks like a decision worth recording as an ADR. Want me to capture it in docs/adr/?"
One suggestion per decision. If they say no or ignore it, move on. Don't be pushy.
