系统设计

基于需求文档创建或更新系统设计文档，支持初始设计和增量设计两种模式。

语言规则

支持中英文提问
统一中文回复
使用中文生成文档

触发条件

初始设计模式

用户已完成需求文档，项目无系统设计
用户要求系统/技术设计
用户需要架构或 API 设计

增量设计模式

新功能加入后需要设计变更（来自 /devdocs-feature）
优化建议确认后需要设计调整（来自 /devdocs-insights）
技术改进需要架构调整
用户要求更新/修改现有设计

前置条件

需求文档：docs/devdocs/01-requirements.md
如不存在，建议先运行 /devdocs-requirements

设计模式检测

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

运行模式

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

`--fast` 模式

跳过 EnterPlanMode 步骤和技术栈偏好询问
使用合理默认值（根据代码库推断技术栈）
仅保留最终写入前的 1 次确认
默认行为不变，--fast 是 opt-in

工作流程

初始设计流程

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

增量设计流程

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

Plan 模式规范

在分析完成、写入文档前，必须使用 EnterPlanMode 呈现设计方案草案，等用户审批后再执行。

初始设计 Plan 内容

## 设计方案草案

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

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

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

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

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

增量设计 Plan 内容

## 变更方案草案

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

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

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

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

Plan 模式时机

模式	进入时机	Plan 内容
初始设计	读取需求 + 询问偏好 + 探索代码后	技术选型、架构方向、模块划分
增量设计	影响分析 + 兼容性评估后	影响范围、变更策略、迁移方案

设计前外部研究

当需求涉及不熟悉的技术/框架或复杂集成时，应在 Plan 模式之前进行外部研究（依赖可用的外部检索工具）。

触发条件：项目未使用过的技术、复杂第三方集成、存在多种可行方案需对比。

研究三步骤：

现有代码模式扫描 — 扫描项目架构和 docs/devdocs/patterns/ 已有经验，确认兼容性。必须检索 patterns/ 目录：扫描标题列表，匹配当前设计需求的关键词，如命中则读取详情作为设计参考（避免重复踩坑、复用已验证方案）
官方文档确认（若有外部检索工具可用）— 查阅官方文档确认 API 可用性、版本兼容性、已知限制（可用 context7 MCP）
最佳实践摘要（若有外部检索工具可用）— 搜索社区最佳实践和常见陷阱，对比方案优劣

研究结论必须写入设计文档（"技术选型"章节），格式：

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

跳过条件：使用项目已有技术栈、需求简单方案明确、--fast 模式。

设计前必问

必须使用 AskUserQuestion 询问用户：

技术栈偏好
- 是否有偏好的技术栈？
- 选项：指定技术栈 / 无偏好（将根据需求推荐）
目标平台
- 目标平台是什么？
- 选项：Web / Mobile (iOS/Android) / Desktop / Server / 跨平台
部署环境
- 部署在哪里？
- 选项：云服务 (AWS/GCP/Azure) / 私有化 / 混合
现有系统集成
- 是否需要与现有系统集成？
- 选项：否 / 是（指定系统、API、数据库）

如用户无偏好，则根据需求设计最优方案。

增量设计

增量设计遵循三步流程：变更范围分类 → 影响分析 → 兼容性评估，然后执行变更并生成 ADR 记录。

变更范围分为三级：仅内部实现（轻量分析）、涉及模块接口（标准分析）、涉及架构（完整分析 + ADR）
影响分析需覆盖受影响的模块、接口、数据模型，并自动扫描关联文档
兼容性评估判断向后兼容性，破坏性变更须标注废弃周期和迁移方案
每个变更项使用统一的变更对比格式（变更前/变更后/原因/影响范围）

进入增量设计模式时，必须读取 incremental-design.md 获取影响分析、兼容性评估、变更对比格式和检查清单。

输出文件

主文件：docs/devdocs/02-system-design.md

文档拆分规则

当满足以下条件时，应拆分文档：

文档超过 300 行
模块数量超过 5 个
API 接口超过 10 个

拆分方式：

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

拆分内容分配：

文件	包含章节
02-system-design.md	1-7: 平台、架构、技术选型、模块、接口签名、模式、代码结构
02-system-design-api.md	9-10: 完整 API 设计、状态流转
02-system-design-data.md	8, 11-13: 数据模型、异常处理、扩展性、需求追溯

详细模板参见 templates/design-template.md。

设计原则

MTE 原则

系统设计必须遵循 MTE 原则：

原则	说明	检查点
Maintainability	可维护性	模块职责单一、依赖清晰、易于理解和修改
Testability	可测试性	核心逻辑可单元测试、依赖可 Mock、边界清晰（参考 `/testing-guide`）
Extensibility	可扩展性	预留扩展点、接口抽象、开闭原则

设计模式选择

