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-decision-23description: Evaluate architecture options, document trade-offs, and write decision records. Use for ADRs, pattern selection, technology choices, or technical-debt decisions.4license: MIT5---67# Architecture Decision89Systematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.1011## When to Use This Skill1213Use this skill when:14- Making technology choices15- Evaluating architectural patterns16- Creating Architecture Decision Records17- Assessing technical debt18- Comparing design alternatives1920Do NOT use this skill when:21- Writing implementation code22- Working on requirements (use requirements-analysis)23- Doing full system design (use system-design)2425## Core Principle2627**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.2829## The Trade-off Triangle3031Every architectural decision involves trade-offs:3233| 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 |3839**Balance Strategies:**40- Start simple, add complexity as needed41- Measure before optimizing42- Use abstractions to defer decisions43- Evolve incrementally4445## Quality Attributes4647### Performance48- Metrics: Response time (p50, p95, p99), throughput, resource utilization49- Tactics: Caching, load balancing, async processing5051### Scalability52- Dimensions: Horizontal, vertical, elastic53- Patterns: Stateless services, sharding, event streaming5455### Reliability56- Metrics: Uptime, MTBF, MTTR57- Patterns: Circuit breakers, retries, redundancy5859### Maintainability60- Factors: Readability, modularity, testability61- Patterns: Clean architecture, DDD, SOLID6263## Context-Pattern Mapping6465### Team Context6667| 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 |7172### Scale Context7374| 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 |7879## Decision Matrix Template8081| 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 |8687Weight factors based on context priorities.8889## Architecture Decision Record (ADR) Template9091```markdown92# ADR-[NUMBER]: [TITLE]9394## Status95[Proposed | Accepted | Deprecated | Superseded]9697## Context98[What is the situation requiring a decision?]99100### Requirements101- [Requirement 1]102- [Requirement 2]103104### Constraints105- [Constraint 1]106- [Constraint 2]107108## Decision109[What is the decision?]110111### Justification112- [Reason 1]113- [Reason 2]114115## Consequences116117### Positive118- [Benefit 1]119- [Benefit 2]120121### Negative122- [Drawback 1]123- [Drawback 2]124125## Alternatives Considered126127### [Alternative 1]128Reason rejected: [Why]129130### [Alternative 2]131Reason rejected: [Why]132```133134## Architectural Refactoring Patterns135136### Branch by Abstraction1371. Create abstraction over current implementation1382. Implement new solution behind abstraction1393. Switch to new implementation1404. Remove old implementation141142### Strangler Fig1431. Identify boundary1442. Implement new solution for new features1453. Gradually migrate old features1464. Retire old system147148### Parallel Run1491. Implement new solution1502. Run both old and new1513. Compare results1524. Switch when confident153154## Technical Debt Management155156### Debt Categories157158| 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 |164165### Metrics166- **Debt ratio:** Debt work / Total work (target < 20%)167- **Interest rate:** Extra effort due to debt168- **Debt ceiling:** Maximum acceptable debt169170## Anti-Patterns171172### Big Ball of Mud173**Symptoms:** No clear structure, everything depends on everything174**Remedy:** Identify boundaries, extract modules, establish interfaces175176### Distributed Monolith177**Symptoms:** Services must deploy together, sync chains, shared DBs178**Remedy:** Merge related services, async communication, separate DBs179180### Golden Hammer181**Symptoms:** One solution for all problems, force-fitting patterns182**Remedy:** Learn alternatives, evaluate objectively, prototype options183184## Related Skills185186- **system-design** - Full system design with ADRs187- **code-review** - Implementation validation188- **task-decomposition** - Breaking down architectural work189- **requirements-analysis** - Understanding constraints
aAAaqwq