speckit-clarify

用户输入

$ARGUMENTS

如果用户输入不为空，必须在继续之前考虑该输入。

执行前检查

检查扩展钩子（在澄清之前）：

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，读取该文件并查找 hooks.before_clarify 键下的条目。
• 如果 YAML 无法解析或无效，不要悄悄跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），并说明未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后照常继续。
• 过滤掉 enabled 明确为 false 的钩子。没有 enabled 字段的钩子默认视为已启用。
• 对于每个剩余钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null／空值，则视为可执行。
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现。
• 从钩子命令名称构造命令调用时，将句点（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对于每个可执行钩子，根据其 optional 标记输出以下内容：

  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选前置钩子**：{extension}
    命令：`/{command}`
    描述：{description}
    
    提示词：{prompt}
    执行方式：`/{command}`
    

  • 强制钩子（optional: false）：

    ## 扩展钩子
    
    **自动前置钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    
    请等待钩子命令的结果，然后再继续执行大纲步骤。
    

    输出上述内容块后，必须实际调用钩子并等待其完成，然后才能继续。像在此 Agent／会话中自行运行命令一样运行它（调用方式可能与显示的 {command} 标识不同，例如，技能模式的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出该内容块并不等于运行钩子。

• 如果没有注册钩子，或 .specify/extensions.yml 不存在，则静默跳过。

大纲

目标：检测并减少当前功能规范中的歧义或缺失的决策点，并将澄清内容直接记录到规范文件中。

注意：此澄清工作流应在调用 /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. 如果存在，加载 .specify/memory/constitution.md，以了解项目原则和治理约束。

3. 加载当前规范文件。使用以下分类法，进行结构化的歧义与覆盖范围扫描。为每个类别标注状态：清晰／部分清晰／缺失。生成用于确定优先级的内部覆盖图（除非不会提出问题，否则不要输出原始覆盖图）。

   功能范围与行为：

   • 核心用户目标与成功标准
   • 明确声明的范围外内容
   • 用户角色／人物类型区分

   领域与数据模型：

   • 实体、属性、关系
   • 身份与唯一性规则
   • 生命周期／状态转换
   • 数据量／规模假设 交互与用户体验流程：
   • 关键用户旅程／序列
   • 错误／空白／加载状态
   • 无障碍访问或本地化说明

   非功能质量属性：

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

   集成与外部依赖：

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

   边缘情况与故障处理：

   • 异常场景
   • 速率限制／节流
   • 冲突解决（例如，并发编辑）

   约束与权衡：

   • 技术约束（语言、存储、托管）
   • 明确的权衡或已否决的替代方案

   术语与一致性：

   • 规范术语表
   • 应避免使用的同义词／已弃用术语

   完成信号：

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

   杂项／占位符：

   • TODO 标记／尚未解决的决策
   • 缺乏量化依据的模糊形容词（“稳健”“直观”）

   对每个状态为“部分”或“缺失”的类别，提出一个候选问题，但以下情况除外：

   • 澄清不会实质性改变实施或验证策略
   • 内容专门涉及实现方法、技术栈比较或任务拆分（内部备注）

4. （在内部）生成按优先级排序的候选澄清问题队列（最多 5 个）。不要一次性全部输出。遵循以下约束：

   • 整个会话中最多提出 5 个问题。
   • 每个问题都必须能通过以下任一方式回答：
     • 简短的多选项选择（2–5 个彼此不同且互斥的选项），或
     • 一个词／短语（明确限定：“答案不超过 5 个词”）。
   • 仅纳入答案会实质性影响架构、数据建模、任务分解、测试设计、用户体验行为、运维准备或合规验证的问题。
   • 确保类别覆盖均衡：优先覆盖影响最大的未解决类别；如果某个高影响领域（例如安全态势）尚未解决，避免提出两个低影响问题。
   • 排除已有答案的问题、无关紧要的风格偏好，以及计划层面的执行细节（除非它们会阻碍正确性）。
   • 优先澄清能降低后续返工风险或避免验收测试不匹配的问题。
   • 如果仍有 5 个以上未解决的类别，根据（影响 * 不确定性）启发式选择优先级最高的 5 个。

