system-design-hd-skill

Research-first software architecture harness — from vague requirement to production-grade design

A Claude Code skill that transforms ambiguous feature requests into professional system design documents.

Features • How It Works • Usage • Architecture • Contributing

---

Table of Contents

• Overview
• Features
• How It Works
• Installation
• Usage
• Architecture
• Documentation
• Development
• Testing
• Contributing
• License

---

Overview

system-design is a comprehensive Claude Code skill that guides engineers and architects through every stage of designing a software system. It enforces a research-first methodology: before recommending any architectural pattern, the skill searches for real-world analogues, extracts lessons, and frames all trade-offs explicitly via Architecture Decision Records (ADRs).

What It Does

/vague requirement ──────────────────────> /production-ready design document

"Design a chat app" ──► Requirements ──► Research ──► Architecture ──► Capacity Plan
                                                                       │
                                                                       ├─► DB Schema
                                                                       ├─► API Contract
                                                                       ├─► ADRs
                                                                       └─► Security Analysis

Who It's For

User	Use Case
Backend Engineer	Design a URL shortener, chat application, or payment system
Tech Lead	Review and improve HLDs with evidence-based recommendations
Architect	Design auth systems, migration strategies, or platform infrastructure
Student / Candidate	Learn system design through educational mode walkthroughs
Product Manager	Understand capacity implications of 10M DAU requirements

---

Features

🎯 Structured Requirements Elicitation

• Socratic questioning to clarify vague requirements
• Functional requirements (FRs) with imperative format
• Non-functional requirements (NFRs) with concrete numeric targets
• Constraints and scope boundary documentation
• Assumption logging with risk assessment

🔬 Research-First Analysis

• WebSearch for real-world system analogues
• Pattern extraction from engineering blogs (Netflix, Uber, Airbnb, etc.)
• Failure mode analysis from post-mortems
• Evidence quality assessment (Tier 1 papers vs. Tier 4 blogs)
• Anti-pattern identification

🏗️ High-Level Architecture Design

• 2-3 architectural options with trade-offs
• Component diagrams (ASCII/Mermaid)
• Pattern justification with requirements traceability
• Failure mode analysis (FMEA)
• Systems thinking checks (feedback loops, cascades)

📊 Capacity Planning

• QPS estimation with formulas (DAU → average → peak)
• Storage projections (1yr, 3yr, 5yr)
• Bandwidth analysis (ingress/egress)
• Compute sizing (server counts, DB connections)
• Caching impact analysis
• SLA matrix definition

🗄️ Database & API Design

• Technology selection with justification
• Entity-relationship modeling
• Schema DDL (SQL) or document structure (NoSQL)
• Indexing and sharding strategy
• REST/GraphQL/gRPC endpoint catalog
• OpenAPI specifications

📝 Architecture Decision Records

• MADR-format ADRs for every major decision
• Options considered table (pros/cons)
• Rationale tied to requirements and research
• Consequences analysis (positive/negative/neutral)
• Second-order effects (team, process, ops impact)

🔒 Security Analysis

• Authentication and authorization design
• Transport security (TLS, mTLS)
• Data encryption at rest
• Rate limiting and DDoS protection
• Compliance requirements (GDPR, HIPAA, PCI-DSS)
• Audit logging

📚 Self-Improving Knowledge Base

• Weekly crawl of engineering blogs (Netflix, Uber, Airbnb, etc.)
• ArXiv paper fetching (cs.DC, cs.SE)
• SHA256-based deduplication
• Structured append to SECOND-KNOWLEDGE-BRAIN.md

---

How It Works

