系统设计
基于需求文档创建或更新系统设计文档，支持初始设计和增量设计两种模式。
语言规则
- 支持中英文提问
- 统一中文回复
- 使用中文生成文档
触发条件
初始设计模式
- 用户已完成需求文档，项目无系统设计
- 用户要求系统/技术设计
- 用户需要架构或 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 模式 → 生成 docs/devdocs/02-system-design.md 文档
│
▼
7. 验证覆盖 → 检查所有 F-XXX 都有对应模块/接口
│
▼
8. 用户确认 → 获得批准后定稿增量设计流程
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 模式规范
在分析完成、写入文档前，必须使用 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
约束
阶段边界约束（最高优先级）
- 本 Skill 仅产出文档，严禁编写或生成任何实现代码（源代码、脚本、配置变更）
- Write 工具仅用于写入
docs/devdocs/下的 Markdown 文档 - "核心接口"章节仅定义签名，严禁包含实现逻辑
- 退出 Plan 模式后，更新设计文档（非代码实现）
- 编码实现由
/devdocs-dev-workflow负责，本 Skill 不涉及
基础约束
- 必须先询问用户技术栈偏好和目标平台
- 技术选型必须说明理由
- 如用户无偏好，根据需求选择最优方案
- 必须指定目标平台和最低版本要求
- API 设计必须包含请求/响应示例
- 数据模型必须考虑索引和查询模式
- 必须识别与现有系统的集成点
- 优先使用项目现有技术栈
MTE 原则约束
- 每个模块职责单一，不超过一个变化原因
- 核心业务逻辑必须可单元测试（无外部依赖或依赖可 Mock，详见
/testing-guide） - 预留合理扩展点，但不为假设需求设计
- 依赖方向：外层依赖内层，内层不依赖外层
- 接口优于实现：依赖抽象，不依赖具体实现
设计模式约束
- 只在解决实际问题时使用设计模式，不为使用而使用
- 使用的设计模式必须说明解决什么问题
- 优先选择简单方案，复杂方案需要说明理由
- 相同问题在项目中使用一致的模式
避免过度设计
- 不为"未来可能"的需求设计，只为当前需求设计
- 不创建只有一个实现的接口（除非为了可测试性）
- 不过早抽象，等到有 3 个以上相似场景再抽象
- 配置优于硬编码，但不为所有内容添加配置
安全约束
- 敏感数据（密码、Token）不明文存储
- 需要认证的 API 已标注
- 用户输入有验证（防注入）
- 敏感操作有日志记录
外部研究约束
- 涉及不熟悉技术且有外部检索工具时，应在 Plan 模式前完成外部研究；无外部工具时，基于现有代码模式扫描和用户输入进行研究
- 研究结论必须写入设计文档，不仅存在于对话中
- 已有技术栈或简单需求可跳过研究
--fast模式跳过研究步骤
Plan 模式约束
- 初始设计：读取需求 + 询问偏好 + 探索代码（+ 外部研究）后，必须进入 Plan 模式
- 增量设计：影响分析 + 兼容性评估后，必须进入 Plan 模式
- Plan 必须包含技术选型理由（初始）或影响范围（增量）
- 用户审批 Plan 后才能写入文档
- 用户要求调整时，更新 Plan 后重新审批
增量设计约束
- 增量设计前必须进行影响分析
- 必须评估向后兼容性
- 破坏性变更必须标注处理方式
- 必须生成设计变更记录
- 新增内容必须标注关联需求（F-XXX / INS-XXX）
- 修改现有接口必须说明兼容性
- 数据模型变更必须说明迁移方案
- 增量设计必须先进行变更范围分类
- 涉及模块接口或架构的变更必须使用变更对比格式
- 必须自动扫描受影响文档并列出更新清单
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 同步记忆文件。