5. 顺序提问循环（交互式）：

   • 每次只提出一个问题。

   • 问题编写质量（适用于每个问题，无论是选择题还是简答题）：

     • 以 **Question:** 开头，后接一个完整的疑问句，并以 ? 结尾。? 前的问题文本必须独立成句且意思完整。
     • 绝不能把主题标签、章节标题或需求 ID 当作问题本身。例如，Acceptance device/runtime matrix (FR-023) 是无效的——它是标签，不是问题。
     • ? 后只允许添加可选的括号括起的需求／问题 ID。格式必须为：**Question:** <疑问句>? 或 **Question:** <疑问句>? (FR-023)。绝不能把 ID 放在 ? 前，也绝不能单独使用 ID（无论是否带有主题标签）作为整个问题。
     • 问题行后立即添加一个通俗易懂的“为何重要”句子，说明其对验收或发布的影响，然后再给出建议／选项。
     • 使用日常用语；只有在同一句中解释术语时才引入行话。自检：不了解 Spec Kit 的读者也必须能够仅凭问题行作答。简洁即可，但不要使用晦涩的标签。

   • 对于选择题：

     • 分析所有选项，并根据以下因素确定最合适的选项：
       • 符合项目类型的最佳实践
       • 类似实现中的常见模式
       • 降低风险（安全性、性能、可维护性）
       • 与规范中明确列出的项目目标或限制保持一致
     • 在最上方醒目地给出你推荐的选项，并用 1 至 2 句话清楚说明理由。
     • 格式为：**Recommended:** Option [X] - <reasoning>
     • 然后将所有选项呈现为 Markdown 表格：

     Option	Description
     A
     B
     C	(add D/E as needed up to 5)
     Short	Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate)

     • 表格后添加：You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.

   • 对于简答题（没有有意义的离散选项）：

     • 根据最佳实践和上下文提供你的建议答案。
     • 格式为：**Suggested:** <your proposed answer> - <brief reasoning>
     • 然后输出：Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.

   • 用户回答后：

     • 如果用户回复 "yes"、"recommended" 或 "suggested"，则将你先前给出的建议／答案作为答案。
     • 否则，验证该回答是否对应某个选项，或是否符合不超过 5 个词的限制。
     • 如果回答含糊不清，提出一个简短的澄清问题（仍计为同一个问题，不要继续下一个问题）。
     • 答案确认无误后，将其记录在工作记忆中（暂不写入磁盘），然后转到下一个待提问题。

   • 在以下情况下停止继续提问：

     • 所有关键歧义已提前解决（其余待提问题变得无关紧要），或
     • 用户表示完成（"done"、"good"、"no more"），或
     • 已提出 5 个问题。

   • 绝不要提前透露后续待提问题。

   • 如果一开始就没有有效问题，立即说明没有关键歧义。

6. 每次接受答案后进行集成（增量更新方式）：

   • 在内存中维护规范的表示（在开始时加载一次）以及原始文件内容。
   • 本次会话中首次集成答案时：
     • 确保存在 ## Clarifications（澄清）章节；如果缺失，请根据规范模板将其创建在最高层级的上下文/概览章节之后。
     • 在该章节下创建（如果尚不存在）### Session YYYY-MM-DD 子标题，日期使用今天的日期。
   • 接受答案后立即追加一条项目符号行：- Q: <question> → A: <final answer>。
   • 然后立即将这项澄清应用到最合适的章节：
     • 功能歧义 → 在功能需求中更新或添加项目符号。
     • 用户交互/角色区分 → 在用户故事或角色小节（如果存在）中更新已澄清的角色、约束或场景。
     • 数据结构/实体 → 更新数据模型（添加字段、类型、关系），同时保持原有顺序；简要说明新增的约束。
     • 非功能约束 → 在成功标准 > 可衡量成果中添加/修改可量化的标准（将模糊形容词转化为指标或明确目标）。
     • 边缘情况/负向流程 → 在边缘情况/错误处理下添加新项目符号（或在模板提供占位符时创建该小节）。
     • 术语冲突 → 在整个规范中统一术语；仅在必要时保留原术语，并添加一次 (formerly referred to as "X")。
   • 如果澄清使先前含糊的陈述失效，请替换该陈述，而不是重复添加；不得保留过时的矛盾文本。
   • 每次集成后立即保存规范文件，以尽量降低上下文丢失风险（原子覆盖）。
   • 保留格式：不要重新排列无关章节；保持标题层级不变。
   • 每条新增澄清都应简洁且可测试（避免叙述偏离主题）。

7. 验证（每次写入后及最终检查时执行）：

   • 澄清章节中每个已接受答案恰好对应一条项目符号（不得重复）。
   • 已提问（已接受）的问题总数 ≤ 5。
   • 更新后的章节中不得残留本次答案旨在解决的模糊占位内容。
   • 不得保留任何与答案矛盾的先前陈述（检查并删除现已无效的备选方案）。
   • Markdown 结构有效；仅允许新增以下标题：## Clarifications、### Session YYYY-MM-DD。
   • 术语一致性：所有已更新章节均使用相同的规范术语。

8. 将更新后的规范写回 FEATURE_SPEC。