The Harness Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                          /system-design invocation                          │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    │               │               │
            ┌───────▼───────┐ ┌───▼────┐ ┌───────▼───────┐
            │  Stage 1:    │ │ Stage 2│ │  Stage 3:     │
            │ Requirements  │ │Research │ │  Architecture │
            │  Gathering   │ │ Phase  │ │    Design     │
            └───────┬───────┘ └───┬────┘ └───────┬───────┘
                    │             │             │
                    └─────────────┼─────────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    │             │             │
            ┌───────▼───────┐ ┌───▼────┐ ┌──────▼──────┐
            │  Stage 4:    │ │ Stage 5│ │  Stage 6:    │
            │  Capacity    │ │ DB &   │ │     ADRs     │
            │  Planning    │ │  API   │ │              │
            └───────┬───────┘ └───┬────┘ └──────┬──────┘
                    │             │             │
                    └─────────────┼─────────────┘
                                  │
            ┌─────────────────────▼─────────────────────┐
            │              Stage 7: Document              │
            │              Assembly                      │
            └─────────────────────┬─────────────────────┘
                                  │
            ┌─────────────────────▼─────────────────────┐
            │            Stage 8: Quality Gate           │
            │              (7 checks)                   │
            └─────────────────────┬─────────────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │  System Design Document   │
                    │  (10 sections, complete)  │
                    └───────────────────────────┘

Stage Details

Stage	Sub-Skill	Output	Quality Gates
1. Requirements	sub-gather-requirements	FR/NFR tables, constraints, scope	5+ FRs, 5+ NFRs with numbers
2. Research	sub-research-similar-cases	Case studies, patterns, anti-patterns	3+ analogues, evidence tier
3. Architecture	Inline	Component diagram, options	FMEA, systems thinking
4. Capacity	sub-capacity-planning	QPS, storage, SLA matrix	Formulas shown, projections
5. DB & API	Inline	Schema, endpoint catalog, OpenAPI	DB ↔ API consistency
6. ADRs	sub-adr-writer	Decision records	3+ ADRs, 2+ alternatives each
7. Document	sub-document-writer	Complete design doc	All 10 sections populated
8. Quality Gate	Inline	Pass/fail on 7 gates	All gates must pass

---

Installation

Prerequisites

• Claude Code CLI (latest version)
• Git

Clone the Repository

git clone https://github.com/dungnotnull/system-design-hd-skill.git
cd system-design-hd-skill

Install Claude Code Skill

# Copy to your Claude skills directory
cp -r . ~/.claude/skills/system-design

# Or use the skill CLI
claude skill install system-design

Optional: Knowledge Updater Dependencies

For the self-improving knowledge base:

cd tools
pip install -r requirements.txt

---

Usage

Basic Usage

/system-design

The skill will guide you through all 8 stages interactively.

Example: Design a URL Shortener

You: Design a URL shortening service like bit.ly. Short URLs must redirect in under 50ms.

Aria (system-design): Before I design anything, I need to fully understand the problem.
[Stage 1: Requirements Gathering]
- What is your target DAU?
- What is the expected read-to-write ratio?
[... continues through all 8 stages ...]

Aria: Here is your complete System Design Document:
[10-section document with HLD, DB schema, API contract, ADRs, capacity plan]

Advanced Options

# Specify a starting stage (skip requirements)
/system-design --stage=3 "Design a chat app"

# Educational mode (explains each decision)
/system-design --educational "How does Twitter scale?"

# Review mode (analyze existing HLD)
/system-design --review ./docs/hld.md

---

Architecture

Project Structure

system-design-hd-skill/
├── README.md                           # This file
├── CLAUDE.md                           # Skill-level memory
├── PROJECT-detail.md                   # Full technical spec
├── PROJECT-DEVELOPMENT-PHASE-TRACKING.md
├── SECOND-KNOWLEDGE-BRAIN.md           # Domain knowledge base
├── COMPLETION-SUMMARY.md               # 80% completion status
│
├── skills/                             # Harness implementation
│   ├── main.md                         # Primary orchestrator (8 stages)
│   ├── sub-gather-requirements.md      # Stage 1 sub-skill
│   ├── sub-research-similar-cases.md   # Stage 2 sub-skill
│   ├── sub-capacity-planning.md        # Stage 4 sub-skill
│   ├── sub-adr-writer.md               # Stage 6 sub-skill
│   └── sub-document-writer.md          # Stage 7 sub-skill
│
├── tools/                              # Supporting tools
│   ├── knowledge_updater.py            # Weekly knowledge base crawler
│   └── requirements.txt                 # Python dependencies
│
├── tests/                              # Validation and test results
│   ├── test-scenarios.md               # 7 test scenarios
│   ├── execution-log-*.md              # Test execution logs
│   ├── quality-gates-enforceability-analysis.md
│   └── knowledge-updater-test-report.md
│
└── docs/                               # Additional documentation
    └── skill-7-integration-analysis.md # Future cross-skill integration plan

