用途
speckit-clarify 用于在功能规格进入计划阶段之前,检测并减少当前功能规格中的歧义或缺失决策点。它的目标是把澄清结果直接记录到规格文件中,以降低后续返工风险。该工作流预期在调用 /speckit-plan 之前运行;若用户明确表示跳过澄清(例如探索性 spike),可以继续,但需要提示下游返工风险会增加。
主要能力
该技能按结构化分类法扫描规格的歧义与覆盖情况,包括功能范围与行为、领域与数据模型、交互与 UX 流程、非功能质量属性、集成与外部依赖、边界情况与失败处理、约束与权衡、术语与一致性、完成信号以及杂项占位符等。每个类别标记为 Clear、Partial 或 Missing,并据此生成候选问题。
问题总数最多 5 个,每次只呈现一个问题。问题形式限定为 2–5 个互斥选项的多选题,或不超过 5 个词的短答案。对于多选题,会给出推荐选项及简要理由,并以 Markdown 表格展示全部选项;对于短答案题,会给出建议答案与格式说明。用户可以用选项字母、"yes"/"recommended"/"suggested" 接受建议,或给出自己的简短答案。
每个被接受的答案会立即增量集成到规格中:功能歧义更新功能需求;用户交互或角色区分更新用户故事或角色小节;数据形状或实体更新数据模型;非功能约束更新成功标准中的可度量结果;边界情况或负向流程加入边界情况/错误处理;术语冲突则统一规范术语。每次集成后保存规格文件,并校验澄清会话中每个接受答案恰好对应一条记录、总问题数不超过 5、无遗留模糊占位符、无矛盾陈述、Markdown 结构有效且术语一致。
使用方式
该技能以斜杠命令形式使用,并接受用户输入参数($ARGUMENTS)作为优先级上下文。执行前会检查项目根目录下的 .specify/extensions.yml 是否存在,并读取 hooks.before_clarify 下的扩展钩子;若 YAML 无法解析或无效则静默跳过。启用的钩子会被执行或提示执行,命令名中的点号会替换为连字符,例如 speckit.git.commit 转为 /speckit-git-commit。
执行时会从仓库根目录运行 .specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly,解析 FEATURE_DIR 与 FEATURE_SPEC 等字段;若 JSON 解析失败则中止并提示重新运行 /speckit-specify 或检查功能分支环境。若存在 .specify/memory/constitution.md,会加载项目原则与治理约束。
若规格文件缺失,会提示用户先运行 /speckit-specify,不会在此创建新规格。提问过程中,若所有关键歧义已提前解决、用户表示完成(如 "done"、"good"、"no more")或已达到 5 个问题,则停止提问。若一开始没有有效问题,会立即报告未发现关键歧义。
适用场景
适合在功能规格撰写完成后、进入计划或任务分解之前使用,用于补齐影响架构、数据建模、任务拆分、测试设计、UX 行为、运维就绪或合规验证的关键决策。也适合需要把澄清结果持久化到规格文件并保持术语一致的团队流程。
限制
每次会话最多提出 5 个问题;不会提前透露后续问题。排除已回答的问题、琐碎风格偏好以及计划层面的执行细节(除非阻塞正确性)。除非缺失会阻碍功能清晰性,否则避免推测性技术栈问题。若配额用尽仍有高影响类别未解决,会在 Deferred 中明确标注原因。执行后还会检查 hooks.after_clarify 下的强制或可选钩子,并在完成报告中汇报提问数量、更新规格路径、涉及章节、规格质量清单状态(若存在 FEATURE_DIR/checklists/requirements.md)以及覆盖摘要。