This skill should be used when designing systems, evaluating architectures, making technology decisions, or planning for scale. Provides technology selection frameworks, scalability planning, and architectural tradeoff analysis.
This skill should be used when designing systems, evaluating architectures, making technology decisions, or planning for scale. Provides technology selection frameworks, scalability planning, and architectural tradeoff analysis.
metadata
{"version":"2.1.0"}
Software Architecture
Design question → options with tradeoffs → documented decision.
<when_to_use>
Designing new systems or major features
Evaluating architectural approaches
Making technology stack decisions
Planning for scale and performance
Analyzing design tradeoffs
NOT for: trivial tech choices, premature optimization, undocumented requirements
</when_to_use>
Load the maintain-tasks skill for stage tracking. Stages advance only, never regress.
Stage
Trigger
activeForm
Discovery
Session start
"Gathering requirements"
Codebase Analysis
Requirements clear
"Analyzing codebase"
Constraint Evaluation
Codebase understood
"Evaluating constraints"
Solution Design
Constraints mapped
"Designing solutions"
Documentation
Design selected
"Documenting architecture"
Situational (insert before Documentation when triggered):
Review & Refinement → feedback cycles on complex designs
Edge cases:
Small questions: skip to Solution Design
Greenfield: skip Codebase Analysis
No ADR needed: skip Documentation
Iteration: Review & Refinement may repeat
Task format:
- Discovery { problem domain }
- Analyze { codebase area }
- Evaluate { constraint type }
- Design { solution approach }
- Document { decision type }
Workflow:
Start: Create Discovery as in_progress
Transition: Mark current completed, add next in_progress
High start: skip to Solution Design for clear problems
Optional end: Documentation skippable if ADR not needed
Proven over Novel
Favor battle-tested over bleeding-edge without strong justification.
Checklist:
3+ years production at scale?
Strong community + active maintenance?
Available experienced practitioners?
Total cost of ownership (learning, tooling, hiring)?
Red flags: "Early adopters" without time budget, "Written in X" without benchmarks, "Everyone's talking" without case studies.
Complexity Budget
Each abstraction must provide 10x value.
Questions:
What specific problem does this solve?
Can we solve with existing tools/patterns?
Maintenance burden (docs, onboarding, debugging)?
Impact on incident response?
Unix Philosophy
Small, focused modules with clear contracts, single responsibilities.
Checklist:
Single, well-defined purpose?
Describe in one sentence without "and"?
Dependencies explicit and minimal?
Testable in isolation?
Clean, stable interface?
Observability First
No system ships without metrics, tracing, alerting.
Required every service:
Metrics: RED (Rate, Errors, Duration) for all endpoints
Tracing: distributed traces with correlation IDs
Logging: structured logs with context
Alerts: SLO-based with runbooks
Dashboards: at-a-glance health
Modern by Default
Use contemporary proven patterns for greenfield, respect legacy constraints.
Patterns (2025):
TypeScript strict mode for type safety
Rust for performance-critical services
Container deployment (Docker, K8s)
Infrastructure as Code (Terraform, Pulumi)
Distributed tracing (OpenTelemetry)
Event-driven architectures
Legacy respect: document why legacy exists, plan incremental migration, don't rewrite what works.
Database: Match data model to use case. PostgreSQL for ACID + complex queries. DynamoDB for flexibility + horizontal scaling. Redis for caching + pub/sub.
Framework (TS): Hono for modern/serverless, Express for proven ecosystem, Fastify for speed, NestJS for enterprise.
Framework (Rust): Axum for type-safe modern, Actix-web for raw performance.
Frontend: React + TanStack Router for complex apps, Solid for perf-critical, Next.js for SSR/SSG.
Infrastructure: Serverless for low-traffic/prototypes, K8s/ECS for multi-service at scale, PaaS for MVPs.
Selection criteria: team expertise, performance needs, ecosystem, type safety, deployment target.
