Architecture Decision
- 449 installs
- 133 repo stars
- Updated February 24, 2026
- jwynia/agent-skills
architecture-decision is a diagnostic agent skill that evaluates architecture options and documents ADRs for developers who need recorded trade-offs, patterns, and outcomes across refactors and onboarding.
About
architecture-decision is version 1.0 agent skill by jwynia that systematically evaluates architecture decisions, documents trade-offs, and selects appropriate patterns as Architecture Decision Records. The skill runs in diagnostic and evaluative mode when developers ask about ADRs, design pattern selection, technology choices, quality attributes, or technical debt implications. It integrates with system-design for ADR templates and works across any project stack. Reach for it before committing to structural changes—database selection, messaging patterns, auth models—so teams and agents retain context, rejected options, and rationale when code evolves or new contributors onboard.
- Architecture Decision Record templates
- Context, options, and tradeoff capture
- Decision status and supersession tracking
- Onboarding-friendly technical rationale
- Agent-readable project decision history
Architecture Decision by the numbers
- 449 all-time installs (skills.sh)
- +3 installs in the week ending Aug 2, 2026 (Skillselion tracking)
- Ranked #397 of 1,879 Documentation skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/jwynia/agent-skills --skill architecture-decisionAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 449 |
|---|---|
| repo stars | ★ 133 |
| Last updated | February 24, 2026 |
| Repository | jwynia/agent-skills ↗ |
How do you document architecture decisions as ADRs?
Capture architecture decisions as ADRs—context, options, tradeoffs, and outcomes—so teams and agents preserve rationale across refactors and onboarding.
Who is it for?
Developers evaluating technology or pattern choices who need structured ADRs with trade-off analysis before implementation commits.
Skip if: Quick bug fixes or single-file refactors where formal architecture records and multi-option evaluation add unnecessary overhead.
When should I use this skill?
User mentions ADR, architecture decision, design pattern selection, technology choice, or architectural trade-offs.
What you get
Architecture Decision Records with context, options, trade-offs, and chosen outcomes
- Architecture Decision Records
- Trade-off analysis
- Pattern selection rationale
By the numbers
- Published as version 1.0 in skill metadata
- Operates in diagnostic and evaluative mode for architecture decisions
Files
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
1. Create abstraction over current implementation 2. Implement new solution behind abstraction 3. Switch to new implementation 4. Remove old implementation
Strangler Fig
1. Identify boundary 2. Implement new solution for new features 3. Gradually migrate old features 4. Retire old system
Parallel Run
1. Implement new solution 2. Run both old and new 3. Compare results 4. 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
Related skills
Lark MarkdownInstantly turn any markdown file into clean, formatted Lark/Figma-compatible documents without manual reformatting.488k
Lark DocCreate, read, update, summarize, rewrite and manage Feishu/Lark cloud documents directly from agent workflows.401k16.1kLark WikiCreate, organize, query, and manage documents, spaces, and members inside Lark (Feishu) knowledge bases directly from AI agent workflows.397k16.1k
Domain ModelingBuild and sharpen a project's domain model: pin down domain terminology in a glossary and record architectural decisions as ADRs.318k202k
Opensource Guide CoachGet expert, attribution-safe guidance on launching and sustaining an open-source project.270k71Readme I18nMaintain consistent, updatable language selector blocks across every README variant in a multilingual repository.270k71How it compares
Pick architecture-decision when formal ADRs and multi-option trade-off analysis are required; use lighter design notes for small, reversible changes.
FAQ
When should architecture-decision be invoked?
architecture-decision should be used when developers ask about ADRs, design pattern selection, technology choices, or architectural trade-offs. The skill evaluates options and records context, rejected alternatives, and outcomes.
What version is architecture-decision and what mode does it use?
architecture-decision is version 1.0 with diagnostic and evaluative mode under MIT license. It systematically evaluates decisions and integrates with system-design for ADR templates.