architecture-decision-records

1# Architecture Decision Records
2 
3Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
4 
5## Use this skill when
6 
7- Making significant architectural decisions
8- Documenting technology choices
9- Recording design trade-offs
10- Onboarding new team members
11- Reviewing historical decisions
12- Establishing decision-making processes
13 
14## Do not use this skill when
15 
16- You only need to document small implementation details
17- The change is a minor patch or routine maintenance
18- There is no architectural decision to capture
19 
20## Instructions
21 
221. Capture the decision context, constraints, and drivers.
232. Document considered options with tradeoffs.
243. Record the decision, rationale, and consequences.
254. Link related ADRs and update status over time.
26 
27## Core Concepts
28 
29### 1. What is an ADR?
30 
31An Architecture Decision Record captures:
32- **Context**: Why we needed to make a decision
33- **Decision**: What we decided
34- **Consequences**: What happens as a result
35 
36### 2. When to Write an ADR
37 
38| Write ADR | Skip ADR |
39|-----------|----------|
40| New framework adoption | Minor version upgrades |
41| Database technology choice | Bug fixes |
42| API design patterns | Implementation details |
43| Security architecture | Routine maintenance |
44| Integration patterns | Configuration changes |
45 
46### 3. ADR Lifecycle
47 
48```
49Proposed → Accepted → Deprecated → Superseded
50              ↓
51…