系统设计

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

语言规则

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

触发条件

初始设计模式

• 用户已完成需求文档，项目无系统设计
• 用户要求系统/技术设计
• 用户需要架构或 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 模式之前进行外部研究（依赖可用的外部检索工具）。

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

研究三步骤：

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

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

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

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

设计前必问

必须使用 AskUserQuestion 询问用户：

1. 技术栈偏好

   • 是否有偏好的技术栈？
   • 选项：指定技术栈 / 无偏好（将根据需求推荐）

2. 目标平台

   • 目标平台是什么？
   • 选项：Web / Mobile (iOS/Android) / Desktop / Server / 跨平台

3. 部署环境

   • 部署在哪里？
   • 选项：云服务 (AWS/GCP/Azure) / 私有化 / 混合

4. 现有系统集成

   • 是否需要与现有系统集成？
   • 选项：否 / 是（指定系统、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 图、索引策略

拆分内容分配：

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

设计原则

MTE 原则

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

设计模式选择

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

设计层次

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

文档结构

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

详细参考

• 核心接口设计：只定义签名不写实现，标注关联 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 后重新审批

增量设计约束

• 增量设计前必须进行影响分析
• 必须评估向后兼容性
• 破坏性变更必须标注处理方式
• 必须生成设计变更记录
• 新增内容必须标注关联需求（F-XXX / INS-XXX）
• 修改现有接口必须说明兼容性
• 数据模型变更必须说明迁移方案
• 增量设计必须先进行变更范围分类
• 涉及模块接口或架构的变更必须使用变更对比格式
• 必须自动扫描受影响文档并列出更新清单

Skill 协作

子 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 进入测试用例设计阶段。

增量设计后

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

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