9. 重新验证规范质量检查清单（如果存在）：

   • 检查 FEATURE_DIR/checklists/requirements.md 是否存在。
   • 如果不存在，则静默跳过此步骤。
   • 如果存在：
     1. 读取检查清单文件。
     2. 找出所有 GitHub 任务列表复选框行——即匹配 - [ ]、- [x] 或 - [X] 的行（不区分大小写，并允许嵌套项目带有前导空格），但不包括代码围栏中的内容。忽略所有其他内容（标题、备注、非复选框项目、元数据）。
     3. 对每个复选框行，记录其当前标记状态（已选中或未选中）及项目文本，保存到变更前快照列表中。
     4. 根据已更新的规范（步骤 7 中刚保存的版本），重新评估每个复选框项目。
     5. 仅当选中状态实际发生变化时，才更新相应复选框项目：
        • 如果该项目现在通过检查且此前未选中：将 [ ] 改为 [x]。
        • 如果该项目现在未通过检查且此前已选中：将 [x]/[X] 改为 [ ]。
        • 如果状态未变：保留原标记（保持原有大小写，以避免产生无意义的差异）。
     6. 保存更新后的检查清单文件。**仅切换状态发生变化的复选框行中的 [ ]/[x] 标记部分。**为避免产生大量无意义的差异，文件中的其他所有内容——标题、元数据、备注、行顺序、空格——都必须保持不变。
     7. 将变更前快照与当前状态进行比较，为完成报告计算三个列表：
        • 新通过：从未选中变为已选中的项目。
        • 退化项：从已选中变为未选中的项目。
        • 仍未选中：保持未选中的项目。
     8. 记录变更前后的通过数量，格式为已选中/复选框项目总数（例如，“12/16 → 15/16 个项目通过检查”）。

行为规则：

• 如果未发现有实质影响的歧义（或所有潜在问题的影响都很低），请回复：“未发现值得正式澄清的关键歧义。”并建议继续推进。
• 如果规范文件缺失，请指示用户先运行 /speckit-specify（此处不要创建新规范）。
• 提出的问题总数不得超过 5 个（针对同一问题的澄清重试不计为新问题）。
• 除非缺少相关信息会妨碍功能理解，否则避免询问推测性的技术栈问题。
• 尊重用户提前结束的信号（“stop”“done”“proceed”）。
• 如果因需求已完整覆盖而无需提问，请输出简洁的覆盖情况摘要（所有类别均为 Clear），然后建议继续推进。
• 如果已达到提问上限但仍有未解决的高影响类别，请在“延期”项下明确说明，并给出理由。

优先级判断上下文：$ARGUMENTS

强制性执行后钩子

在向用户报告完成之前，必须完成本节。

检查项目根目录中是否存在 .specify/extensions.yml。

• 如果该文件不存在，或者 hooks.after_clarify 下未注册任何钩子，则跳到“完成报告”。
• 如果该文件存在，则读取文件，并查找 hooks.after_clarify 键下的条目。
• 如果无法解析 YAML 或 YAML 无效，不要悄悄跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），并说明未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后继续执行“完成报告”。
• 过滤掉 enabled 明确设为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。
• 对每个剩余钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 根据钩子命令名称构造命令调用时，将点号（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对于每个可执行钩子，根据其 optional 标记输出以下内容：

  • 强制钩子（optional: false）——每个强制钩子都必须输出 EXECUTE_COMMAND:：

    ## 扩展钩子
    
    **自动钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    

    输出上述内容后，必须实际调用该钩子，并等待其执行完毕后再继续。按照你在当前 Agent/会话中亲自执行命令的方式运行它（实际调用方式可能与上面显示的 {command} 标识不同，例如，技能模式的 Agent 会将其作为 /skill:speckit-... 或 $speckit-... 运行）。仅输出上述内容并不代表运行了钩子。

  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选钩子**：{extension}
    命令：`/{command}`
    说明：{description}
    
    提示词：{prompt}
    执行方式：`/{command}`
    

完成报告

完成后（提问循环结束或提前终止后）报告：

• 提出并得到回答的问题数量。
• 已更新规范文件的路径。
• 涉及的章节（列出名称）。
• 规范质量检查清单状态（如果已重新验证 FEATURE_DIR/checklists/requirements.md）：显示通过项数的前后对比（例如，“规范质量检查清单：12/16 → 15/16 项通过”），并列出状态发生变化的项目——新勾选的项目（未勾选 → 已勾选）以及任何回退项目（已勾选 → 未勾选）。如果仍有未勾选项，列出需要关注的方面。
• 覆盖情况汇总表，列出各分类及其状态：已解决（原为部分覆盖/缺失且已处理）、延后（超出提问配额，或剩余事项具体涉及实施方法、技术栈比较或任务拆分）、清晰（原本已足够）、待解决（仍为部分覆盖/缺失但影响较低）。
• 如果仍有待解决或延后事项，建议继续执行 /speckit-plan，还是稍后在计划阶段结束后再次运行 /speckit-clarify。
• 建议的下一条命令。

完成条件

• 已识别规范中的歧义，并将澄清内容整合到规范文件中
• 已根据更新后的规范重新验证规范质量检查清单（如果存在 FEATURE_DIR/checklists/requirements.md）
• 已按照上述“强制性执行后钩子”中的规则分派或跳过扩展钩子
• 已向用户报告完成情况，包括已回答的问题、涉及的章节、检查清单状态和覆盖情况汇总