system-design

System Design

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

Role

Identity: System Architect
Focus: technical trade-offs, module boundaries, interface contracts, scalability
Avoid: user story details, product prioritization, UI visual and interaction implementation (consume design mockup data to drive APIs)
Judgment tendency: prioritize simple solutions; complexity requires a clear justification

Quick Start

One sentence: Create or update the system design document (architecture, API, data models).

Most common usage: /system-design(auto-detect initial/incremental)

Not suitable? Requirements not written yet →/requirements, UI design →ui-orchestrator

Language Rules

Support questions in Chinese and English
Reply uniformly 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 a system/technical design
The user needs architecture or API design

Incremental Design Mode

Design changes are needed after a new feature is added (from /feature）
Design adjustments are needed after optimization suggestions are confirmed (from /insights）
Technical improvements require architectural 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 run /requirements

Design Mode Detection

Automatically detect at startup:02-system-design.md does not exist → initial design mode; exists → check whether there are uncovered feature points (F-XXX); if so, prompt for incremental design; if not, ask the user for their intent.

Operating Modes

/system-design              → 自动检测模式（初始/增量）
/system-design --realign    → 规范升级回扫：已完成设计按新 spec_version 查漏补缺（不触发 L1~L4 重做）
/system-design --realign=<scope> → 限定范围：layer1/layer2/layer3/layer4 或具体章节名

Realign mode: When the system-design specification is upgraded (spec_version bump), the structure/fields of the existing design document are filled in according to the new specification;nota replacement for initial/incremental design, only performs "gap filling". See references/realign.mdfor details. Recommended user entry point /pipeline realign(uniformly scheduled by the orchestration layer).

Workflow

Initial design process (top-down L1~L4 layered progression)

1. 读取需求 → 加载 01-requirements.md（含 design_context）
      │
      ▼
2. 询问偏好 → 技术栈、平台、集成需求
      │
      ▼
3. 探索代码 → 针对需求涉及的接口/实体/表确认已有实现
      │
      ▼
3.5 外部研究（按需）→ 详见"设计前外部研究"章节
      │
      ▼
4. 自顶向下分层设计（逐层推进，但不逐层确认——见「何时需要你拍板」）
      ├── L1 架构层：§2 架构概览 + §1 运行平台
      │     聚焦：边界、分层、关键外部依赖
      ├── L2 模块层：§4 模块设计（职责 + 对外/依赖接口引用）
      │     聚焦：模块边界、单一职责、依赖方向面向接口
      │     自查：SRP / LoD / DIP（见 references/solid-principles-guide.md）
      ├── L3 接口行为层：§5 核心接口（签名 + 前置/后置/错误契约）
      │     聚焦：契约可测性、接口行为非代码细节
      │     ⛔ 强制通过"设计边界自查清单"（references/design-boundary-guide.md）
      │     自查：OCP / LSP / ISP / DIP
      └── L4 数据模型层：§8 数据模型（实体/关系/索引）
            聚焦：存储层不可见细节（可观察约束应在 §5 错误契约）
      │
      ▼
5. 对抗性审查（按复杂度分级触发 SOLID+LoD，见 references/design-review.md）
      │
      ▼
6. 生成 docs/devdocs/02-system-design.md 文档（含审查结论 + 原则校验表 + 关键选型 ADR）
      │
      ▼
7. 验证覆盖 → 所有功能点（F-XXX）都有对应模块/接口
      │
      ▼
8. 有岔路 → 拍板后定稿；无岔路 → 直接定稿

Key Rules：

Each layer may leave ⏳ placeholders (some fields/error codes/parameters to be refined in the next layer or implementation phase); when L4 is completed, forcibly summarize all ⏳ lists
L3 vs L4 boundary determination: external callerobservablebehavior belongs to L3;invisiblepersistence details belong to L4 (see design-boundary-guide.md for details)
Layering is a design method, not a confirmation rhythm：L1L4 progresses layer by layer to ensure top-down stepwise refinement; boundary self-check (L1L4 boundary validation + out-of-bounds counterexamples + principle validation)is executed constantly and written directly into the document, without occupying the user confirmation interface.

When You Need to Make the Call

One-sentence criterion:Does this requirement have more than two reasonable approaches?

Situation	Action
No — Single-function scope, self-evident approach (reuse the existing tech stack, no new external dependencies, no structural trade-offs)	Don't ask. Produce 02 directly; consistency is handled by `/verify --docs` 承担。步骤 2「询问偏好」同样跳过
Yes — There are forks that require setting a direction (technology selection, architectural style, key data model trade-offs, breaking changes)	Ask once, presenting only the forks themselves: what the options are, the cost of each, which one is recommended, and why

⛔ The confirmation interface must not present agent self-check artifacts(module breakdown table / interface summary / data model table / principle checklist / adversarial review table). Humans can't verify these accurately; the agent verifies them more accurately — they go straight into the document. Mixing them into the confirmation interface only degrades confirmation into a formality, producing fake "confirmed" records.

The criterion rests onwhether there are forks, not on requirement size. Scale is only a cheap proxy: large requirements usually have forks, small ones usually don't. If you do encounter something small with a fork (say, writing a single function but needing to choose an encryption algorithm), ask anyway.

与 ceremony 的关系: the orchestration layer's normalized ceremony（fast / standard / deep, see constraints.md task/normalized-intent-shape; the colloquial "fast track" i.e. fast) determineswhether to ask, and the fork criterion determineswhether there is anything to ask. The two are in an AND relationship:

	No forks	Forks present
`ceremony: fast`(the result of orchestration-layer normalization; this skill only reads it, never judges it)	Don't ask	Don't ask, but must disclose — the fork, which option I chose, and why, written prominently in 02's "Key Selection ADR"
`standard` / `deep`	Don't ask	Ask once

fast means the user is spared interruption, not spared awareness. The outsourcee may decide on its own, but not disclosing is not acceptable.

Incremental design process

1. 读取现有设计 → 加载 02-system-design*.md
      │
      ▼
2. 识别变更来源
      ├── 新功能需求（F-XXX）
      ├── 优化建议（INS-XXX，归类见 insights）
      └── 技术改进
      │
      ▼
3. 影响分析
      ├── 识别受影响的模块
      ├── 识别受影响的接口
      └── 识别受影响的数据模型
      │
      ▼
4. 兼容性评估
      ├── 接口变更是否向后兼容？
      ├── 数据模型变更是否需要迁移？
      └── 是否有破坏性变更？
      │
      ▼
5. 呈现变更方案 + 对抗性审查（AskUserQuestion）
      ├── 常规：三视角挑战（用户价值/架构兼容性/可测试性）
      ├── 新增：**修订清单表格**（必填，格式 §章节 | 动作 | 描述，≤10 行）
      │     动作枚举：新增 / 改写 / 局部调整 / 重构
      └── 新增：**原则校验表**（按复杂度触发 SOLID+LoD，三态强制填写）
      │
      ▼
6. 用户确认方案（含修订清单与原则校验）
      │
      ▼
7. 更新 docs/devdocs/02-system-design*.md 文档
      └── 按修订清单逐条执行正文更新（非仅 ADR 追加）
      │
      ▼
8. 追加变更记录（ADR 仅记 WHY，不记 WHAT；详见 incremental-design.md 检查清单）
      │
      ▼
9. 用户确认 → 获得批准后更新文档

Solution confirmation specification

Confirmation only happens whenthere are forks(for the criterion see "When you need to make the call"), and only forks are presented. For the draft template see references/plan-drafts.md。

Mode	Confirmation timing	What is presented
Initial design · forks present	After L1~L4 are completed, once	Only the forks: technology selection / architectural direction / key trade-offs — the cost of each option + which one is recommended + why
Initial design · no forks	No confirmation	—
Incremental design	After impact analysis + compatibility assessment	Impact scope, change strategy,revision checklist

Constraints：

Forks present: before confirmation, only show the solution, do not write to any file; generate only after the decision is made
No forks: generate the document directly,no confirmation gate— a going-through-the-motions confirmation leaves fake "confirmed" records
In all cases: only generate documents under docs/devdocs/ , implementation code is strictly forbidden
Agent self-check (boundary validation / out-of-bounds counterexamples / principle validation / adversarial review) is always executed, and the resultsare written to the document rather than the confirmation interface

Pre-design external research

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

Trigger conditions: technologies not previously used in the project, complex third-party integrations, or multiple feasible solutions that need to be compared.

Three research steps：

Existing code pattern scan — Scan the project architecture and docs/devdocs/patterns/ existing experience to confirm compatibility.The patterns/ directory must be searched: scan the title list and match keywords for the current design requirements; if there is a match, read the details as design reference (to avoid repeating pitfalls and reuse proven solutions)
Official documentation confirmation(if external retrieval tools are available) — Consult official documentation to confirm API availability, version compatibility, and known limitations (context7 MCP may be used)
Best practice summary(if external retrieval tools are available) — Search for community best practices and common pitfalls, and compare the pros and cons of solutions

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

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

Skip conditions: using the project's existing technology stack, or simple requirements with a clear solution (i.e., "no fork in the road").

Must-ask before design

AskUserQuestion must be used to ask the user：

Technology stack preference
- Do you have a preferred technology stack?
- Options: specify a technology 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 an existing system?
- 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, you must read incremental-design.md to obtain the impact analysis, compatibility assessment, change comparison format, and checklist.

Output files

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

Document splitting rules

The document should be split when the following conditions are met:

The document exceeds 300 lines
Number of modules exceeds 5
Number of API interfaces exceeds 10

Split method：

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

Split content allocation：

File	Included chapters
02-system-design.md	1-7, 15-16: Platform, architecture, technology selection, modules, interface signatures, patterns, code placement principles, design review, ADR
02-system-design-api.md	9-10: Complete API design, state transitions
02-system-design-data.md	8, 11-14: Data model, exception handling, extensibility, requirements traceability

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

Information organization

When writing and incrementally updating design documents, follow the five principles of doc-organization . The two most closely related to this skill:

Change rationale belongs in the ADR chapter, not in the main text introduction——Putting the revision history in the introduction causes "what the current design is" to have two answers within the same document (the old statement in the main text coexisting with the new conclusion in the revision history)
Module numbering (M1 / M2 …) and ADR-NNN should be explained at first occurrence——Rejected modules are especially prone to leaving only a name ("delete M3") without ever being defined, and cannot be supplemented afterward

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, boundaries are clear (refer to `/testing-guide`）
Extensibility	Extensibility	Reserve extension points, interface abstraction, open-closed principle

Design pattern selection

Choose appropriate design patterns according to the scenario,use them only when necessary. See references/design-patterns.md。

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 (signature + behavioral contract): Method signature + preconditions/postconditions/error contract (must not include specific implementation logic), annotate associated feature points (v1: F-XXX / v2: FEAT-XXX)
Design patterns - Applied patterns and rationale
Code placement principles - Module placement/interface-implementation separation/naming constraints (not a complete directory tree; see references/code-structure-conventions.md）
Data model - Entity definitions and relationships
API design - Interface endpoints and request/response examples,annotate associated feature points (v1: F-XXX / v2: FEAT-XXX) + AC-XXX; when design_context exists, page data requirements drive the response structure
State Transitions - State machine 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 between feature points and modules/interfaces,Coverage Checklist
Design Review - Adversarial review conclusions (from product/engineering/testing perspectives)
Design Change Records (ADR) - Initial design records key selections, incremental design records changes

Detailed Reference

Complete Design Document Template → templates/design-template.md
Logging Design → templates/log-design-guide.md
Adversarial Review Question Checklist → references/design-review.md
UI→API Mapping → references/design-input-guide.md
Design Boundary Counterexamples (Design vs Implementation) → references/design-boundary-guide.md
SOLID+LoD Six Principles Guide → references/solid-principles-guide.md
Code Directory Conventions (Non-Design Decisions) → references/code-structure-conventions.md
Solution Draft Template (Initial + Incremental) → references/plan-drafts.md
Incremental Design Details → references/incremental-design.md
Realign Sub-process (Specification Upgrade Rescan) → references/realign.md

Constraints

Phase Boundary Constraints (Highest Priority)

⛔ Do not proceed: The documentation phase must not produce implementation code (source code, scripts, configuration changes)(Recovery method: use /dev-workflow to perform coding)
The "Core Interfaces" section only defines signatures and behavioral contracts; implementation logic is strictly prohibited (coding is handled by /dev-workflow )
⛔ Do not proceed: Out-of-bounds counterexamples appear within interface contracts(Algorithm refinement/internal state/control flow/pseudocode/field descriptive comments/timing retry strategies/dependency coupling to implementation, see references/design-boundary-guide.md)(Recovery method: rewrite as behavioral contract statements)
⛔ Do not proceed: When cross-module dependencies exist, the "Dependency Interface Reference" column in the §4 module table contains specific implementation class names or bare module names(Recovery method: rewrite as I*(§章节号) references; if the interface is undefined, go back to the L3 layer to supplement; for a single module or no cross-module dependencies, fill in "None")
⛔ Do not proceed (incremental design): Only ADRs are appended while the relevant sections of the main text are not updated(Recovery method: perform main text updates according to the revision checklist, or register "the reason for only appending ADRs" in the checklist)
⛔ Do not proceed: Generated/updated documents do not have generated_by / spec_version / generated_at three-field YAML frontmatter written at the top(Recovery method: complete according to the templates/design-template.md top example; for spec_version constants see references/realign.md）

Basic Constraints

Must first ask the user about technology stack preferences and target platform
Must specify the target platform and minimum version requirements
API design must include request/response examples
Data models must consider indexes and query patterns
Must identify integration points with existing systems, distinguishing existing implementations (reuse)/extension/new additions; the solution draft must include verification evidence
Prioritize using the project's existing technology stack

MTE + SOLID/LoD Principle Constraints

MTE is the higher-level goal (Maintainability/Testability/Extensibility, see references/mte-rubric.md); SOLID + the six Dimitri principles are the means to achieve the higher-level goalDesign Evidence(see references/solid-principles-guide.md). The two sets are not merged; during MTE evaluation, SOLID is cited as evidence.

Core business logic must be unit-testable(no external dependencies, or dependencies can be mocked)
Core interfaces must include behavioral contracts(pre-/post-/error contracts), so that tests can be written independently of the implementation
For the DIP hard constraint, see §4 Dependency Interface Reference Gate in "Phase Boundary Constraints"; the remaining 5 principles are heuristic threshold warnings (exceeding the threshold requires justification + ADR, not a hard block)

For the criteria checklist on module responsibilities / abstraction timing / design pattern selection, see references/mte-rubric.md; this section does not mirror it.

Avoid Over-Design

Do not design for "possible future" requirements; design only for current requirements
Dependency inversion is retained by default: modules communicate through §5 interfaces; the next constraint on "single-implementation interfaces" only targets "over-abstraction (creating interfaces for purely internal details)",and does not weaken the core principle of "cross-module dependencies facing interfaces"
Do not create interfaces with only one implementation (unless for testability or cross-module boundaries)

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 technologies are involved and external retrieval tools are available, external research should be completed before solution confirmation; 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 merely exist in the conversation

Solution Confirmation Constraints

When the initial design has forks: the direction choices must be presented and the user must be awaited for a decision; when there are no forks, produce directly without a confirmation gate
Incremental design: after impact analysis + compatibility assessment, the solution must be presented and user confirmation awaited
When confirmation is required, the document can only be written after the decision is made
⛔ The review results and principle verification table are written into the "Design Review" section of the document and must not be mixed into the confirmation interface

Incremental Design Constraints

Before incremental design, impact analysis + backward compatibility assessment + change scope classification must be performed

For the criteria checklist on impact identification, breaking change marking, ADR generation, affected document scanning, etc., see references/incremental-design.md; this section does not mirror it.

Skill Collaboration

Scenario	Collaborating Skill	Description
New feature design change	`/feature`	New features trigger incremental design
Optimization suggestion design change	`/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 a professional external UI/UX Skill
Interface status inventory	`/codebase-insight`	Extract the list of public interfaces in the existing code for reference during design

Sub-Agent Summary Format

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

skill: system-design
status: success | failed | partial
summary:
  headline: "初始设计完成，2 模块 2 接口"
  details:
    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: []
blockers: []
output_files:
  - docs/devdocs/02-system-design.md
new_ids: {}
next_recommended:
  skill: test-cases

Next Steps

After initial design

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

After incremental design

If there are new feature points → run /test-cases to supplement test cases
If there are data model changes → record the migration plan in the design document; the actual script is executed by /dev-workflow to execute
If there are breaking changes → mark the scope of impact and migration strategy in the design document

Tip: when document changes are significant, it is recommended to run /agent-memory to sync the memory file.