workflow-requirements-clarification

name workflow-requirements-clarification description 需求澄清。只负责明确"要解决什么问题"，生成 spec.md 的前三章节（背景、目标、需求）。禁止在本阶段讨论设计方案——设计是 workflow-system-design skill 的职责。 需求澄清 核心定位 AI 负责调研代码背景，用户负责提供需求信息。 AI 职责划分 AI 自己调研（读代码） ： 现有实现是怎样的 代码路径、数据流 已有的接口和数据结构 技术约束（如使用的框架） 相关模块的职责 向用户询问 ： 为什么需要这个功能 要解决什么问题 具体要做哪些功能 目标和成功标准 非目标（不做什么） 性能/兼容性等非功能需求 规则 ：如果信息可以从 codebase 获取， AI 必须自己调研 ，不问用户。 苏格拉底式提问 向用户询问需求信息时，采用 苏格拉底式提问 ——刨根问底，理解问题本质： 技巧 说明 示例 追问 Why 不接受表面答案，追问到问题本质 用户："加个缓存" → AI："为什么需要缓存？慢到什么程度？目标是多少？" 指出矛盾 发现用户表述中的矛盾时，引导用户澄清 用户："要高并发，但不能改接口" → AI："异步化会改变接口语义，这两个目标是否冲突？" 揭示遗漏 引导用户思考未考虑的场景 AI："你考虑过 X 失败的情况吗？" AI 生成内容的前置条件 AI 已完成代码调研 （理解现状，并向用户确认） AI 已充分追问 （理解问题本质） 加载相关规范 （如 bp-distributed-systems 等） 触发条件 用户描述功能需求但缺乏具体细节 用户请求开发新功能 spec.md 不存在或需求章节为空 对话模式 AI 角色边界 AI 应该做 AI 不应该做 提问，追问 Why 未经请求就给答案 指出矛盾或遗漏 未追问清楚就生成内容 质疑不清晰的表述 跳过追问直接给建议 用户请求时 生成内容 生成后不询问用户意见 每轮对话结构 1. 说明当前阶段和目标 2. 提出一个开放式问题（让用户思考） 3. 等待用户回答 4. 评估用户回答： - 清晰完整 → 复述确认，进入下一问题 - 模糊 → 追问具体含义 - 有矛盾 → 指出矛盾 - 有遗漏 → 引导思考 5. 用户澄清后，再次确认 工作流程 Step 0: 评估复杂度并创建 spec 复杂度 信号 处理方式 简单 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 。 Step 1: 代码调研（AI 自主完成） 目标 ：理解现有实现，不询问用户 AI 操作 ： 调用 codebase-researcher subagent 深度调研相关代码（模块结构、接口、依赖关系、数据流） 识别相关模块、接口、数据结构 生成现状分析摘要 向用户汇报（必须） ： 我先调研了一下相关代码： **相关模块**： - [文件路径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 根据需求场景判断是否相关，相关则询问，并给出具体例子帮助用户理解）： 类别 何时询问 引导问题 具体例子 性能 涉及热路径、数据处理 延迟/吞吐量要求？并发量预估？ "比如：单次请求延迟 < 10ms？支持 1000 QPS？" 可用性 涉及关键链路 SLA 要求？故障降级方案？ "比如：节点挂了怎么办？还能继续提供服务吗？" 一致性 涉及分布式、事务 强一致/最终一致？隔离级别？ "比如：并发写同一行时谁赢？读能看到正在写的数据吗？多个操作需要原子性吗？跨节点读写一致吗？" 兼容性 涉及接口、协议变更 API 是否需向后兼容？ "比如：新增字段后，旧客户端解析会报错吗？旧版本写入的数据新版本能读吗？" 升级 涉及持久化格式变更 滚动升级安全吗？需要数据迁移吗？ "比如：新旧版本混部时数据互通吗？" 回滚 有持久化变更 能回滚吗？回滚后数据丢失吗？ "比如：升级失败回滚到旧版本，新写入的数据还在吗？" 安全 涉及权限、敏感数据 权限控制？数据脱敏？审计日志？ "比如：谁能调用这个接口？操作需要记录吗？" 可观测 新功能、复杂逻辑 需要哪些监控指标？告警阈值？ "比如：需要监控成功率、延迟分布吗？什么情况告警？" 资源 涉及大数据量处理 内存/CPU/磁盘限制？ "比如：单次请求最多用多少内存？" 可扩展 涉及数据增长 数据量增长预期？水平扩展？ "比如：数据量翻倍时性能会怎样？" 持久性 涉及数据存储 允许丢数据吗？持久化策略？ "比如：断电重启后数据还在吗？" 结束条件 ：用户确认关键约束，或明确表示"没有其他约束"。 实时更新 spec ：确认后，更新 spec.md 的 3.2 非功能性需求 。 Step 6: 最终确认 目标 ：回顾 spec 前三章节的完整性，确认无遗漏。 操作 ： 读取 spec.md 前三章节内容 向用户展示摘要，确认无需补充或修改 如有修改，更新对应章节内容 结束语 ： spec.md 前三章节已完成：docs/design-docs/<module>/<feature>/spec.md （已填写：1. 背景、2. 目标、3. 需求） 如果准备好了，说"开始设计"进入 system design 阶段。 强制规则 AI 自主调研代码背景 ：现有实现、代码路径等信息 AI 必须自己读代码获取 只问用户需求信息 ：为什么做、做什么、不做什么、约束条件 只填前三章节 ：spec.md 只填写 1. 背景、2. 目标、3. 需求 正确的文件路径 ： docs/design-docs/<module>/<feature>/spec.md 禁止生成后续章节 ：设计方案由 workflow-system-design skill 负责 必须使用 cp 复制模板 ：禁止从头创建 spec.md 实时更新 spec ：每个步骤结束后立即更新对应章节，不要等到最后一次性写入 反模式 ❌ 错误做法 ✅ 正确做法 问用户"现有实现是怎样的" AI 自己读代码调研 从头创建 spec.md 必须用 cp 复制模板 生成到宿主工具私有目录 生成到 docs/design-docs/ 文件名 xxx-spec.md 文件名必须是 spec.md 填写设计方案章节 只填前三章节 一次问多个问题 每轮只问一个核心问题 所有步骤完成后才写 spec 每步结束后实时更新对应章节 参考资料 完整 spec 模板