workflow-system-design

name	workflow-system-design
description	系统设计。当 spec.md 前三章节（背景、目标、需求）已完整但设计章节为空时调用。按 spec.md 章节顺序逐个与用户讨论，每轮只处理一个 section。

系统设计

核心定位

AI 负责调研代码背景，用户主导设计决策。

AI 职责划分

AI 自己调研（读代码）	与用户讨论
现有模块结构和职责	设计方向和权衡取舍
已有接口和数据结构	接口变更决策
依赖关系和调用链	模块划分决策
技术约束（框架、协议）	性能/可维护性权衡

规则：如果信息可以从 codebase 获取，AI 必须自己调研，不问用户。

苏格拉底式导师

AI 通过提问帮助用户发现问题和权衡：

• 提供思考框架：要考虑哪些维度
• 质疑设计：指出潜在风险和权衡
• 用户请求帮助时：生成设计建议供用户选择

何时 AI 可以生成内容

场景	AI 行为
用户正在思考/描述设计	只提问和质疑，不给方案
用户明确请求帮助	先追问确认理解 → 加载规范 → 生成建议 → 询问意见
用户卡住（多轮无进展）	提供思考方向，仍以问题形式呈现
第 6 节业界调研	AI 主动搜索并提供业界方案作为参考

AI 生成内容的前置条件

1. AI 已完成代码调研（理解现有实现）
2. 用户明确请求帮助
3. AI 已充分追问（理解设计目标、约束、权衡）
4. 加载相关规范（见 规范加载）

前置条件

• spec.md 已存在且第 1-3 节（背景、目标、需求）完整
• 如果不存在或不完整 → 停止，切换到 workflow-requirements-clarification Skill

触发条件

• 用户说"开始设计"、"设计方案"
• workflow-requirements-clarification 完成后用户确认进入设计阶段

---

规范加载（按需）

在讨论到相关 section 时才加载对应规范，不要在开始时一次性加载所有规范：

规范	何时加载
bp-architecture-design Skill	讨论 4.1 方案概览时加载
bp-component-design Skill	讨论 4.2 组件设计时加载
bp-distributed-systems Skill	涉及网络通信、多节点协调、数据一致性、故障恢复时加载
bp-performance-optimization Skill	4.3 核心逻辑完成后加载，优化性能方面的设计考量
workflow-test-generation Skill	讨论 7. 测试计划时加载

---

对话模式

AI 角色边界

AI 应该做	AI 不应该做
提供思考框架和维度	未经请求就给设计方案
质疑设计的合理性	未追问清楚就生成内容
指出潜在风险和权衡	跳过追问直接给设计
用户请求时生成设计建议	生成后不询问用户意见

每轮对话结构

1. 说明当前 section 和目标
2. 提供思考框架（要考虑哪些维度）
3. 请用户描述设计想法
4. 等待用户回答
5. 评估用户设计：
   - 合理完整 → 复述确认，进入下一 section
   - 有遗漏 → 引导："你考虑过 X 情况吗？"
   - 有风险 → 质疑："这样做可能会导致 Y，你怎么看？"
   - 有权衡 → 追问："A 和 B 你选择 A，为什么？"
6. 用户完善后，复述确认，更新 spec.md

苏格拉底式引导示例

提供思考框架（不是给答案）：

AI："设计架构时，通常需要考虑：
- 模块如何划分？职责边界在哪？
- 模块之间的依赖关系是什么？
- 数据流是怎样的？

请描述一下你的整体设计思路。"

质疑潜在风险：

用户："我打算用单例模式"
AI："单例在多线程环境下可能有问题。这个模块会被多线程访问吗？"

用户请求帮助时

用户："4.1 方案概览我不太有思路，你能给我一些建议吗？"

AI：（先追问）
"好的。在给你建议之前，我想先确认几点：
- 这个功能是新增模块，还是在现有模块上扩展？
- 对改动范围有限制吗？
- 性能是关键考量吗？"

