architecture-adr
When making significant architectural decisions that need to be documented. Used by ARCHITECT-AGENT.
When & Why to Use This Skill
This Claude skill facilitates the creation and management of Architecture Decision Records (ADRs). It helps software architects and development teams document significant technical choices, evaluate alternatives, and track the long-term consequences of architectural changes to ensure transparency, maintainability, and clear communication across the engineering organization.
Use Cases
- Technology Stack Selection: Documenting the rationale and trade-offs when choosing specific frameworks, databases, or cloud infrastructure providers.
- Architectural Pattern Shifts: Recording the decision-making process when migrating between patterns, such as moving from a monolith to microservices.
- Integration Strategy: Evaluating and deciding between different communication methods like synchronous REST APIs versus asynchronous message queues.
- Security and API Governance: Tracking significant modifications to security models or documenting breaking changes in public-facing APIs to maintain a historical 'why' record.
- Structured Peer Reviews: Using the ADR template and evaluation matrix to facilitate objective architectural reviews and team alignment on complex technical problems.
| name | architecture-adr |
|---|---|
| description | When making significant architectural decisions that need to be documented. Used by ARCHITECT-AGENT. |
| version | 1.0.0 |
| tokens | ~400 |
| confidence | high |
| - https | //cognitect.com/blog/2011/11/15/documenting-architecture-decisions |
| last_validated | 2025-01-10 |
| next_review | 2025-01-24 |
| tags | [architecture, adr, decisions, documentation] |
When to Use
When making significant architectural decisions that need to be documented. Used by ARCHITECT-AGENT.
Patterns
ADR Structure
# ADR-001: {Decision Title}
## Status
Proposed | Accepted | Deprecated | Superseded by ADR-XXX
## Context
{What situation requires a decision?}
## Decision Drivers
- {Driver 1}
- {Driver 2}
## Considered Options
1. **Option A** - {brief description}
2. **Option B** - {brief description}
3. **Option C** - {brief description}
## Decision
We will use **Option B** because {reasoning}.
## Consequences
### Positive
- {benefit 1}
### Negative
- {tradeoff 1}
Option Evaluation
| Criteria | Option A | Option B | Option C |
|----------|----------|----------|----------|
| Effort | High | Medium | Low |
| Risk | Low | Medium | High |
| Scalability | Good | Good | Poor |
| Team expertise | Low | High | Medium |
When to Write ADR
- Technology choice (framework, database, cloud)
- Architecture pattern (monolith vs microservices)
- Integration approach (sync vs async)
- Security model changes
- Breaking changes to APIs
Anti-Patterns
- Decisions without documented alternatives
- Missing "why not" for rejected options
- No consequences section
- ADR written after implementation
- Superseded ADRs not linked
Verification Checklist
- Context explains the problem
- At least 2 options considered
- Decision clearly stated with reasoning
- Both positive and negative consequences
- Status is current
- Related ADRs linked