adr
Document architectural decisions in standardized ADR format. This skill should be used when making significant technical decisions, choosing between approaches, establishing patterns, or when other skills (create-plan, implement-plan, brainstorm) identify decisions that need documentation. Triggers on "document decision", "create ADR", "architectural decision", or automatically when invoked by other skills during planning and implementation.
mhylle · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add mhylle/claude-skills-collection --skill adr技能说明
name: adr description: Document architectural decisions in standardized ADR format. This skill should be used when making significant technical decisions, choosing between approaches, establishing patterns, or when other skills (create-plan, implement-plan, brainstorm) identify decisions that need documentation. Triggers on "document decision", "create ADR", "architectural decision", or automatically when invoked by other skills during planning and implementation. argument-hint: "[decision-title?]"
Architectural Decision Records (ADR)
Contents
- Design Principles
- When to Use This Skill
- ADR Location and Naming
- Getting the Next ADR Number
- ADR Status Values
- Creating an ADR
- Workflow
- Integration with Other Skills
- Response Format (for subagent use)
- Listing Existing ADRs
- Searching ADRs
- Deprecating an ADR
- Quality Checklist
- Best Practices
- Resources
Reference files (open one when a step points to it):
references/adr-template.md: ADR-NNNN: [Title]references/index-template.md: Architectural Decision Records
Document significant architectural and technical decisions in a standardized, searchable format optimized for LLM context efficiency.
Design Principles
Context Conservation
ADRs are designed for efficient LLM consumption:
- Small, focused files - One decision per ADR, minimal content
- Quick Reference block - First 5 lines summarize the entire ADR
- Central INDEX.md - Single file listing all ADRs with one-line summaries
LLM Reading Strategy
When consulting ADRs, follow this tiered approach:
TIER 1: Read INDEX.md (one file, all summaries)
↓ Identify potentially relevant ADRs
TIER 2: Read Quick Reference block only (first 10 lines of candidate ADRs)
↓ Confirm relevance
TIER 3: Read full ADR content (only when details are needed)
Implementation:
# Tier 1: Scan index
Read("docs/decisions/INDEX.md")
# Tier 2: Quick reference only (use limit parameter)
Read("docs/decisions/ADR-0001-title.md", limit=10)
# Tier 3: Full content (only if needed)
Read("docs/decisions/ADR-0001-title.md")
When to Use This Skill
Directly invoked when:
- Making a significant technical decision
- Choosing between architectural approaches
- Establishing patterns or conventions
- Documenting why a particular technology was selected
Automatically invoked by other skills when:
- create-plan: Design decision is made in Phase 4
- implement-plan: Mismatch discovered or architectural choice made during implementation
- brainstorm: Key decisions identified during analysis
ADR Location and Naming
Directory: docs/decisions/
Naming Convention: ADR-NNNN-short-title.md
NNNN: Zero-padded sequential number (0001, 0002, etc.)short-title: Lowercase, hyphenated description (max 50 chars)
Examples:
ADR-0001-use-jwt-for-authentication.mdADR-0002-postgresql-over-mongodb.mdADR-0003-event-sourcing-for-audit.md
Getting the Next ADR Number
Before creating an ADR, determine the next sequence number:
# Find highest existing ADR number
ls docs/decisions/ADR-*.md 2>/dev/null | sort -t- -k2 -n | tail -1 | grep -oP 'ADR-\K\d+' || echo "0000"
If no ADRs exist, start with 0001.
ADR Status Values
| Status | Meaning |
|---|---|
| Proposed | Under consideration, not yet decided |
| Accepted | Decision made, ready for implementation |
| Deprecated | Was accepted, now superseded |
| Superseded | Replaced by another ADR (link to replacement) |
Creating an ADR
Required Information
Gather these inputs (ask user if not provided):
| Field | Description | Required |
|---|---|---|
| Title | Short, descriptive title | Yes |
| Context | Why is this decision needed? | Yes |
| Options | What alternatives were considered? | Yes |
| Decision | What was decided? | Yes |
| Rationale | Why this option? | Yes |
| Consequences | What are the implications? | Yes |
| Related ADRs | Links to related decisions | If applicable |
ADR Template
Use this format (also in references/adr-template.md):
# ADR-NNNN: [Title]
> **Quick Reference** | Status: [Accepted] | Date: [YYYY-MM-DD]
> **Decision**: [One sentence: what was decided]
> **Context**: [One sentence: why this decision was needed]
> **Alternatives**: [Rejected options, comma-separated]
> **Impact**: [Key areas affected, comma-separated]
---
## Context
[2-3 sentences max. The problem or opportunity being addressed.]
## Decision
**We will use [chosen option].**
[1-2 sentences explaining the decision.]
## Alternatives Considered
| Option | Pros | Cons | Why Not |
|--------|------|------|---------|
| [Option A] | [Key pro] | [Key con] | [Brief reason] |
| [Option B] | [Key pro] | [Key con] | [Brief reason] |
## Consequences
- **Positive**: [Key benefit]
- **Negative**: [Key trade-off]
- **Requires**: [What must be done as a result]
## Related
- [ADR-XXXX](./ADR-XXXX-title.md): [Relationship]
Quick Reference Block (Mandatory)
The first 5 lines after the title form the Quick Reference block. This enables LLMs to assess relevance without reading the full document.
Format (must fit in ~5 lines):
> **Quick Reference** | Status: [Status] | Date: [Date]
> **Decision**: [One sentence summary of what was decided]
> **Context**: [One sentence on why this decision was needed]
> **Alternatives**: [Comma-separated list of rejected options]
> **Imp
阅读完整来源 ↗