speckit-clarify

name	speckit-clarify
description	通过提出最多 5 个高度针对性的澄清问题, 识别当前功能规范中未充分说明的领域, 并将答案编码回规范中.
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"templates/commands/clarify.md"}
disable-model-invocation	true

用户输入

$ARGUMENTS

在继续之前, 你必须考虑用户输入(如果不为空).

概述

目标: 检测并减少活跃功能规范中的模糊性或缺失的决策点, 并将澄清内容直接记录在规范文件中.

注意: 此澄清工作流应在调用 /speckit.plan 之前运行(并完成). 如果用户明确表示他们跳过澄清(例如, 探索性原型), 你可以继续, 但必须警告下游返工风险增加.

执行步骤:

1. 从仓库根目录运行 .specify/scripts/bash/check-prerequisites.sh --json --paths-only 一次(组合 --json --paths-only 模式 / -Json -PathsOnly). 解析最小 JSON 负载字段:

   • FEATURE_DIR
   • FEATURE_SPEC
   • (可选捕获 IMPL_PLAN, TASKS 用于未来的链式流程.)
   • 如果 JSON 解析失败, 中止并指示用户重新运行 /speckit.specify 或验证功能分支环境.
   • 对于参数中包含单引号的情况(如 "I'm Groot"), 使用转义语法: 例如 'I'''m Groot'(或优先使用双引号: "I'm Groot").

2. 加载当前规范文件. 使用此分类法执行结构化模糊性和覆盖范围扫描. 对于每个类别, 标记状态: 清晰 / 部分 / 缺失. 生成用于优先级排序的内部覆盖范围图(除非不会提问, 否则不输出原始图).

   功能范围与行为:

   • 核心用户目标和成功标准
   • 明确的超出范围声明
   • 用户角色 / 角色区分

   领域与数据模型:

   • 实体, 属性, 关系
   • 身份和唯一性规则
   • 生命周期 / 状态转换
   • 数据量 / 规模假设

   交互与 UX 流程:

   • 关键用户旅程 / 序列
   • 错误 / 空白 / 加载状态
   • 可访问性或本地化说明

   非功能性质量属性:

   • 性能(延迟, 吞吐量目标)
   • 可扩展性(水平 / 垂直, 限制)
   • 可靠性和可用性(正常运行时间, 恢复期望)
   • 可观察性(日志, 指标, 追踪信号)
   • 安全性和隐私(身份验证 / 授权, 数据保护, 威胁假设)
   • 合规性 / 监管约束(如有)

   集成与外部依赖:

   • 外部服务 / API 和故障模式
   • 数据导入 / 导出格式
   • 协议 / 版本控制假设

   边缘情况与故障处理:

   • 负面场景
   • 速率限制 / 节流
   • 冲突解决(例如, 并发编辑)

   约束与权衡:

   • 技术约束(语言, 存储, 托管)
   • 明确的权衡或被拒绝的替代方案

   术语与一致性:

   • 规范术语表术语
   • 避免的同义词 / 已弃用术语

   完成信号:

   • 验收标准可测试性
   • 可衡量的完成定义风格指标

   其他 / 占位符:

   • TODO 标记 / 未解决的决策
   • 缺少量化的模糊形容词("robust", "intuitive")

   对于每个处于部分或缺失状态的类别, 添加候选问题机会, 除非:

   • 澄清不会实质性地改变实施或验证策略
   • 信息更适合推迟到规划阶段(内部记录)

3. (内部)生成候选澄清问题的优先级队列(最多5个). 不要一次性输出所有问题. 应用这些约束:

   • 整个会话最多5个问题.
   • 每个问题必须可以用以下任一方式回答:
     • 简短的多项选择(2-5个不同的, 互斥的选项), 或
     • 单词 / 短语答案(明确约束: "用 <=5 个词回答").
   • 仅包含答案实质上影响架构, 数据建模, 任务分解, 测试设计, UX 行为, 运营准备或合规性验证的问题.
   • 确保类别覆盖平衡: 尝试首先覆盖最高影响的未解决类别; 避免在单个高影响领域(例如, 安全态势)未解决时询问两个低影响问题.
   • 排除已回答的问题, 琐碎的风格偏好或规划级别的执行细节(除非阻碍正确性).
   • 偏好减少下游返工风险或防止不一致验收测试的澄清.
   • 如果超过5个类别仍未解决, 通过(影响 * 不确定性)启发式选择前5个.

