devdocs-system-design

System Design

Create or update the system design document based on the requirements document, supporting both initial design and incremental design modes.

Language Rules

Support questions in Chinese and English
Always reply in Chinese
Generate documents in Chinese

Trigger Conditions

Initial Design Mode

The user has completed the requirements document, and the project has no system design
The user requests system/technical design
The user needs architecture or API design

Incremental Design Mode

Design changes are needed after new features are added (from /devdocs-feature）
Design adjustments are needed after optimization suggestions are confirmed (from /devdocs-insights）
Technical improvements require architecture adjustments
The user requests to update/modify the existing design

Prerequisites

Requirements document:docs/devdocs/01-requirements.md
If it does not exist, it is recommended to first run /devdocs-requirements

Design Mode Detection

启动时自动检测
      │
      ▼
检查 02-system-design.md 是否存在
      │
      ├── 不存在 → 初始设计模式
      │
      └── 存在 → 增量设计模式
            │
            ▼
      检查是否有新增需求（F-XXX）未覆盖
            │
            ├── 有 → 提示增量设计
            │
            └── 无 → 询问用户意图

Run Mode

/devdocs-system-design              → 自动检测模式（初始/增量）
/devdocs-system-design --fast       → 跳过 Plan 模式，使用合理默认值，仅最终确认

`--fast` mode

Skip the EnterPlanMode step and the tech stack preference inquiry
Use reasonable defaults (infer the tech stack from the codebase)
Keep only 1 confirmation before the final write
Default behavior remains unchanged,--fast is opt-in

Workflow

Initial Design Workflow

1. 读取需求 → 加载 01-requirements.md
      │
      ▼
2. 询问偏好 → 技术栈、平台、集成需求
      │
      ▼
3. 探索代码 → 了解现有架构
      │
      ▼
3.5 外部研究（按需）→ 详见"设计前外部研究"章节
      │
      ▼
4. 进入 Plan 模式 → 呈现设计方案草案
      │              （技术选型、架构方向、模块划分）
      ▼
5. 用户审批 Plan → 确认方向或调整
      │
      ▼
6. 退出 Plan 模式 → 生成 docs/devdocs/02-system-design.md 文档
      │
      ▼
7. 验证覆盖 → 检查所有 F-XXX 都有对应模块/接口
      │
      ▼
8. 用户确认 → 获得批准后定稿

Incremental Design Workflow

1. 读取现有设计 → 加载 02-system-design*.md
      │
      ▼
2. 识别变更来源
      ├── 新功能需求（F-XXX）
      ├── 优化建议（INS-XXX）
      └── 技术改进
      │
      ▼
3. 影响分析
      ├── 识别受影响的模块
      ├── 识别受影响的接口
      └── 识别受影响的数据模型
      │
      ▼
4. 兼容性评估
      ├── 接口变更是否向后兼容？
      ├── 数据模型变更是否需要迁移？
      └── 是否有破坏性变更？
      │
      ▼
5. 进入 Plan 模式 → 呈现变更方案
      │              （影响范围、兼容性结论、变更策略）
      ▼
6. 用户审批 Plan → 确认方案或调整
      │
      ▼
7. 退出 Plan 模式 → 更新 docs/devdocs/02-system-design*.md 文档
      ├── 文档中新增模块/接口/数据模型章节
      ├── 更新现有设计文档内容
      └── 在文档中标注变更版本
      │
      ▼
8. 生成变更记录 → 追加到设计文档
      │
      ▼
9. 用户确认 → 获得批准后更新文档

Plan Mode Specification

After analysis is complete and before writing the document,EnterPlanMode must be used to present the design draft, and execute only after user approval.

Initial Design Plan Content

## 设计方案草案

### 技术选型
- 语言/框架：<选择> — <理由>
- 数据库：<选择> — <理由>
- 其他关键依赖：<列表>

### 架构方向
- 架构风格：<分层/微服务/Serverless/...>
- 核心设计决策：<列表>

### 模块划分
| 模块 | 职责 | 关联功能点 |
|------|------|-----------|
| ... | ... | F-XXX |

### 关键接口概要
- <接口名>: <职责摘要>

### 风险与权衡
- <取舍点1>: 选择 A 而非 B，因为 ...

Incremental Design Plan Content

## 变更方案草案

### 变更来源
- F-XXX / INS-XXX: <描述>

### 影响范围
| 影响对象 | 影响类型 | 向后兼容 |
|----------|----------|----------|
| ... | 新增/修改/删除 | ✅/❌ |

### 变更策略
- <具体变更动作列表>

### 破坏性变更处理
- <如有，列出迁移方案>

Plan Mode Timing

Mode	Entry Timing	Plan Content
Initial Design	After reading requirements + asking preferences + exploring code	Technology selection, architecture direction, module division
Incremental Design	After impact analysis + compatibility assessment	Impact scope, change strategy, migration plan

External Research Before Design

When requirements involve unfamiliar technologies/frameworks or complex integrations, external research should be conducted before Plan mode (depending on available external retrieval tools).

Trigger Conditions: technologies not previously used in the project, complex third-party integrations, or multiple feasible options that need comparison.

Three Research Steps：

Existing Code Pattern Scan — Scan the project architecture and docs/devdocs/patterns/ existing experience to confirm compatibility.Must search the patterns/ directory: scan the title list, match keywords for the current design requirements, and if there is a hit, read the details as design reference (to avoid repeating pitfalls and reuse validated solutions)
Official Documentation Confirmation(if external retrieval tools are available) — Consult official documentation to confirm API availability, version compatibility, and known limitations (context7 MCP can be used)
Best Practices Summary(if external retrieval tools are available) — Search community best practices and common pitfalls, and compare the pros and cons of options

Research conclusions must be written into the design document(the "Technology Selection" section), format:

#### <技术名称>
**研究结论**：
- 官方文档确认：<版本、兼容性、限制>
- 最佳实践：<关键发现>
- 选择理由：<为什么选这个方案>
- 已知风险：<潜在问题和缓解措施>

Skip Conditions: using the project's existing tech stack, simple requirements with a clear solution,--fast mode.

Must Ask Before Design

Must use AskUserQuestion to ask the user：

Tech Stack Preference
- Is there a preferred tech stack?
- Options: Specify tech stack / No preference (will recommend based on requirements)
Target Platform
- What is the target platform?
- Options: Web / Mobile (iOS/Android) / Desktop / Server / Cross-platform
Deployment Environment
- Where will it be deployed?
- Options: Cloud service (AWS/GCP/Azure) / On-premises / Hybrid
Existing System Integration
- Does it need to integrate with existing systems?
- Options: No / Yes (specify system, API, database)

If the user has no preference, design the optimal solution based on the requirements.

Incremental Design

Incremental design follows a three-step process:Change scope classification → Impact analysis → Compatibility assessment, then update the design document and generate an ADR record.

Change scope is divided into three levels: internal implementation only (lightweight analysis), involving module interfaces (standard analysis), involving architecture (full analysis + ADR)
Impact analysis must cover affected modules, interfaces, and data models, and automatically scan related documents
Compatibility assessment determines backward compatibility; breaking changes must specify a deprecation period and migration plan
Each change item uses a unified change comparison format (before change / after change / reason / impact scope)

When entering incremental design mode, must read incremental-design.md to obtain impact analysis, compatibility assessment, change comparison format, and checklist.

Output Files

Main File：docs/devdocs/02-system-design.md

Document Splitting Rules

Documents should be split when the following conditions are met:

Document exceeds 300 lines
Number of modules exceeds 5
Number of API interfaces exceeds 10

Splitting Method：

docs/devdocs/
├── 02-system-design.md          # 主文档：架构概览、技术选型、模块划分
├── 02-system-design-api.md      # API 设计：接口定义、请求响应示例
└── 02-system-design-data.md     # 数据模型：实体定义、ER 图、索引策略

Split Content Allocation：

File	Sections Included
02-system-design.md	1-7: Platform, architecture, technology selection, modules, interface signatures, patterns, code structure
02-system-design-api.md	9-10: Complete API design, state transitions
02-system-design-data.md	8, 11-13: Data model, exception handling, scalability, requirements traceability

For detailed templates, see templates/design-template.md。

Design Principles

MTE Principles

System design must follow the MTE principles：

Principle	Description	Checkpoint
Maintainability	Maintainability	Single responsibility for modules, clear dependencies, easy to understand and modify
Testability	Testability	Core logic can be unit tested, dependencies can be Mocked, clear boundaries (refer to `/testing-guide`）
Extensibility	Scalability	Reserve extension points, interface abstraction, open-closed principle

Design Pattern Selection

Choose appropriate design patterns based on the scenario,use them only when necessary：

Scenario	Recommended Pattern	Applicable Cases
Object Creation	Factory / Builder	Complex object construction, creation of multiple types
Behavior Extension	Strategy / Template	Algorithm replaceable, fixed process with variable steps
Structural organization	Facade / Adapter	Simplify complex interfaces, adapt third-party libraries
State management	State / Observer	State-driven behavior, event notification
Data access	Repository / DAO	Data layer abstraction, query encapsulation

Design layers

Interface layer (thin layer) → Service layer (core business logic) → Domain layer (entities/value objects) → Infrastructure layer (data access/external services)

Document structure

Target platform - Platform, version requirements, deployment environment
Architecture overview - High-level architecture diagram (Mermaid）
Technology selection - Technology choices and rationale
Module design - Module responsibilities and dependencies,annotate associated feature points (F-XXX)
Core interfaces - Interface-oriented (signatures only): Key interface and method signatures (Strictly prohibited from containing concrete implementation logic), annotate associated F-XXX
Design patterns - Applied patterns and rationale
Code structure - Directory structure design
Data model - Entity definitions and relationships
API design - Interface endpoints and request/response examples,annotate associated F-XXX, AC-XXX
State transitions - State machines for key business processes
Exception handling - Error codes and handling strategies
Logging design - Log levels, key logging points, trace IDs
Extensibility - Extension points and future considerations
Requirements traceability - Mapping relationships between feature points and modules/interfaces,coverage checklist

Detailed reference

Core interface design: Define signatures only without writing implementations, annotate associated F-XXX → templates/design-template.md
Code structure design: Organize directory structure according to layered architecture → templates/design-template.md
Logging design: Levels, key logging points, format, trace ID → templates/log-design-guide.md

Constraints

Phase boundary constraints (highest priority)

This Skill only produces documents; strictly prohibited from writing or generating any implementation code (source code, scripts, configuration changes)
The Write tool is only used to write docs/devdocs/ Markdown documents under
The "Core Interfaces" section only defines signatures; strictly prohibited from containing implementation logic
After exiting Plan mode, update the design document (not code implementation)
Coding implementation is handled by /devdocs-dev-workflow , which this Skill does not involve

Basic constraints

Must first ask the user for technology stack preferences and target platform
Technology selection must state the rationale
If the user has no preference, choose the optimal solution based on requirements
Must specify the target platform and minimum version requirements
API design must include request/response examples
Data model must consider indexes and query patterns
Must identify integration points with existing systems
Prioritize using the project's existing tech stack

MTE principle constraints

Each module has a single responsibility and no more than one reason to change
Core business logic must be unit testable(no external dependencies or dependencies can be mocked, see /testing-guide）
Reserve reasonable extension points, but do not design for hypothetical requirements
Dependency direction: outer layers depend on inner layers, inner layers do not depend on outer layers
Interfaces over implementations: depend on abstractions, not concrete implementations

Design pattern constraints

Use design patterns only when solving real problems, not for the sake of using them
Design patterns used must explain what problem they solve
Prefer simple solutions; complex solutions require justification
Use consistent patterns in the project for the same problem

Avoid over-engineering

Do not design for "possible future" requirements, design only for current requirements
Do not create interfaces with only one implementation (unless for testability)
Do not abstract prematurely; wait until there are 3 or more similar scenarios before abstracting
Configuration is better than hardcoding, but do not add configuration for everything

Security constraints

Sensitive data (passwords, tokens) is not stored in plaintext
APIs requiring authentication are marked
User input is validated (to prevent injection)
Sensitive operations are logged

External research constraints

When unfamiliar technology is involved and external retrieval tools are available, external research should be completed before Plan mode; when no external tools are available, conduct research based on existing code pattern scanning and user input
Research conclusions must be written into the design document, not only exist in the conversation
Research can be skipped for existing tech stacks or simple requirements
--fast mode skips the research step

Plan mode constraints

Initial design: after reading requirements + asking preferences + exploring code (+ external research), must enter Plan mode
Incremental design: after impact analysis + compatibility assessment, must enter Plan mode
Plan must include technical selection rationale (initial) or impact scope (incremental)
Documents can only be written after the user approves the Plan
When the user requests adjustments, update the Plan and re-approve it

Incremental design constraints

Impact analysis must be performed before incremental design
Backward compatibility must be assessed
Breaking changes must be marked with handling methods
Design change records must be generated
New content must be marked with associated requirements (F-XXX / INS-XXX)
Modifying existing interfaces must explain compatibility
Data model changes must explain the migration plan
Incremental design must first classify the change scope
Changes involving module interfaces or architecture must use the change comparison format
Must automatically scan affected documents and list an update checklist

Skill collaboration

Scenario	Collaborating Skill	Description
New feature design changes	`/devdocs-feature`	New features trigger incremental design
Optimization suggestion design changes	`/devdocs-insights`	Incremental design is triggered after insight confirmation
Testability design	`/testing-guide`	Ensure core logic is unit testable
Code quality	`/code-quality`	MTE principles guide design
UI architecture	`/ui-orchestrator`	Route to specialized external UI/UX Skill
Automatic interface extraction	`/devdocs-retrofit`	Reverse-extract interface definitions from existing code and sync them to design documents

Sub-Agent summary format

When this Skill runs as a sub-Agent, return the following structured summary:

skill: devdocs-system-design
mode: initial | incremental
modules_added: [AuthModule, UserModule]
interfaces_added: ["POST /api/register", "POST /api/login"]
data_models_added: [User, Session]
breaking_changes: false
patterns_referenced: []  # 从 docs/devdocs/patterns/ 匹配的模式
status: completed
output_files:
  - docs/devdocs/02-system-design.md

Next steps

After initial design

After the user confirms the system design, it is recommended to run /devdocs-test-cases to enter the test case design phase.

After incremental design

If there are new feature points → run /devdocs-test-cases to supplement test cases
If there are data model changes → prepare database migration scripts
If there are breaking changes → notify relevant dependents

Tip: When document changes are significant, it is recommended to run /agent-memory to sync memory files.