system-design

执行环境

| 路径类型 | 说明 | |---------|------| | 使用方式 | 此技能提供模板和指导，无需本地脚本执行 | | 调用场景 | 当用户需要系统设计、架构文档、技术选型时自动激活 | | 输出位置 | docs/design-catalog/ 目录（相对于项目根目录） |

路径说明

• 无本地脚本依赖：此技能生成文档模板，不涉及本地脚本执行
• 生成的目录：保存在执行命令时的当前目录下的 docs/design-catalog/
• 项目上下文：基于当前工作目录确定项目根目录

System Design Through EventStorming

Overview

Transform requirements into navigable design catalogs using EventStorming methodology and Mermaid diagrams.

Core principle: Progressive elaboration through event-driven thinking, producing token-efficient visual artifacts in standardized catalog structure.

Announce at start: "I'm using the system-design skill to create a design catalog for your system."

When to Use

Use when:

• User wants to design a new system
• Requirements exist but design doesn't
• Need structured thinking before implementation
• Team needs shared visual artifacts

Don't use when:

• Adding features to existing system (consider brainstorming instead)
• Implementation already started
• User wants code, not design

Quick Reference

| Phase | Key Activities | Output Files | |-------|---------------|-------------| | 1. Requirements | Ask questions, identify actors/constraints | requirements.md | | 2. Big Picture | EventStorming timeline with events/commands | big-picture.mmd | | 3. Processes | Zoom into critical processes, add aggregates | process-{name}.mmd | | 4. Data & Flows | ERD, state charts, sequences | erd.mmd, state-{entity}.mmd, sequence-{flow}.mmd | | 5. Integration | Generate catalog README | README.md |

The Iron Laws

Law 1: ASK QUESTIONS - No Assumptions

NEVER make "industry-standard assumptions" without asking the user first.

• Ask about actors, constraints, scale, budget, timeline
• Use AskUserQuestion tool for architectural choices
• Mark unclear areas as hotspots instead of assuming

Bad:

 "I'll assume standard PostgreSQL for data storage"
 "Proceeding with industry-standard assumptions"
 "I'll design for moderate scale (10K users)"

Good:

 "What database are you currently using?" (AskUserQuestion with options)
 "What scale are you targeting?" (AskUserQuestion: 100 users / 10K / 100K+)
 "Budget constraints for infrastructure?" (Ask directly)

Law 2: MERMAID ONLY - No ASCII Diagrams

All diagrams MUST use Mermaid format. NO exceptions.

• No ASCII art
• No text-based diagrams
• No "version control friendly" excuses for avoiding Mermaid

Bad:

 ASCII art entity relationships
 Text-based flowcharts
 "I'll create ASCII diagrams because they're universal"

Good:

 Mermaid ER diagrams
 Mermaid flowcharts
 Mermaid sequence diagrams
 Mermaid state charts

Law 3: EVENTSTORMING - Event-Driven Thinking

Use EventStorming methodology for Phases 2-3. Required.

• Identify domain events (what happens in the system)
• Add commands (what triggers events)
• Add actors (who initiates)
• Add systems (external integrations)
• Mark hotspots (unclear/risky areas)

Bad:

 "Using traditional waterfall analysis"
 "Creating use cases and functional specs"
 "Based on proven patterns" (without events)

Good:

 "Let's identify key business events" (EventStorming)
 "What triggers each event?" (Commands)
 "What data changes when this event happens?" (Aggregates)

Law 4: CATALOG STRUCTURE - Standardized Organization

All artifacts go into docs/design-catalog/ with specific structure.

docs/design-catalog/
  README.md              # Navigation hub
  requirements.md
  big-picture.mmd
  processes/
    process-{name}.mmd
  data/
    erd.mmd
    state-{entity}.mmd
  flows/
    sequence-{flow}.mmd

No random file names. No mixed concerns.

Law 5: DESIGN NOT IMPLEMENTATION

Stay at design abstraction. NO implementation details in design phase.

Forbidden in design artifacts:

