| name | designing-systems |
| description | Design scalable, reliable software systems. Use when planning new systems, major features, or architecture changes. Covers C4 diagrams, trade-off analysis, and system decomposition. |
| allowed-tools | Read, Write, Glob, Grep |
Designing Systems
Workflows
Feedback Loops
- Draft design document
- Review with stakeholders
- Create POC for risky components
- Refine design based on POC
- Finalize ADR
Blueprint Template
Every system design should include:
- High-Level Diagram: Mermaid graph showing components
- Component Boundaries: Clear responsibility definitions
- API Definitions: OpenAPI or GraphQL specs
- Data Models: Schema definitions
- Trade-off Analysis: Rationale for key decisions
C4 Model Levels
Level 1: Context
Who uses the system? What external systems does it interact with?
Level 2: Container
What are the major deployable units? (APIs, databases, queues)
Level 3: Component
What are the major building blocks within each container?
Level 4: Code
Class/function level (usually not needed in architecture docs)
Trade-off Analysis
For major decisions, explicitly document:
| Decision | Option A | Option B |
|---|
| Pros | ... | ... |
| Cons | ... | ... |
| When to Choose | ... | ... |
Non-Functional Requirements
Always consider:
- Scalability: Expected load, growth rate
- Availability: SLA targets, failure modes
- Latency: P50, P95, P99 requirements
- Security: Authentication, authorization, data protection
- Cost: Infrastructure, operational overhead
Resources
