Structured process for creating high-quality Architecture Decision Records in MADR format. Triggers on keywords: "ADR", "Architecture Decision", "決定記録", "技術選定", "アーキテクチャ決定", "design decision", "技術的決定", "設計判断", "create ADR", "document decision", "非推奨化", "deprecation", "プロセス変更", "process change". Provides 6-phase process: pre-creation validation, template selection, reference collection, proofreading, index update, and error recovery with retry mechanisms. Available templates: technology-selection, architecture-pattern, process-change, deprecation.
This skill is limited to using the following tools:
EVALUATIONS.mdREADME.mdassets/architecture-pattern.mdassets/deprecation.mdassets/process-change.mdassets/technology-selection.mdreferences/impact-analysis.mdreferences/rollback-plan.mdreferences/test-coverage.mdscripts/pre-check.shscripts/update-index.shscripts/validate-adr.shCreate Architecture Decision Records in MADR format through a 4-stage process: validation, collection, generation, and confirmation to ensure documentation quality.
Purpose: Prevent duplicates and inconsistencies in advance
Actions:
Script: scripts/pre-check.sh
Check Items:
# 1. Duplicate ADR Check
- Title similarity check (warning if Levenshtein distance < 3)
- Search for existing ADRs on same technology/pattern
- Confirm related superseded ADRs
# 2. Naming Convention Validation
- Title length: 5-64 characters
- Prohibited character check (/:*?"<>|)
- Slug generation possibility confirmation
# 3. Date/Version Consistency
- Created date ≤ current date
- Consistency with project version
- Timezone confirmation
# 4. Directory Structure
- Confirm docs/adr/ exists
- Check write permissions
- Verify numbering rules (0001-9999)
Output Example:
🔍 ADR Pre-Creation Check
✅ Duplicate check: No similar ADRs found
✅ Naming convention: OK
✅ Date consistency: OK
⚠️ Warning: ADR-0015 may be related ("Adopt React for UI")
→ Please confirm relevance
✅ Ready to create
Next number: 0023
Purpose: Select appropriate structure based on ADR type
Template Types:
| Template | Use Case | Section Characteristics |
|---|---|---|
| technology-selection | Technology/library selection | Alternatives comparison focused |
| architecture-pattern | Architecture pattern | Detailed context & consequences analysis |
| process-change | Development process changes | Detailed decision drivers |
| deprecation | Deprecating existing technology | Migration plan required |
Selection Process:
📋 ADR Template Selection
Which category does this decision fall into?
1. Technology selection (library, framework, language)
2. Architecture pattern (structure, design policy)
3. Process change (workflow, rules)
4. Deprecation (retiring existing technology)
Selection > 1
✅ Template: technology-selection.md
Required sections:
- Context and Problem Statement
- Considered Options (minimum 3 recommended)
- Pros and Cons of the Options
- Decision Outcome
- Confirmation (implementation verification method)
Purpose: Systematically collect information that supports the decision
Script: scripts/collect-references.sh
Collection Targets:
# 1. Project Documentation
- Related sections in README.md
- Specifications under docs/
- Related entries in CHANGELOG.md
# 2. Issue Tracker
- GitHub Issues (labels: architecture, decision)
- Related discussion threads
- History leading to the decision
# 3. Pull Requests
- Related implementation PRs
- Review comments
- Performance measurement results
# 4. External Resources
- Official documentation
- Benchmark results
- Community evaluations
Output Format:
## References (auto-collected)
### Within Project
- [README.md#Tech Stack](../README.md#tech-stack)
- [Spec: State Management Requirements](../docs/requirements/state-management.md)
### Issues & PRs
- [Issue #145: State Management Library Selection](https://github.com/org/repo/issues/145)
- [PR #167: Zustand POC Implementation](https://github.com/org/repo/pull/167)
### External Resources
- [Zustand Official Documentation](https://github.com/pmndrs/zustand)
- [State of JS 2024: State Management](https://stateofjs.com/...)
- [Benchmark Results](https://npmtrends.com/zustand-vs-redux)
Implementation:
#!/bin/bash
# scripts/collect-references.sh
KEYWORD="$1" # e.g., "zustand" "state management"
# GitHub Issues search (using gh CLI)
echo "### Issues & PRs"
gh issue list --search "$KEYWORD" --state all --limit 5 \
--json number,title,url \
--jq '.[] | "- [Issue #\(.number): \(.title)](\(.url))"'
# Project-wide grep
echo "### Within Project"
rg -l "$KEYWORD" docs/ README.md 2>/dev/null | while read file; do
echo "- [$file]($file)"
done
Purpose: Quality assurance after ADR completion
Script: scripts/validate-adr.sh
Verification Items:
# references/impact-analysis.md
## Impact Analysis Checklist
### Codebase
- [ ] Identify number of affected files (estimate: ___ files)
- [ ] List of modules requiring changes
- [ ] Presence of breaking changes
- [ ] Need for compatibility layer
### Dependencies
- [ ] Need to update package.json
- [ ] Confirm conflicts with dependent libraries
- [ ] Confirm version constraints
### Team
- [ ] Number of affected team members
- [ ] Learning cost estimate (___ hours/person)
- [ ] Documentation update tasks
# references/test-coverage.md
## Test Update Checklist
- [ ] Identify scope of existing test updates
- [ ] New tests needed (estimate: ___ tests)
- [ ] Impact on E2E tests
- [ ] Need for performance tests
- [ ] Regression test plan
# references/rollback-plan.md
## Rollback Plan Checklist
### Preparation
- [ ] Create rollback procedure document
- [ ] Identify backup targets
- [ ] Define rollback triggers
### Verification
- [ ] Estimate rollback time (___ minutes)
- [ ] Data integrity assurance method
- [ ] Possibility of partial/gradual rollback
Validation Script Execution Example:
# scripts/validate-adr.sh 0023-adopt-zustand.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ADR Validation Report: 0023-adopt-zustand.md
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Required sections: Complete
✅ MADR format: Compliant
⚠️ Warning: Confirmation section is empty
⚠️ Warning: Only 2 references (recommended: 3+)
📊 Checklist Progress:
Impact analysis: 3/5 complete
Test updates: 0/5 not started ← Action needed
Rollback plan: 2/3 complete
Recommendation: Complete the test update checklist
Purpose: Visualize relationships between ADRs and improve discoverability
Script: scripts/update-index.sh
Actions:
# docs/adr/README.md auto-update
## Architecture Decision Records
| Number | Title | Status | Date |
|--------|-------|--------|------|
| [0023](0023-adopt-zustand.md) | Adopt Zustand for State Management | proposed | 2025-10-21 |
| [0022](0022-migration-turborepo.md) | Migrate to Turborepo | accepted | 2025-10-15 |
| [0021](0021-typescript-strict.md) | Enable TypeScript Strict Mode | accepted | 2025-10-10 |
### By Status
- **Proposed**: 0023
- **Accepted**: 0015, 0016, 0021, 0022
- **Deprecated**: 0008
- **Superseded**: 0003 → 0021
# Auto-added within ADR-0023
## Related ADRs
### Depends On
- [ADR-0015: Adopt React for UI](0015-adopt-react-for-ui.md) - Prerequisite for state management
### Related
- [ADR-0021: TypeScript Strict Mode](0021-typescript-strict.md) - Type safety enhancement
### May Supersede
- [ADR-0008: Use Redux for State](0008-use-redux-for-state.md) - Future replacement candidate
Link Generation Algorithm:
# Keyword-based relevance detection
KEYWORDS=$(extract_keywords "$ADR_FILE") # "zustand", "state", "react"
# Calculate relevance score from existing ADRs
for existing_adr in docs/adr/*.md; do
score=$(calculate_relevance "$KEYWORDS" "$existing_adr")
if [ $score -gt 3 ]; then
echo "Related: $existing_adr (score: $score)"
fi
done
Purpose: Automatic recovery on errors and clear guidance
Error Patterns and Handling:
❌ Error: Cannot create docs/adr/0023-adopt-zustand.md
Reason: Relative path resolution failed
🔧 Auto-fix attempt:
1. Convert relative path → absolute path
Before: docs/adr/
After: /Users/user/project/docs/adr/
2. Attempt directory creation
mkdir -p /Users/user/project/docs/adr/
3. Retrying...
❌ Error: Selected template not found
Template: technology-selection.md
Path: .claude/skills/creating-adrs/assets/
🔧 Fallback:
1. Use default template
2. Suggest custom template
- Extract structure from similar ADR
- Start with MADR minimal structure
Selection > 1 (default)
✅ Continuing with default template
⚠️ Warning: GitHub Issues collection failed
Reason: gh CLI not authenticated
🔧 Alternatives:
1. Search local files only (can continue)
2. Enter references manually
3. Add later (edit after ADR creation)
Selection > 1
✅ Continuing with local references only
Within project: 3 items found
External links: Manual input required
# /adr command automatically uses this skill
/adr "Adopt Zustand for State Management"
1. Pre-Check execution (automatic)
↓
2. Template selection (interactive)
↓
3. Reference collection (automatic + manual supplement)
↓
4. Information input (interactive)
↓
5. ADR generation
↓
6. Validation execution (automatic)
↓
7. Checklist presentation (confirmation)
↓
8. Index update (automatic)
↓
9. Complete
---
# Existing settings
name: creating-adrs
description: Create high-quality Architecture Decision Records through a structured process
# Additional settings
config:
strict_mode: true # All checklists required
auto_collect_references: true # Automatic reference collection
template_fallback: minimal # Behavior on template failure
index_auto_update: true # Automatic index update
duplicate_threshold: 0.7 # Similarity threshold for duplicate detection (0-1)
---
# Grant execution permissions
chmod +x .claude/skills/creating-adrs/scripts/*.sh
# Check gh CLI authentication
gh auth status
# If not authenticated
gh auth login
# Place project-specific templates
.claude/skills/creating-adrs/assets/custom-template.md
# Will appear in selection options during ADR creation
For verifying skills integration status:
| Item | Before | After | Improvement |
|---|---|---|---|
| ADR creation time | 15 min | 8 min | 47% reduction |
| Duplicate ADR rate | 5% | 0% | 100% eliminated |
| Missing required sections | 20% | 0% | 100% eliminated |
| Average reference count | 1.5 | 3.2 | 113% increase |
| README.md update forgotten | 30% | 0% | 100% eliminated |