workflow-requirements-clarification

name: workflow-requirements-clarification description: 需求澄清。只负责明确"要解决什么问题"，生成 spec.md 的前三章节（背景、目标、需求）。禁止在本阶段讨论设计方案——设计是 workflow-system-design skill 的职责。

需求澄清

核心定位

AI 负责调研代码背景，用户负责提供需求信息。

AI 职责划分

AI 自己调研（读代码）：

• 现有实现是怎样的
• 代码路径、数据流
• 已有的接口和数据结构
• 技术约束（如使用的框架）
• 相关模块的职责

向用户询问：

• 为什么需要这个功能
• 要解决什么问题
• 具体要做哪些功能
• 目标和成功标准
• 非目标（不做什么）
• 性能/兼容性等非功能需求

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

苏格拉底式提问

向用户询问需求信息时，采用苏格拉底式提问——刨根问底，理解问题本质：

AI 生成内容的前置条件

1. AI 已完成代码调研（理解现状，并向用户确认）
2. AI 已充分追问（理解问题本质）
3. 加载相关规范（如 bp-distributed-systems 等）

触发条件

• 用户描述功能需求但缺乏具体细节
• 用户请求开发新功能
• spec.md 不存在或需求章节为空

对话模式

AI 角色边界

每轮对话结构

1. 说明当前阶段和目标
2. 提出一个开放式问题（让用户思考）
3. 等待用户回答
4. 评估用户回答：
   - 清晰完整 → 复述确认，进入下一问题
   - 模糊 → 追问具体含义
   - 有矛盾 → 指出矛盾
   - 有遗漏 → 引导思考
5. 用户澄清后，再次确认

工作流程

Step 0: 评估复杂度并创建 spec

中等及以上：立即创建目录并复制模板：

mkdir -p docs/design-docs/<module>/<feature>/
cp skills/workflow-requirements-clarification/reference/spec_template.md \
   docs/design-docs/<module>/<feature>/spec.md

路径规则：根据功能所属模块确定。文件名必须是 spec.md。

Step 1: 代码调研（AI 自主完成）

目标：理解现有实现，不询问用户

AI 操作：

1. 调用 codebase-researcher subagent 深度调研相关代码（模块结构、接口、依赖关系、数据流）
2. 识别相关模块、接口、数据结构
3. 生成现状分析摘要

向用户汇报（必须）：

我先调研了一下相关代码：

**相关模块**：
- [文件路径1]: [职责说明]
- [文件路径2]: [职责说明]

**现有实现**：
[概述当前的实现方式、数据流、关键接口]

**技术约束**：
- [约束1，如使用的框架、协议]
- [约束2，如已有的接口规范]

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

结束条件：用户确认理解正确。必须等用户确认后才能进入 Step 2。

实时更新 spec：用户确认后，更新 spec.md 的 1.2 现状分析 和 1.3 主要使用场景。

Step 2: 澄清背景与问题

目标：让用户说清楚"要解决什么问题"

开场白：

请描述一下：**现在遇到了什么问题？这个问题带来了什么影响？**

追问方向：

• "你说的 X 具体是指什么？"
• "影响范围有多大？有数据吗？"
• "没有这个功能，现在是怎么解决的？"

结束条件：用户能清晰回答"要解决什么问题"，AI 复述确认无误。

实时更新 spec：确认后，更新 spec.md 的 1.1 问题描述。

Step 3: 明确目标与边界

目标：让用户定义"成功标准"和"不做什么"

开场白：

好的，问题我理解了。

接下来请你想一下：
- **这次的目标是什么？怎么算做完了？**
- **有什么是明确不做的？**

追问方向：

• "你说'性能要好'，具体是多少？怎么测量？"
• "这几个目标的优先级是什么？"
• "如果时间不够，哪些可以不做？"

结束条件：用户给出明确、可衡量的目标和边界。

实时更新 spec：确认后，更新 spec.md 的 2. 目标 和 2.1 非目标。

Step 4: 明确功能性需求

目标：让用户说清楚"具体要做哪些功能来达成目标"

开场白：

目标明确了。

接下来请你描述一下：**具体需要哪些功能来达成这个目标？**

追问方向：

• "这个功能的输入是什么？输出是什么？"
• "有哪些操作/场景需要支持？"
• "用户/调用方会怎么使用这个功能？"

结束条件：用户给出具体的功能列表，AI 复述确认无误。

实时更新 spec：确认后，更新 spec.md 的 3.1 功能性需求。

Step 5: 确认非功能性需求

目标：引导用户思考隐藏的约束条件

分布式系统场景：如果需求涉及网络通信、多节点协调、数据一致性、故障恢复，必须加载 bp-distributed-systems Skill。

开场白：

最后想请你考虑一下：**有没有隐藏的约束条件？**

比如：性能要求、接口兼容性、升级回滚策略？

非功能性需求 checklist（AI 根据需求场景判断是否相关，相关则询问，并给出具体例子帮助用户理解）：

结束条件：用户确认关键约束，或明确表示"没有其他约束"。

实时更新 spec：确认后，更新 spec.md 的 3.2 非功能性需求。

Step 6: 最终确认

目标：回顾 spec 前三章节的完整性，确认无遗漏。

操作：

1. 读取 spec.md 前三章节内容
2. 向用户展示摘要，确认无需补充或修改
3. 如有修改，更新对应章节内容

结束语：

spec.md 前三章节已完成：docs/design-docs/<module>/<feature>/spec.md
（已填写：1. 背景、2. 目标、3. 需求）

如果准备好了，说"开始设计"进入 system design 阶段。

强制规则

1. AI 自主调研代码背景：现有实现、代码路径等信息 AI 必须自己读代码获取
2. 只问用户需求信息：为什么做、做什么、不做什么、约束条件
3. 只填前三章节：spec.md 只填写 1. 背景、2. 目标、3. 需求
4. 正确的文件路径：docs/design-docs/<module>/<feature>/spec.md
5. 禁止生成后续章节：设计方案由 workflow-system-design skill 负责
6. 必须使用 cp 复制模板：禁止从头创建 spec.md
7. 实时更新 spec：每个步骤结束后立即更新对应章节，不要等到最后一次性写入

反模式

参考资料

• 完整 spec 模板