Agent skill
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.
Install this agent skill to your Project
npx add-skill https://github.com/jwynia/agent-skills/tree/main/skills/tech/development/architecture/architecture-decision
Metadata
Additional technical details for this skill
- mode
- diagnostic+evaluative
- type
- diagnostic
- author
- jwynia
- domain
- agile-software
- version
- 1.0
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
jwynia/agent-skills
document-to-narration
Convert written documents to narrated video scripts with TTS audio and word-level timing. Use when preparing essays, blog posts, or articles for video narration. Outputs scene files, audio, and VTT with precise word timestamps. Keywords: narration, voiceover, TTS, scenes, audio, timing, video script, spoken.
jwynia/agent-skills
shadcn-layouts
Generate correct shadcn/Tailwind layouts by applying CSS mental models. This skill should be used when the user asks to 'create a shadcn layout', 'fix layout issues', 'debug CSS height problems', 'make scrolling work', or has issues with Tailwind flex/grid. Keywords: shadcn, Tailwind, layout, CSS, flex, grid, height, scroll, overflow.
jwynia/agent-skills
frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Provides analysis tools for auditing existing designs and generation tools for creating color palettes, typography systems, design tokens, and component templates. Supports React, Vue, Svelte, and vanilla HTML/CSS. Use when building web components, pages, or applications. Keywords: design, UI, frontend, CSS, components, palette, typography, tokens, accessibility.
jwynia/agent-skills
react-pwa
jwynia/agent-skills
pwa-development
Implement Progressive Web App features for React and Svelte projects. This skill should be used when the user asks to 'make a PWA', 'add offline support', 'create a service worker', 'fix caching issues', or wants installable web apps. Keywords: PWA, service worker, offline, manifest, caching, installable, Workbox, vite-pwa.
jwynia/agent-skills
mastra-hono
Develop AI agents, tools, and workflows with Mastra v1 Beta and Hono servers. This skill should be used when creating Mastra agents, defining tools with Zod schemas, building workflows with step data flow, setting up Hono API servers with Mastra adapters, or implementing agent networks. Keywords: mastra, hono, agent, tool, workflow, AI, LLM, typescript, API, MCP.
Didn't find tool you were looking for?