doc-generate-adr
Generate Architecture Decision Records (ADRs) to document significant architectural decisions. Use when making important technical decisions that need documentation.
When & Why to Use This Skill
This Claude skill automates the generation of Architecture Decision Records (ADRs), enabling engineering teams to systematically document critical technical choices, rationale, and trade-offs. By capturing the 'why' behind architectural shifts in a standardized format, it ensures long-term project maintainability, improves team alignment, and preserves institutional knowledge.
Use Cases
- Documenting Technology Selection: Record the detailed rationale and comparison data when choosing specific frameworks, databases, or cloud providers for a project.
- Capturing Design Trade-offs: Formally document the pros, cons, and consequences of architectural patterns (e.g., Microservices vs. Monolith) to provide context for future developers.
- Standardizing Engineering Workflows: Implement a consistent ADR structure across distributed teams to ensure all major technical pivots are documented uniformly.
- Facilitating Code Reviews and Audits: Use generated ADRs as a reference point during architectural reviews to justify design decisions to stakeholders and auditors.
- Onboarding New Developers: Provide a historical log of architectural evolution, helping new team members understand the constraints and decisions that shaped the current codebase.
| name | doc-generate-adr |
|---|---|
| description | Generate Architecture Decision Records (ADRs) to document significant architectural decisions. Use when making important technical decisions that need documentation. |
| mcp_fallback | none |
| category | doc |
Generate ADR Skill
Create Architecture Decision Records for technical decisions.
When to Use
- Making significant architectural decisions
- Choosing between technical alternatives
- Documenting design trade-offs
- Recording rationale for future reference
Quick Reference
./scripts/create_adr.sh "Decision Title"
# Creates: docs/adr/ADR-XXX-decision-title.md
Workflow
- Identify decision - What choice needs documentation?
- Research alternatives - Gather evidence and performance data
- Create ADR - Run script with title
- Fill sections - Context, Decision, Rationale, Consequences, Alternatives
- Review - Get team approval
- Update status - Change from "Proposed" to "Accepted"
ADR Format
All ADRs follow this structure:
# ADR-XXX: Title
**Status**: Proposed | Accepted | Deprecated | Superseded
**Date**: YYYY-MM-DD
**Deciders**: Names/roles
## Context
What is the issue we're facing?
## Decision
What decision are we making?
## Rationale
Why this decision? Key reasons.
## Consequences
### Positive
- Benefit 1
### Negative
- Drawback 1
### Neutral
- Other impact 1
## Alternatives Considered
### Alternative 1
Why not chosen.
Status Lifecycle
- Proposed - Under consideration
- Accepted - Decision made and active
- Deprecated - No longer recommended
- Superseded - Replaced by newer ADR
Storage Location
docs/adr/
├── ADR-001-language-selection.md
├── ADR-002-testing-strategy.md
└── README.md
Error Handling
| Issue | Fix |
|---|---|
| Missing context | Add background and constraints |
| Unclear decision | Make decision more specific |
| Missing alternatives | Document at least 2 alternatives |
| No consequences | Think through positive and negative impacts |
References
- See existing ADRs in
/docs/adr/for examples - Related skill:
phase-plan-generatefor planning