create-adr
创建MADR格式架构决策记录。用于记录架构决策、记录技术选择或创建架构决策记录(ADR)。
📖 中文导读:创建MADR格式架构决策记录。用于记录架构决策、记录技术选择或创建架构决策记录(ADR)。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: create-adr description: Create MADR-format Architecture Decision Record. Use when recording an architectural decision, documenting a technical choice, or creating an ADR.
ADR Creation Skill
Purpose
Create Architecture Decision Records (ADRs) using the MADR (Markdown Any Decision Records) format. ADRs capture important architectural decisions and their context for future reference.
Smart Interaction
ASK the User When:
- Creating new ADR: Confirm ADR number (auto-suggest next available)
- Deleting ADR: Always confirm, suggest "Deprecated" status instead
- Superseding ADR: Confirm which ADR is being replaced
PROCEED Autonomously When:
- Updating existing ADR: Add consequences discovered during implementation
- Linking ADRs: Add related ADR links
- Fixing typos: Non-destructive corrections
- Updating status: Proposed → Accepted after team approval
Instructions
When creating an ADR:
- Find the next ADR number by checking
/docs/decisions/ - Use the MADR template at
templates/madr.md - Output to
/docs/decisions/NNNN-[kebab-case-title].md
Template
Use the template at: .claude/skills/create-adr/templates/madr.md
ADR Naming Convention
Format: NNNN-kebab-case-title.md
Examples:
0001-use-supabase-for-database.md0002-tanstack-query-for-state.md0003-fumadocs-for-documentation.md
Status Definitions
| Status | Meaning |
|---|---|
| Proposed | Under discussion, not yet decided |
| Accepted | Decision has been made and applies |
| Deprecated | No longer applies, but kept for history |
| Superseded | Replaced by another ADR (link to it) |
When to Create an ADR
Create an ADR when:
- Choosing between technologies/libraries
- Defining architectural patterns
- Making decisions that affect multiple parts of the system
- Making decisions that are hard to reverse
- Team needs to understand "why" something was done
Output Location
All ADRs go to: /docs/decisions/NNNN-title.md
Quality Checklist
Before completing:
- ADR number is sequential (check existing ADRs)
- Title is clear and descriptive
- Context explains the problem, not the solution
- Decision is stated clearly
- Consequences cover positive, negative, and neutral
- At least 2 options were considered
- Related links are included
- YAML frontmatter has title and description
Examples
Creating New ADRs (Will Ask User)
- "Create an ADR for choosing Supabase" → Ask: Confirm number 0001?
- "Record the decision to use TanStack Query" → Suggest next number
Updating Existing ADRs (Autonomous)
- "Mark ADR-001 as accepted" → Updates status
- "Add implementation notes to ADR-003" → Adds to Notes section
- "Link ADR-002 to ADR-005" → Adds to Related section
Status Changes
- "Deprecate ADR-002" → Updates status, adds deprecation note
- "ADR-003 supersedes ADR-001" → Updates both ADRs with cross-references