Sub-Skill Interfaces

sub-gather-requirements:
  input: User problem statement
  output: requirements-spec.md
  tools: WebSearch, Read, Write
  gates: 5+ FRs, 5+ NFRs with numbers

sub-research-similar-cases:
  input: Problem domain from Stage 1
  output: research-report.md
  tools: WebSearch, WebFetch, Read
  gates: 3+ case studies, evidence tier

sub-capacity-planning:
  input: NFRs from Stage 1
  output: capacity-plan.md
  tools: WebSearch, Write
  gates: Formulas shown, 1/3/5yr projections

sub-adr-writer:
  input: Decisions from Stages 3-5
  output: adr-collection.md
  tools: Write
  gates: 3+ ADRs, 2+ alternatives each

sub-document-writer:
  input: All stage outputs
  output: system-design-document.md
  tools: Read, Write
  gates: All 10 sections populated

---

Documentation

• PROJECT-detail.md - Full technical specification
• PROJECT-DEVELOPMENT-PHASE-TRACKING.md - Build roadmap and status
• SECOND-KNOWLEDGE-BRAIN.md - Domain knowledge base
• COMPLETION-SUMMARY.md - 80% completion details

Test Scenarios

• test-scenarios.md - 7 concrete test scenarios
• execution-log-url-shortener.md
• execution-log-microservices-migration.md
• execution-log-chat-application.md
• execution-log-ecommerce-checkout.md
• execution-log-ml-model-serving.md

---

Development

Current Status

Phase 0-4: Complete ✅

• Architecture defined
• All sub-skills written
• Main harness implemented
• Test scenarios validated
• Quality gates enforceability verified

Phase 5: Pending (Skipped per user request)

• Cross-skill integration with Skill 7 (research-first-reasoning)
• Shared sub-skill export for Cluster A

Completion: 80% - Production-ready for core functionality

Running Tests

# Validate harness execution
# (Manual validation - see execution-log-*.md files)

# Test knowledge_updater (requires Python env)
cd tools
python knowledge_updater.py --dry-run

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas for contribution:

• Additional test scenarios
• Knowledge base improvements
• Documentation enhancements
• Bug fixes and optimizations

---

Testing

Test Scenarios Validated

Scenario	Domain	Complexity	Status
URL Shortener	Classic interview	Medium	✅ Pass
Real-time Chat	WebSocket, messaging	High	✅ Pass
E-commerce Checkout	Saga pattern, PCI-DSS	High	✅ Pass
ML Model Serving	GPU, k8s, versioning	High	✅ Pass
API Gateway Migration	Strangler Fig, zero-downtime	High	✅ Pass

Quality Gates

31 total gates across all stages:

• 22 fully enforceable (71%)
• 7 partially enforceable (23%)
• 2 conversational (6%)

See quality-gates-enforceability-analysis.md for details.

---

Roadmap

Completed ✅

• Phase 0: Research & Skill Architecture
• Phase 1: Core Sub-Skills (5 skills)
• Phase 2: Main Harness + Quality Gates
• Phase 3: Knowledge Brain Pipeline
• Phase 4: Testing & Validation (5 scenarios)

In Progress 🚧

• Phase 5: Cross-Skill Integration
  • Skill 7 (research-first-reasoning) integration
  • Shared sub-skills for Cluster A

Future 📋

• Additional test scenarios (10+ total)
• Runtime testing of knowledge_updater.py
• Automated gate checker tool
• VS Code extension for design doc editing

---

Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Ensure all quality gates pass

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Acknowledgments

• Engineering Blogs for system design case studies (Netflix, Uber, Airbnb, Meta, AWS, Google, Spotify)
• ArXiv for distributed systems and software engineering papers
• system-design-primer for foundational patterns
• Claude Code for the skill framework
• MADR for Architecture Decision Record format

---

Star History

---

Built with ❤️ for the systems design community

🔝 Back to Top