Architecture Decision Record
Write an Architecture Decision Record from a proposed change, including context, options, consequences, and what was rejected. Use when asked to write an ADR, record a design decision, or explain why this approach won.
Copy the file into your agent runtime. Cursor loads personal skills from ~/.cursor/skills/architecture-decision-record/SKILL.md and project skills from .cursor/skills/architecture-decision-record/SKILL.md. Claude Code looks in .claude/skills/architecture-decision-record/SKILL.md.
Architecture Decision Record
When to use
A choice is about to be (or was) made and the team will otherwise forget why. Triggers: write an ADR, record this decision, why did we pick X.
What it does
Produces a short ADR: status, context, decision, options considered, consequences, and follow-ups.
Steps
- Title as a decision, not a topic (
Use SQS for webhook delivery, notMessaging). - Status: proposed / accepted / superseded (link the successor if known).
- Context: the force that made a choice necessary. Facts, not vibes.
- Options: at least two real alternatives, each with a trade-off. Include "do nothing."
- Decision: one paragraph, present tense.
- Consequences: good, bad, and the follow-up work the decision creates.
Output
# ADR-NNN: Title Status: Context: Options: Decision: Consequences: Follow-ups:
Guardrails
Do not hide a rejected option that was actually cheaper. Do not write an ADR for a reversible default (lint rules, folder names) unless the user asked. If requirements are missing, list them under Context as unknowns instead of filling them in.