根据场景选择合适的设计模式，只在必要时使用：

场景	推荐模式	适用情况
对象创建	Factory / Builder	复杂对象构建、多种类型创建
行为扩展	Strategy / Template	算法可替换、流程固定步骤可变
结构组织	Facade / Adapter	简化复杂接口、适配第三方库
状态管理	State / Observer	状态驱动行为、事件通知
数据访问	Repository / DAO	数据层抽象、查询封装

设计层次

接口层（薄层）→ 服务层（核心业务逻辑）→ 领域层（实体/值对象）→ 基础设施层（数据访问/外部服务）

文档结构

目标平台 - 平台、版本要求、部署环境
架构概览 - 高层架构图（Mermaid）
技术选型 - 技术选择及理由
模块设计 - 模块职责与依赖，标注关联功能点 (F-XXX)
核心接口 - 面向接口 (仅签名): 关键接口和方法签名（严禁包含具体实现逻辑），标注关联 F-XXX
设计模式 - 应用的模式及理由
代码结构 - 目录结构设计
数据模型 - 实体定义与关系
API 设计 - 接口端点及请求/响应示例，标注关联 F-XXX, AC-XXX
状态流转 - 关键业务流程的状态机
异常处理 - 错误码与处理策略
日志设计 - 日志级别、关键日志点、追溯 ID
扩展性 - 扩展点与未来考量
需求追溯 - 功能点与模块/接口的映射关系，覆盖检查清单

详细参考

核心接口设计：只定义签名不写实现，标注关联 F-XXX → templates/design-template.md
代码结构设计：按分层架构组织目录结构 → templates/design-template.md
日志设计：级别、关键日志点、格式、追溯 ID → templates/log-design-guide.md

约束

基础约束

必须先询问用户技术栈偏好和目标平台
技术选型必须说明理由
如用户无偏好，根据需求选择最优方案
必须指定目标平台和最低版本要求
API 设计必须包含请求/响应示例
数据模型必须考虑索引和查询模式
必须识别与现有系统的集成点
优先使用项目现有技术栈

MTE 原则约束

每个模块职责单一，不超过一个变化原因
核心业务逻辑必须可单元测试（无外部依赖或依赖可 Mock，详见 /testing-guide）
预留合理扩展点，但不为假设需求设计
依赖方向：外层依赖内层，内层不依赖外层
接口优于实现：依赖抽象，不依赖具体实现

设计模式约束

只在解决实际问题时使用设计模式，不为使用而使用
使用的设计模式必须说明解决什么问题
优先选择简单方案，复杂方案需要说明理由
相同问题在项目中使用一致的模式

避免过度设计

不为"未来可能"的需求设计，只为当前需求设计
不创建只有一个实现的接口（除非为了可测试性）
不过早抽象，等到有 3 个以上相似场景再抽象
配置优于硬编码，但不为所有内容添加配置

安全约束

敏感数据（密码、Token）不明文存储
需要认证的 API 已标注
用户输入有验证（防注入）
敏感操作有日志记录

外部研究约束

涉及不熟悉技术且有外部检索工具时，应在 Plan 模式前完成外部研究；无外部工具时，基于现有代码模式扫描和用户输入进行研究
研究结论必须写入设计文档，不仅存在于对话中
已有技术栈或简单需求可跳过研究
--fast 模式跳过研究步骤

Plan 模式约束

初始设计：读取需求 + 询问偏好 + 探索代码（+ 外部研究）后，必须进入 Plan 模式
增量设计：影响分析 + 兼容性评估后，必须进入 Plan 模式
Plan 必须包含技术选型理由（初始）或影响范围（增量）
用户审批 Plan 后才能写入文档
用户要求调整时，更新 Plan 后重新审批

增量设计约束

Skill 协作

场景	协作 Skill	说明
新功能设计变更	`/devdocs-feature`	新功能触发增量设计
优化建议设计变更	`/devdocs-insights`	洞察确认后触发增量设计
可测试性设计	`/testing-guide`	确保核心逻辑可单元测试
代码质量	`/code-quality`	MTE 原则指导设计
UI 架构	`/ui-orchestrator`	路由到专业的外部 UI/UX Skill
接口自动提取	`/devdocs-retrofit`	从现有代码逆向提取接口定义并同步到设计文档

子 Agent 摘要格式

当本 Skill 作为子 Agent 运行时，返回以下结构化摘要：

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

下一步

初始设计后

用户确认系统设计后，建议运行 /devdocs-test-cases 进入测试用例设计阶段。

增量设计后

如有新增功能点 → 运行 /devdocs-test-cases 补充测试用例
如有数据模型变更 → 准备数据库迁移脚本
如有破坏性变更 → 通知相关依赖方

提示：文档变更较大时，建议运行 /agent-memory 同步记忆文件。

devdocs-system-design