architecture-decision-recorder
Create and manage Architecture Decision Records (ADRs) for documenting important architectural decisions, tradeoffs, and rationale.
When & Why to Use This Skill
The Architecture Decision Recorder is a specialized Claude skill designed to systematically document, manage, and track Architecture Decision Records (ADRs). It enables engineering teams to capture the rationale, context, and trade-offs behind critical technical decisions, ensuring long-term architectural clarity and facilitating seamless knowledge transfer across the development lifecycle.
Use Cases
- Case 1: Documenting major technology stack selections and the rationale behind choosing specific frameworks, languages, or databases.
- Case 2: Recording complex design trade-offs and technical constraints encountered during system design to prevent future 're-deciding' of the same issues.
- Case 3: Maintaining a version-controlled historical log of architectural evolution to streamline developer onboarding and technical audits.
- Case 4: Facilitating team communication and alignment by providing a standardized, immutable template for proposing and reviewing significant structural modifications.
| name | architecture-decision-recorder |
|---|---|
| description | Create and manage Architecture Decision Records (ADRs) for documenting important architectural decisions, tradeoffs, and rationale. |
| allowed-tools | [Read, Write, Edit, Bash, Grep, Glob] |
Architecture Decision Recorder
Systematically document architectural decisions using the ADR pattern.
When to Use
- Documenting significant architectural decisions
- Recording technology choices
- Tracking design tradeoffs
- Maintaining architectural history
- Facilitating team communication
ADR Template
# ADR-NNNN: [Title]
**Date:** YYYY-MM-DD
**Status:** [Proposed | Accepted | Deprecated | Superseded]
**Decision Makers:** [Names]
## Context
What is the issue we're trying to solve? What are the forces at play?
### Business Context
- Business goal or requirement
- Constraints (time, budget, team)
- Stakeholder concerns
### Technical Context
- Current system state
- Technical constraints
- Integration requirements
## Decision
We will [decision statement].
### Rationale
Why this approach over alternatives?
## Consequences
### Positive
- Benefit 1
- Benefit 2
### Negative
- Tradeoff 1
- Tradeoff 2
### Risks
- Risk 1 → Mitigation strategy
- Risk 2 → Mitigation strategy
## Alternatives Considered
### Option 1: [Name]
**Pros:** [List]
**Cons:** [List]
**Rejected because:** [Reason]
### Option 2: [Name]
**Pros:** [List]
**Cons:** [List]
**Rejected because:** [Reason]
## Implementation
- [ ] Action item 1
- [ ] Action item 2
## References
- [Link to research]
- [Related ADR]
Best Practices
- ✅ Create ADRs for all major decisions
- ✅ Keep ADRs immutable (supersede, don't edit)
- ✅ Store in version control
- ✅ Link related ADRs
- ✅ Review quarterly
- ✅ Include quantitative data
Related Commands
/adr-create- Create new ADR