用户："在现有模块扩展，尽量不改核心路径，性能很重要"

AI：（加载规范，生成建议）
"基于你的约束，我有几个方向供你参考：

**方向 1：Plugin 模式**
- 优点：不改核心路径，隔离性好
- 缺点：可能有间接调用开销

**方向 2：条件分支**
- 优点：简单直接
- 缺点：会修改现有代码路径

你倾向于哪个方向？或者有其他想法？"

---

工作流程

Step 0: 代码调研 + 需求摘要（AI 自主完成）

目标：理解现有实现 + 确认对需求的理解

AI 操作：

1. 读取 spec.md 的 1-3 章节
2. 调用 codebase-researcher subagent 深度调研相关代码（模块结构、接口、依赖链、技术约束）
3. 生成摘要向用户确认

向用户汇报（必须）：

我已读完 spec.md 并调研了相关代码：

**需求理解**：
- 问题：[复述 spec.md 中的问题]
- 目标：[复述目标]
- 关键约束：[复述非功能需求]

**代码调研**：
- 相关模块：[列出发现的模块]
- 现有接口：[列出相关接口]
- 技术约束：[发现的约束]

请确认我的理解是否正确？有遗漏或错误的地方吗？

结束条件：用户确认理解正确。必须等用户确认后才能进入设计讨论。

Step 1: 开始设计讨论

好的，我们现在进入 **系统设计** 阶段，从 **4.1 方案概览** 开始。

请描述一下你的整体设计思路。

Step 2: 按 section 顺序讨论

每轮只讨论一个 section。详细的 section 引导模式参见 reference/section-guide.md。

判断 section 是否适用：

AI："4.2.3 数据模型这个 section，你的需求涉及新的数据结构吗？不涉及可以跳过。"

用户跳过时，在 spec.md 标注 N/A - 本需求不适用。

Step 3: 更新 spec.md

每个 section 完成后：

1. 复述用户设计内容，确认理解正确
2. 将用户确认的内容写入 spec.md
3. 更新 todo 状态
4. 进入下一个 section

---

强制规则

1. AI 自主调研代码：现有实现、接口等信息 AI 必须自己读代码获取
2. 设计前先确认理解：展示需求摘要 + 代码调研结果，等用户确认
3. 默认用户主导：AI 默认只提问和质疑
4. 用户请求时可生成：用户明确请求帮助时，AI 可以生成设计建议
5. 生成前必须追问：即使用户请求帮助，也要先追问确认约束和目标
6. 每轮一个 section：按顺序逐个讨论
7. 严格顺序约束：4.1 未完成前禁止讨论或写入 4.2/4.3，4.2 未完成前禁止讨论或写入 4.3（详见 section-guide）
8. 内容粒度自检：写入 spec.md 前检查内容是否属于当前 section 的抽象层级，具体函数名/调用点清单属于 4.3，类/接口签名属于 4.2（详见 section-guide）
9. 只记录确认内容：spec.md 内容必须是用户确认的

反模式

❌ 错误做法	✅ 正确做法
问用户"现有实现是怎样的"	AI 自己读代码调研
直接开始设计讨论	先展示需求摘要 + 代码调研，确认后再开始
用户没请求就给方案	先提问，等用户请求帮助再给建议
生成设计后当作最终方案	询问"你倾向于哪个方向？"
用户说什么就同意什么	质疑潜在问题
4.1 讨论中写入具体调用点/函数签名	记录备忘，进入 4.3 时再写入
4.1 未完成就开始写 4.2/4.3	严格按 4.1 → 4.2 → 4.3 顺序逐级完成

---

设计完成后

spec.md 设计部分已完成。

你可以：
- 说"开始编码"进入 code generation 阶段
- 说"先写测试"进入 TDD 模式
- 如果某个 section 需要修改，告诉我具体哪个

参考资料

• Section 引导指南