| name | adr |
| description | Document significant architectural decisions using the ADR (Architecture Decision Record) format. Use during research phases when choosing between approaches, when introducing new dependencies or patterns, or when the user asks to document a technical decision. |
Architecture Decision Record (ADR) Skill
Purpose
Document significant architectural decisions so institutional knowledge persists across conversations and team members. ADRs capture the why, not just the what.
When to Invoke
- During Research phase when a significant architecture decision is identified
- When user explicitly asks to document a decision
- When choosing between 2+ viable approaches
- When introducing a new dependency or pattern
- When changing existing architecture
ADR Storage
ADRs are stored in docs/decisions/ as numbered files:
docs/decisions/
├── 0001-use-postgresql-for-storage.md
├── 0002-adopt-feature-based-structure.md
├── 0003-use-testcontainers-for-integration.md
└── NNNN-short-title.md
ADR Template
Create the ADR file at docs/decisions/NNNN-short-title.md:
# NNNN. Short Title
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by NNNN
## Context
What is the issue that we're seeing that is motivating this decision?
Include technical constraints, business requirements, and relevant context.
## Options Considered
### Option A: {name}
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High
### Option B: {name}
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High
### Option C: {name} (if applicable)
- **Pros:** ...
- **Cons:** ...
- **Effort:** Low/Medium/High
## Decision
We chose **Option X** because...
## Consequences
### Positive
- What becomes easier or possible as a result
### Negative
- What becomes harder as a result
- Technical debt introduced (if any)
### Risks
- What could go wrong with this decision
- Mitigation strategies
## Related
- Links to relevant rules, previous ADRs, or external resources
Process Guidelines
- Number sequentially — check existing ADRs in
docs/decisions/ for the next number
- Keep titles short — descriptive enough to identify the decision at a glance
- Status lifecycle:
Proposed → Accepted (after approval) → optionally Deprecated or Superseded
- Never delete ADRs — if a decision is reversed, mark as
Superseded by NNNN and create a new ADR
- Use Sequential Thinking skill if the trade-off analysis is complex
Rule Compliance
ADRs should reference applicable rules:
- Architectural Patterns @.claude/rules/architectural-pattern.md
- Core Design Principles @.claude/rules/core-design-principles.md
- Project Structure @.claude/rules/project-structure.md