jwynia/architecture-decision
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.
npx skills add https://github.com/jwynia/agent-skills --skill architecture-decisionSystematically evaluate architecture decisions, document trade-offs, and select appropriate patterns for context. Provides frameworks for pattern selection, ADR creation, and technical debt management.
Use this skill when:
Do NOT use this skill when:
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.
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:
| Context | Preferred Patterns | Avoid |
|---------|-------------------|-------|
| Small team | Monolith, vertical slices, shared DB | Microservices, complex abstractions |
| Multiple teams | Service boundaries, API contracts | Shared state, tight coupling |
| Context | Preferred Patterns | Reasoning |
|---------|-------------------|-----------|
| Startup | Monolith first, vertical scaling | Optimize for development speed |
| Enterprise | Service mesh, horizontal scaling | Optimize for operational scale |
| 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.
# 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]
| 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 |
Symptoms: No clear structure, everything depends on everything
Remedy: Identify boundaries, extract modules, establish interfaces
Symptoms: Services must deploy together, sync chains, shared DBs
Remedy: Merge related services, async communication, separate DBs
Symptoms: One solution for all problems, force-fitting patterns
Remedy: Learn alternatives, evaluate objectively, prototype options
Take jwynia/architecture-decision from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.