القائمة
需求澄清。只负责明确"要解决什么问题"，生成 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 | 每步结束后实时更新对应章节 |