| name | systems-design |
| description | 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.1"} |
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.
Evolutionary
Design for change with clear upgrade paths.
Practices:
- Version all APIs with deprecation policies
- Feature flags for gradual rollouts
- Design with migration paths in mind
- Deployment independent from release
- Automated compatibility testing
<technology_selection_summary>
Load technology-selection.md for detailed guidance.
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.
</technology_selection_summary>
<design_patterns_summary>
Load design-patterns.md for detailed guidance.
Service Decomposition
Monolith first. Extract when hitting specific pain:
- Different scaling needs
- Different deployment cadences
- Team boundaries
- Technology constraints
Microservices: yes for 10+ engineers, clear domains, independent scaling. No for small teams, unclear domains.
Communication
| Pattern | Use when | Tradeoffs |
|---|
| Sync (REST, gRPC) | Immediate response needed | Tight coupling, cascading failures |
| Async (queues, streams) | Eventual consistency OK | Complexity, ordering challenges |
| Event-driven | Decoupling, audit trail | Event versioning, consistency |
Data Management
- Database per service: each service owns its data
- CQRS: separate read/write when patterns differ
- Event sourcing: when audit trail critical
</design_patterns_summary>
<scalability_summary>
Load scalability.md for detailed guidance.
Key Metrics: Latency (p50/p95/p99), throughput (RPS), utilization (CPU/mem/net/disk), error rates, saturation (queues, pools).
Capacity Planning: Baseline → load test → find limits → model growth → plan 30-50% headroom.
Bottleneck Solutions:
| Resource | Solutions |
|---|
| Database | Indexing, read replicas, caching, sharding |
| CPU | Horizontal scale, algorithm optimization, async |
| Memory | Profiling, streaming, data structure optimization |
| Network | Compression, CDN, HTTP/2, gRPC |
| I/O | SSD, batching, async I/O, caching |
Scaling Strategies: Vertical (simple, limited), horizontal (stateless required), caching layers (L1/L2/L3), database scaling (replicas, sharding, pooling).
</scalability_summary>
<rust_summary>
Load rust-architecture.md for detailed guidance.
Choose Rust when: Performance-critical, resource-constrained, memory safety critical, concurrent processing.
Skip Rust when: Prototype/MVP, small team without experience, standard CRUD, missing ecosystem libs.
Stack: tokio (runtime), axum/actix-web (framework), sqlx/diesel (database), serde (serialization), tracing (observability), thiserror/anyhow (errors).
vs TypeScript: Rust is 2-10x faster, 5-10x lower memory, compile-time bug detection, no GC. TS has faster iteration, massive ecosystem, easier hiring.
</rust_summary>
<common_patterns_summary>
Load common-patterns.md for detailed guidance.
| Pattern | Purpose |
|---|
| API Gateway | Single entry, routing, auth, rate limiting |
| BFF | Per-client backends with optimized data shapes |
| Circuit Breaker | Fail fast when downstream unhealthy |
| Saga | Distributed transactions across services |
| Strangler Fig | Gradual legacy migration via proxy |
</common_patterns_summary>
<implementation_summary>
Load implementation-guidance.md for detailed guidance.
Phased Delivery:
- MVP (2-4 wks): Core workflow, simplest architecture, validate problem-solution fit
- Beta (4-8 wks): Key features, monitoring, automated deploy, validate product-market fit
- Production (8-12 wks): Full features, reliability, auto-scaling, DR
- Optimization (ongoing): Performance tuning, cost optimization
Critical Path: Identify blocking dependencies, parallel workstreams, resource constraints, risk areas, decision points.
Observability: Metrics (RED), logging (structured + correlation IDs), tracing (OpenTelemetry), alerting (SLO-based + runbooks).
</implementation_summary>
<adr_summary>
Load adr-template.md for the full template.
ADR structure:
- Status, Date, Deciders, Context
- Decision
- Alternatives Considered (with pros/cons/why not)
- Consequences (positive, negative, neutral)
- Implementation Notes
- Success Metrics
- Review Date
</adr_summary>
<questions_summary>
Load questions-checklist.md for the full checklist.
Requirements: Core workflows, data storage, integrations, critical vs nice-to-have.
Non-functional: Users (now + 1-2 yrs), latency targets, availability (99.9%? 99.99%?), consistency, compliance.
Constraints: Existing systems, current tech, team expertise, deployment env, budget, timeline, acceptable debt.
Technology Selection: Why this over alternatives? Production experience? Operational complexity? Lock-in risk? Hiring?
Risk: Blast radius? Rollback strategy? Detection? Contingency? Assumptions? Cost of being wrong?
</questions_summary>
Use EnterPlanMode when presenting options — enables keyboard navigation.
Structure:
- Prose above tool: context, reasoning, recommendation
- Inside tool: 2-3 options with tradeoffs + "Something else"
- User selects: number, modifications, or combo
After user choice:
- Restate decision
- List implications
- Surface concerns if any
- Ask clarifying questions if gaps remain
Before documenting:
- Verify all options considered
- Confirm rationale is clear
- Check success metrics defined
- Validate migration path if applicable
At Documentation stage:
- Create ADR if architectural decision
- Skip if simple tech choice
- Mark stage complete after delivery
ALWAYS:
- Create Discovery todo at session start
- Update todos at stage transitions
- Ask clarifying questions about requirements and constraints before proposing
- Present 2-3 viable options with clear tradeoffs
- Document decisions with rationale (ADR when appropriate)
- Consider immediate needs and future scale
- Evaluate team expertise and operational capacity
- Account for budget and timeline constraints
NEVER:
- Recommend bleeding-edge tech without strong justification
- Over-engineer solutions for current scale
- Skip constraint analysis (budget, timeline, team, existing systems)
- Propose architectures the team can't operate
- Ignore operational complexity in technology selection
- Proceed without understanding non-functional requirements
- Skip stage transitions when moving through workflow
Core:
Deep Dives:
- technology-selection.md — database, framework, infrastructure selection
- design-patterns.md — service decomposition, communication, data management
- scalability.md — performance modeling, bottlenecks, scaling strategies
- rust-architecture.md — when to use Rust, stack recommendations
- common-patterns.md — API Gateway, BFF, Circuit Breaker, Saga, Strangler
- implementation-guidance.md — phased delivery, observability
- adr-template.md — Architecture Decision Record template
- questions-checklist.md — requirements and risk questions
