designing-systems
Design scalable, reliable software systems. Use when planning new systems, major features, or architecture changes. Covers C4 diagrams, trade-off analysis, and system decomposition.
When & Why to Use This Skill
This Claude skill streamlines the software architecture process by helping engineers design scalable, reliable, and well-documented systems. It facilitates the creation of C4 diagrams, data models, and API contracts while ensuring robust decision-making through structured trade-off analysis and the generation of Architecture Decision Records (ADRs).
Use Cases
- Initial System Planning: Use the skill to gather functional and non-functional requirements and create high-level C4 diagrams for new microservices or platforms.
- Feature Expansion: Evaluate the impact of adding major features to an existing system, identifying potential single points of failure and architectural risks.
- Technical Documentation: Automatically generate structured ADRs and Mermaid-based diagrams to document complex design decisions and maintain a clear project history.
- Performance & Reliability Optimization: Conduct non-functional requirement analysis to ensure the architecture meets scalability, availability, and latency SLA targets.
- Stakeholder Alignment: Create clear visual blueprints and trade-off tables to facilitate reviews and reach consensus on technical directions.
| 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
- Requirements: Gather functional and non-functional requirements
- Diagrams: Create C4 diagrams (Context, Container)
- Data: Define data model and storage strategy
- API: Define interfaces and contracts
- Risks: Identify single points of failure
- Document: Save to
./artifacts/adr_[topic].md
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