Architecture Decision
Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.
When to Use This Skill
Use this skill when:
- Making technology choices
- Evaluating architectural patterns
- Creating Architecture Decision Records
- Assessing technical debt
- Comparing design alternatives
Do NOT use this skill when:
- Writing implementation code
- Working on requirements (use requirements-analysis)
- Doing full system design (use system-design)
Core Principle
Context drives decisions. No pattern is universally good or bad. The best architecture is not the most elegant—it's the one that best serves its purpose while remaining maintainable and evolvable.
The Trade-off Triangle
Every architectural decision involves trade-offs:
| Vertex |
Maximized By |
Cost |
| Simplicity |
Monolith, sync communication, single DB |
Scalability limits |
| Flexibility |
Microservices, event-driven, plugins |
Complexity overhead |
| Performance |
Caching, denormalization, optimized code |
Maintainability |
Balance Strategies:
- Start simple, add complexity as needed
- Measure before optimizing
- Use abstractions to defer decisions
- Evolve incrementally
Quality Attributes
Performance
- Metrics: Response time (p50, p95, p99), throughput, resource utilization
- Tactics: Caching, load balancing, async processing
Scalability
- Dimensions: Horizontal, vertical, elastic
- Patterns: Stateless services, sharding, event streaming
Reliability
- Metrics: Uptime, MTBF, MTTR
- Patterns: Circuit breakers, retries, redundancy
Maintainability
- Factors: Readability, modularity, testability
- Patterns: Clean architecture, DDD, SOLID
Context-Pattern Mapping
Team Context
| Context |
Preferred Patterns |
Avoid |
| Small team |
Monolith, vertical slices, shared DB |
Microservices, complex abstractions |
| Multiple teams |
Service boundaries, API contracts |
Shared state, tight coupling |
Scale Context
| Context |
Preferred Patterns |
Reasoning |
| Startup |
Monolith first, vertical scaling |
Optimize for development speed |
| Enterprise |
Service mesh, horizontal scaling |
Optimize for operational scale |
Decision Matrix Template
| Option |
Consistency |
Flexibility |
Scalability |
Complexity |
Cost |
Total |
| Option A |
5 |
2 |
3 |
2 |
3 |
15 |
| Option B |
3 |
5 |
4 |
3 |
3 |
18 |
| Option C |
2 |
3 |
5 |
1 |
2 |
13 |
Weight factors based on context priorities.
Architecture Decision Record (ADR) Template
# ADR-[NUMBER]: [TITLE]
## Status
[Proposed | Accepted | Deprecated | Superseded]
## Context
[What is the situation requiring a decision?]
### Requirements
- [Requirement 1]
- [Requirement 2]
### Constraints
- [Constraint 1]
- [Constraint 2]
## Decision
[What is the decision?]
### Justification
- [Reason 1]
- [Reason 2]
## Consequences
### Positive
- [Benefit 1]
- [Benefit 2]
### Negative
- [Drawback 1]
- [Drawback 2]
## Alternatives Considered
### [Alternative 1]
Reason rejected: [Why]
### [Alternative 2]
Reason rejected: [Why]
Architectural Refactoring Patterns
Branch by Abstraction
- Create abstraction over current implementation
- Implement new solution behind abstraction
- Switch to new implementation
- Remove old implementation
Strangler Fig
- Identify boundary
- Implement new solution for new features
- Gradually migrate old features
- Retire old system
Parallel Run
- Implement new solution
- Run both old and new
- Compare results
- Switch when confident
Technical Debt Management
Debt Categories
| Type |
Examples |
Payment Strategy |
| Design |
Missing abstractions, tight coupling |
Refactoring sprints |
| Code |
Duplication, complexity, poor naming |
Continuous cleanup |
| Test |
Missing tests, flaky tests |
Test improvement |
| Documentation |
Missing docs, outdated diagrams |
Documentation sprints |
Metrics
- Debt ratio: Debt work / Total work (target < 20%)
- Interest rate: Extra effort due to debt
- Debt ceiling: Maximum acceptable debt
Anti-Patterns
Big Ball of Mud
Symptoms: No clear structure, everything depends on everything
Remedy: Identify boundaries, extract modules, establish interfaces
Distributed Monolith
Symptoms: Services must deploy together, sync chains, shared DBs
Remedy: Merge related services, async communication, separate DBs
Golden Hammer
Symptoms: One solution for all problems, force-fitting patterns
Remedy: Learn alternatives, evaluate objectively, prototype options
Related Skills
- system-design - Full system design with ADRs
- code-review - Implementation validation
- task-decomposition - Breaking down architectural work
- requirements-analysis - Understanding constraints
1---2name: architecture-decision3description: Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns. This skill should be used when the user asks about 'architecture decision', 'ADR', 'design pattern selection', 'technology choice', or needs to evaluate architectural trade-offs. Keywords: architecture, ADR, patterns, trade-offs, technical debt, quality attributes, decision record.4license: MIT5---6
7# Architecture Decision
8
9Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.
10
11## When to Use This Skill
12
13Use this skill when:
14- Making technology choices
15- Evaluating architectural patterns
16- Creating Architecture Decision Records
17- Assessing technical debt
18- Comparing design alternatives
19
20Do NOT use this skill when:
21- Writing implementation code
22- Working on requirements (use requirements-analysis)
23- Doing full system design (use system-design)
24
25## Core Principle
26
27**Context drives decisions.** No pattern is universally good or bad. The best architecture is not the most elegant—it's the one that best serves its purpose while remaining maintainable and evolvable.
28
29## The Trade-off Triangle
30
31Every architectural decision involves trade-offs:
32
33| Vertex | Maximized By | Cost |
34|--------|--------------|------|
35| **Simplicity** | Monolith, sync communication, single DB | Scalability limits |
36| **Flexibility** | Microservices, event-driven, plugins | Complexity overhead |
37| **Performance** | Caching, denormalization, optimized code | Maintainability |
38
39**Balance Strategies:**
40- Start simple, add complexity as needed
41- Measure before optimizing
42- Use abstractions to defer decisions
43- Evolve incrementally
44
45## Quality Attributes
46
47### Performance
48- Metrics: Response time (p50, p95, p99), throughput, resource utilization
49- Tactics: Caching, load balancing, async processing
50
51### Scalability
52- Dimensions: Horizontal, vertical, elastic
53- Patterns: Stateless services, sharding, event streaming
54
55### Reliability
56- Metrics: Uptime, MTBF, MTTR
57- Patterns: Circuit breakers, retries, redundancy
58
59### Maintainability
60- Factors: Readability, modularity, testability
61- Patterns: Clean architecture, DDD, SOLID
62
63## Context-Pattern Mapping
64
65### Team Context
66
67| Context | Preferred Patterns | Avoid |
68|---------|-------------------|-------|
69| **Small team** | Monolith, vertical slices, shared DB | Microservices, complex abstractions |
70| **Multiple teams** | Service boundaries, API contracts | Shared state, tight coupling |
71
72### Scale Context
73
74| Context | Preferred Patterns | Reasoning |
75|---------|-------------------|-----------|
76| **Startup** | Monolith first, vertical scaling | Optimize for development speed |
77| **Enterprise** | Service mesh, horizontal scaling | Optimize for operational scale |
78
79## Decision Matrix Template
80
81| Option | Consistency | Flexibility | Scalability | Complexity | Cost | Total |
82|--------|-------------|-------------|-------------|------------|------|-------|
83| Option A | 5 | 2 | 3 | 2 | 3 | 15 |
84| Option B | 3 | 5 | 4 | 3 | 3 | 18 |
85| Option C | 2 | 3 | 5 | 1 | 2 | 13 |
86
87Weight factors based on context priorities.
88
89## Architecture Decision Record (ADR) Template
90
91```markdown
92# ADR-[NUMBER]: [TITLE]
93
94## Status
95[Proposed | Accepted | Deprecated | Superseded]
96
97## Context
98[What is the situation requiring a decision?]
99
100### Requirements
101- [Requirement 1]
102- [Requirement 2]
103
104### Constraints
105- [Constraint 1]
106- [Constraint 2]
107
108## Decision
109[What is the decision?]
110
111### Justification
112- [Reason 1]
113- [Reason 2]
114
115## Consequences
116
117### Positive
118- [Benefit 1]
119- [Benefit 2]
120
121### Negative
122- [Drawback 1]
123- [Drawback 2]
124
125## Alternatives Considered
126
127### [Alternative 1]
128Reason rejected: [Why]
129
130### [Alternative 2]
131Reason rejected: [Why]
132```
133
134## Architectural Refactoring Patterns
135
136### Branch by Abstraction
1371. Create abstraction over current implementation
1382. Implement new solution behind abstraction
1393. Switch to new implementation
1404. Remove old implementation
141
142### Strangler Fig
1431. Identify boundary
1442. Implement new solution for new features
1453. Gradually migrate old features
1464. Retire old system
147
148### Parallel Run
1491. Implement new solution
1502. Run both old and new
1513. Compare results
1524. Switch when confident
153
154## Technical Debt Management
155
156### Debt Categories
157
158| Type | Examples | Payment Strategy |
159|------|----------|------------------|
160| **Design** | Missing abstractions, tight coupling | Refactoring sprints |
161| **Code** | Duplication, complexity, poor naming | Continuous cleanup |
162| **Test** | Missing tests, flaky tests | Test improvement |
163| **Documentation** | Missing docs, outdated diagrams | Documentation sprints |
164
165### Metrics
166- **Debt ratio:** Debt work / Total work (target < 20%)
167- **Interest rate:** Extra effort due to debt
168- **Debt ceiling:** Maximum acceptable debt
169
170## Anti-Patterns
171
172### Big Ball of Mud
173**Symptoms:** No clear structure, everything depends on everything
174**Remedy:** Identify boundaries, extract modules, establish interfaces
175
176### Distributed Monolith
177**Symptoms:** Services must deploy together, sync chains, shared DBs
178**Remedy:** Merge related services, async communication, separate DBs
179
180### Golden Hammer
181**Symptoms:** One solution for all problems, force-fitting patterns
182**Remedy:** Learn alternatives, evaluate objectively, prototype options
183
184## Related Skills
185
186- **system-design** - Full system design with ADRs
187- **code-review** - Implementation validation
188- **task-decomposition** - Breaking down architectural work
189- **requirements-analysis** - Understanding constraints
majiayu000