4. 顺序提问流程(交互式):

   • 一次只提出确切一个问题.
   • 对于多项选择题:

     • 分析所有选项并基于以下确定最合适的选项:

       • 项目类型的最佳实践
       • 类似实现中的常见模式
       • 风险降低(安全性, 性能, 可维护性)
       • 与规范中可见的任何明确项目目标或约束的一致性

     • 在顶部突出显示你的推荐选项并附上清晰推理(1-2句话解释为什么这是最佳选择).

     • 格式为: **推荐:** 选项 [X] - <理由>

     • 然后将所有选项渲染为 Markdown 表格:

       选项	描述
       A	<选项 A 描述>
       B	<选项 B 描述>
       C	<选项 C 描述>
       简短	提供不同的简短答案(<=5个词)

     • 表格后添加: 你可以回复选项字母(如 "A"), 说 "是" 或 "推荐" 接受推荐, 或提供你自己的简短答案.

   • 对于简答题风格(没有有意义的不同选项):
     • 基于最佳实践和上下文提供你的建议答案.
     • 格式为: **建议:** <你建议的答案> - <简要理由>
     • 然后输出: 格式: 简短回答(<=5个词). 你可以说 "是" 或 "建议" 接受建议, 或提供你自己的答案.
   • 用户回答后:
     • 如果用户回复 "yes", "recommended" 或 "suggested", 使用你之前陈述的推荐 / 建议作为答案.
     • 否则, 验证答案映射到一个选项或符合 <=5 个词的约束.
     • 如果模糊, 要求快速消除歧义(计数仍属于同一问题; 不前进).
     • 一旦满意, 将其记录在工作内存中(尚未写入磁盘)并移动到下一个排队的问题.
   • 在以下情况时停止进一步提问:
     • 所有关键模糊性早期解决(剩余排队项目变得不必要), 或
     • 用户发出完成信号("done", "good", "no more"), 或
     • 你达到5个已问问题.
   • 永远不要提前揭示未来的排队问题.
   • 如果开始时没有有效问题, 立即报告没有关键模糊性.

5. 每次接受答案后的集成(增量更新方法):

   • 维护规范的内存表示(开始时加载一次)加上原始文件内容.
   • 对于此会话中第一个集成的答案:
     • 确保 ## Clarifications 部分存在(如果缺失, 根据规范模板在最高级别的上下文 / 概述部分之后创建).
     • 在其下, 创建(如果不存在)今天的 ### Session YYYY-MM-DD 子标题.
   • 接受后立即追加项目符号行: - Q: <question> → A: <final answer>.
   • 然后立即将澄清应用到最合适的部分:
     • 功能模糊性 → 更新或在功能需求中添加项目符号.
     • 用户交互 / 角色区分 → 更新用户故事或角色子部分(如果存在), 包含澄清的角色, 约束或场景.
     • 数据形状 / 实体 → 更新数据模型(添加字段, 类型, 关系)保持顺序; 简洁地记录添加的约束.
     • 非功能性约束 → 在成功标准 > 可衡量结果中添加/修改可衡量标准(将模糊形容词转换为指标或明确目标).
     • 边缘情况 / 负面流程 → 在边缘情况 / 错误处理下添加新项目符号(或如果模板提供占位符则创建此类子部分).
     • 术语冲突 → 在整个规范中规范化术语; 仅在必要时通过添加一次 (formerly referred to as "X") 保留原始术语.
   • 如果澄清使早期模糊声明无效, 替换该声明而不是重复; 不留用过时的矛盾文本.
   • 每次集成后保存规范文件以最小化上下文丢失风险(原子覆盖).
   • 保持格式: 不重新排序不相关的部分; 保持标题层次结构完整.
   • 保持每个插入的澄清最小化和可测试(避免叙述性偏离).

6. 验证(每次写入后执行, 最终再进行一次完整检查):

   • 澄清会话每个接受的答案只包含一个项目符号(无重复).
   • 总共询问(接受)的问题 <= 5.
   • 更新的部分不包含新答案旨在解决的持续模糊占位符.
   • 没有矛盾的早期声明保留(扫描已删除的现在无效的替代选择).
   • Markdown 结构有效; 仅允许新标题: ## Clarifications, ### Session YYYY-MM-DD.
   • 术语一致性: 所有更新部分使用相同的规范术语.

7. 将更新的规范写回 FEATURE_SPEC.

8. 报告完成(提问循环结束或提前终止后):

   • 询问和回答的问题数量.
   • 更新规范的路径.
   • 涉及的部分(列出名称).
   • 覆盖范围摘要表, 列出每个分类类别及状态: 已解决(曾是部分 / 缺失并已处理), 已推迟(超过问题配额或更适合规划), 清晰(已足够), 未完成(仍是部分 / 缺失但影响低).
   • 如果有任何未完成或已推迟的剩余, 建议是继续到 /speckit.plan 还是在规划后再次运行 /speckit.clarify.
   • 建议的下一个命令.

行为规则:

• 如果没有发现有意义的模糊性(或所有潜在问题都是低影响的), 回应: "未检测到值得正式澄清的关键歧义." 并建议继续.
• 如果规范文件缺失, 指示用户首先运行 /speckit.specify(不要在此创建新规范).
• 永远不要超过总共5个询问的问题(单个问题的澄清重试不计为新问题).
• 避免推测性技术堆栈问题, 除非缺失阻碍功能清晰性.
• 尊重用户提前终止信号("stop", "done", "proceed").
• 如果由于完全覆盖而没有提问, 输出紧凑的覆盖范围摘要(所有类别清晰)然后建议前进.
• 如果达到配额但仍有未解决的高影响类别, 在已推迟下明确标记它们并附上理由.

优先级排序的上下文: $ARGUMENTS