菜单
需求澄清。只负责明确"要解决什么问题"，生成 spec.md 的前三章节（背景、目标、需求）。禁止在本阶段讨论设计方案——设计是 workflow-system-design skill 的职责。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
代码文件修改的统一入口。当用户请求任何代码变更（新功能、优化、Bug 修复、重构）时必须首先调用此 skill。仅适用于代码文件（如 .cc/.cpp/.h/.go/.py 等），修改 .md 等非代码文件时不需要调用。它会评估复杂度、检查 spec.md、生成 tasks.md、并逐个任务执行。
测试生成。基于 spec.md 或被测代码，生成单元测试、集成测试、性能测试。当用户请求生成测试、TDD 模式、或 workflow-code-generation 完成后触发。
将纠错经验沉淀为持久化的 Rules/Skills 更新，构建反馈闭环。当被用户纠正且错误具有模式性时自动触发，或通过 /reflect 命令手动触发回顾。
问题排查。当用户遇到编译错误、运行时异常、单测失败、流水线报错、现网告警等需要定位问题时触发。
代码评审。协调 5 个专项 reviewer subagent 对代码进行并行多维度审查。可由用户直接触发，也可由主 agent 加载后作为 Judge 执行。
系统设计。当 spec.md 前三章节（背景、目标、需求）已完整但设计章节为空时调用。按 spec.md 章节顺序逐个与用户讨论，每轮只处理一个 section。
| name | workflow-requirements-clarification |
| description | 需求澄清。只负责明确"要解决什么问题"，生成 spec.md 的前三章节（背景、目标、需求）。禁止在本阶段讨论设计方案——设计是 workflow-system-design skill 的职责。 |
AI 负责调研代码背景，用户负责提供需求信息。
AI 自己调研（读代码）：
向用户询问：
规则：如果信息可以从 codebase 获取，AI 必须自己调研，不问用户。
向用户询问需求信息时，采用苏格拉底式提问——刨根问底，理解问题本质：
| 技巧 | 说明 | 示例 |
|---|---|---|
| 追问 Why | 不接受表面答案，追问到问题本质 | 用户："加个缓存" → AI："为什么需要缓存？慢到什么程度？目标是多少？" |
| 指出矛盾 | 发现用户表述中的矛盾时，引导用户澄清 | 用户："要高并发，但不能改接口" → AI："异步化会改变接口语义，这两个目标是否冲突？" |
| 揭示遗漏 | 引导用户思考未考虑的场景 | AI："你考虑过 X 失败的情况吗？" |
bp-distributed-systems 等）spec.md 不存在或需求章节为空| AI 应该做 | AI 不应该做 |
|---|---|
| 提问，追问 Why | 未经请求就给答案 |
| 指出矛盾或遗漏 | 未追问清楚就生成内容 |
| 质疑不清晰的表述 | 跳过追问直接给建议 |
| 用户请求时生成内容 | 生成后不询问用户意见 |
1. 说明当前阶段和目标
2. 提出一个开放式问题（让用户思考）
3. 等待用户回答
4. 评估用户回答：
- 清晰完整 → 复述确认，进入下一问题
- 模糊 → 追问具体含义
- 有矛盾 → 指出矛盾
- 有遗漏 → 引导思考
5. 用户澄清后，再次确认
| 复杂度 | 信号 | 处理方式 |
|---|---|---|
| 简单 | bug fix、配置调整、单点修改 | 不创建 spec，1-2 轮对话后直接进入 code-generation |
| 中等 | 涉及多文件、单模块功能 | 创建 spec |
| 复杂 | 跨模块、新特性、架构变更 | 创建 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。
目标：理解现有实现，不询问用户
AI 操作：
codebase-researcher subagent 深度调研相关代码（模块结构、接口、依赖关系、数据流）向用户汇报（必须）：
我先调研了一下相关代码：
**相关模块**：
- [文件路径1]: [职责说明]
- [文件路径2]: [职责说明]
**现有实现**：
[概述当前的实现方式、数据流、关键接口]
**技术约束**：
- [约束1，如使用的框架、协议]
- [约束2，如已有的接口规范]
请确认我的理解是否正确？有遗漏或错误的地方吗？
结束条件：用户确认理解正确。必须等用户确认后才能进入 Step 2。
实时更新 spec：用户确认后，更新 spec.md 的 1.2 现状分析 和 1.3 主要使用场景。
目标：让用户说清楚"要解决什么问题"
开场白：
请描述一下：**现在遇到了什么问题？这个问题带来了什么影响？**
追问方向：
结束条件：用户能清晰回答"要解决什么问题"，AI 复述确认无误。
实时更新 spec：确认后，更新 spec.md 的 1.1 问题描述。
目标：让用户定义"成功标准"和"不做什么"
开场白：
好的，问题我理解了。
接下来请你想一下：
- **这次的目标是什么？怎么算做完了？**
- **有什么是明确不做的？**
追问方向：
结束条件：用户给出明确、可衡量的目标和边界。
实时更新 spec：确认后，更新 spec.md 的 2. 目标 和 2.1 非目标。
目标：让用户说清楚"具体要做哪些功能来达成目标"
开场白：
目标明确了。
接下来请你描述一下：**具体需要哪些功能来达成这个目标？**
追问方向：
结束条件：用户给出具体的功能列表，AI 复述确认无误。
实时更新 spec：确认后，更新 spec.md 的 3.1 功能性需求。
目标：引导用户思考隐藏的约束条件
分布式系统场景：如果需求涉及网络通信、多节点协调、数据一致性、故障恢复，必须加载
bp-distributed-systemsSkill。
开场白：
最后想请你考虑一下：**有没有隐藏的约束条件？**
比如：性能要求、接口兼容性、升级回滚策略？
非功能性需求 checklist（AI 根据需求场景判断是否相关，相关则询问，并给出具体例子帮助用户理解）：
| 类别 | 何时询问 | 引导问题 | 具体例子 |
|---|---|---|---|
| 性能 | 涉及热路径、数据处理 | 延迟/吞吐量要求？并发量预估？ | "比如：单次请求延迟 < 10ms？支持 1000 QPS？" |
| 可用性 | 涉及关键链路 | SLA 要求？故障降级方案？ | "比如：节点挂了怎么办？还能继续提供服务吗？" |
| 一致性 | 涉及分布式、事务 | 强一致/最终一致？隔离级别？ | "比如：并发写同一行时谁赢？读能看到正在写的数据吗？多个操作需要原子性吗？跨节点读写一致吗？" |
| 兼容性 | 涉及接口、协议变更 | API 是否需向后兼容？ | "比如：新增字段后，旧客户端解析会报错吗？旧版本写入的数据新版本能读吗？" |
| 升级 | 涉及持久化格式变更 | 滚动升级安全吗？需要数据迁移吗？ | "比如：新旧版本混部时数据互通吗？" |
| 回滚 | 有持久化变更 | 能回滚吗？回滚后数据丢失吗？ | "比如：升级失败回滚到旧版本，新写入的数据还在吗？" |
| 安全 | 涉及权限、敏感数据 | 权限控制？数据脱敏？审计日志？ | "比如：谁能调用这个接口？操作需要记录吗？" |
| 可观测 | 新功能、复杂逻辑 | 需要哪些监控指标？告警阈值？ | "比如：需要监控成功率、延迟分布吗？什么情况告警？" |
| 资源 | 涉及大数据量处理 | 内存/CPU/磁盘限制？ | "比如：单次请求最多用多少内存？" |
| 可扩展 | 涉及数据增长 | 数据量增长预期？水平扩展？ | "比如：数据量翻倍时性能会怎样？" |
| 持久性 | 涉及数据存储 | 允许丢数据吗？持久化策略？ | "比如：断电重启后数据还在吗？" |
结束条件：用户确认关键约束，或明确表示"没有其他约束"。
实时更新 spec：确认后，更新 spec.md 的 3.2 非功能性需求。
目标：回顾 spec 前三章节的完整性，确认无遗漏。
操作：
结束语：
spec.md 前三章节已完成：docs/design-docs/<module>/<feature>/spec.md
（已填写：1. 背景、2. 目标、3. 需求）
如果准备好了，说"开始设计"进入 system design 阶段。
docs/design-docs/<module>/<feature>/spec.mdworkflow-system-design skill 负责| ❌ 错误做法 | ✅ 正确做法 |
|---|---|
| 问用户"现有实现是怎样的" | AI 自己读代码调研 |
| 从头创建 spec.md | 必须用 cp 复制模板 |
| 生成到宿主工具私有目录 | 生成到 docs/design-docs/ |
文件名 xxx-spec.md | 文件名必须是 spec.md |
| 填写设计方案章节 | 只填前三章节 |
| 一次问多个问题 | 每轮只问一个核心问题 |
| 所有步骤完成后才写 spec | 每步结束后实时更新对应章节 |