• Database schemas (SQL, migrations)
• Deployment guides (Docker, Kubernetes)
• CI/CD pipelines
• Specific technology choices (unless user specified)
• Implementation timelines (16-week plans)
• Team structure recommendations
• Code examples (API endpoints, controllers, services, functions)
• Configuration files (YAML, JSON, ENV)

Allowed:

• Entity relationships (conceptual)
• State transitions (conceptual)
• Event flows (conceptual)
• Integration points (generic)
• Hotspots for technical decisions

Law 6: TOKEN EFFICIENCY - Diagrams Over Prose

Prefer Mermaid diagrams over lengthy text descriptions.

Token targets by project complexity:

• Simple (single service, 5-10 entities): < 10K tokens
• Medium (2-3 services, 10-20 entities): < 20K tokens
• Complex (multiple services, 20+ entities): < 35K tokens

If exceeding targets, check:

• Are you writing prose that diagrams could show?
• Are you repeating information across files?
• Are you including implementation details?

Bad:

 4,000 lines of documentation
 Verbose explanations of every decision
 Repeating information across files
 "This is complex so 50K tokens is reasonable"

Good:

 Mermaid diagram with annotations
 Cross-reference: "See big-picture.mmd for event flow"
 Tables for entity attributes
 Minimal prose, maximum visual clarity

The 5 Phases

REQUIRED: Use TodoWrite to track phase progress.

Copy this checklist:

System Design Progress:
- [ ] Phase 1: Requirements (actors, constraints, goals identified)
- [ ] Phase 2: Big Picture (EventStorming timeline created)
- [ ] Phase 3: Processes (Critical processes detailed)
- [ ] Phase 4: Data & Flows (ERD, state charts, sequences created)
- [ ] Phase 5: Integration (Catalog assembled, next steps planned)

Phase 1: Requirements Understanding

Goal: Understand context before designing

Activities:

1. Ask questions ONE at a time (following brainstorming pattern)
2. Use AskUserQuestion for architectural choices with trade-offs
3. Identify: business goals, constraints, key actors, success criteria

Questions to ask:

• "What problem does this system solve?"
• "Who are the primary users/actors?"
• "What are the critical constraints?" (performance, scale, budget, timeline)
• "How do you define success?"
• "What systems need to integrate?"

Output: Create docs/design-catalog/requirements.md

Validation: Present requirements summary, ask: "Does this capture the scope?"

Phase 2: EventStorming Big Picture

Goal: Understand business process through events

Announce: "Let's explore the business process through EventStorming."

Activities:

1. Ask: "What are the key business events that happen in this system?"
2. Build timeline collaboratively (add events as user describes)
3. Ask: "Who triggers each event? What commands cause them?"
4. Add actors and commands
5. Ask: "Are there external systems involved?"
6. Add external systems
7. Mark hotspots for unclear areas (DON'T assume, MARK AS HOTSPOT)

EventStorming Color Conventions (Mermaid):

flowchart LR
    %% Style definitions
    classDef event fill:#ff9800,stroke:#e65100,color:#000
    classDef command fill:#2196f3,stroke:#0d47a1,color:#fff
    classDef actor fill:#ffeb3b,stroke:#f57f17,color:#000
    classDef system fill:#9c27b0,stroke:#4a148c,color:#fff
    classDef aggregate fill:#4caf50,stroke:#1b5e20,color:#fff
    classDef hotspot fill:#f44336,stroke:#b71c1c,color:#fff

    Actor[Customer]:::actor
    Cmd1[Place Order]:::command
    Evt1[Order Placed]:::event
    Agg1[Order]:::aggregate
    Sys1[Payment Gateway]:::system
    Hot1[? Refund policy unclear]:::hotspot

    Actor --> Cmd1
    Cmd1 --> Evt1
    Evt1 --> Agg1
    Agg1 --> Sys1
    Evt1 -.question.- Hot1

Output: Create docs/design-catalog/big-picture.mmd

Validation: Present diagram, ask: "Does this capture the high-level flow?"

Phase 3: Process EventStorming

Goal: Detail specific processes from big picture

Activities:

1. Identify 2-4 critical processes to