speckit-clarify

speckit-clarify

本技能内容源自 GitHub Spec Kit 官方提示词模板。

• 上游：https://github.com/github/spec-kit
• 许可：MIT License，Copyright GitHub, Inc.（完整文本见同目录 LICENSE.txt）
• 适配说明：官方模板面向斜杠命令场景；原文中的 $ARGUMENTS 指用户在对话中给出的请求， 跨命令引用（如 speckit.plan）在本技能体系中对应同名的 speckit-* 技能。 其余内容与上游保持一致，未作改写。

---

用户输入

$ARGUMENTS

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

执行前检查

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

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，读取该文件并查找 hooks.before_clarify 键下的条目。
• 如果无法解析 YAML 或格式无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），并说明未检查任何钩子，包括其中注册的任何必需钩子（optional: false），然后继续正常流程。
• 过滤掉 enabled 明确设置为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。
• 对于其余钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空值，则视为可执行钩子。
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现。
• 对于每个可执行钩子，根据其 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_COMMAND_PLAN__ 之前运行并完成。如果用户明确表示要跳过澄清（例如，进行探索性试验），可以继续，但必须警告用户后续返工风险会增加。

执行步骤：

1. 从仓库根目录运行 {SCRIPT} 一次（组合 --json --paths-only 模式 / -Json -PathsOnly）。解析 JSON 载荷中的以下字段：

   • FEATURE_DIR
   • FEATURE_SPEC
   • （可选）捕获 IMPL_PLAN、TASKS，供未来串联流程使用。
   • 如果 JSON 解析失败，则中止并要求用户重新运行 __SPECKIT_COMMAND_SPECIFY__ 或检查功能分支环境。
   • 对于参数中的单引号，例如 "I'm Groot"，使用转义语法：例如 'I'\''m Groot'（或在可能时使用双引号："I'm Groot"）。

2. 如果存在：加载 /memory/constitution.md，了解项目原则和治理约束。

3. 加载当前规范文件。使用以下分类法执行结构化的歧义与覆盖范围扫描。对每个类别标记状态：明确 / 部分明确 / 缺失。生成一份内部覆盖范围映射，用于确定优先级（如果不会提出问题，则不要输出原始映射）。

   功能范围与行为：

   • 核心用户目标与成功标准
   • 明确声明的范围外事项
   • 用户角色 / 用户画像的区分 领域与数据模型：
   • 实体、属性、关系
   • 身份与唯一性规则
   • 生命周期／状态转换
   • 数据量／规模假设

   交互与用户体验流程：

   • 关键用户旅程／操作序列
   • 错误／空白／加载状态
   • 无障碍或本地化说明

   非功能性质量属性：

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

   集成与外部依赖：

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

   边界情况与故障处理：

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

   约束与权衡：

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

   术语与一致性：

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

   完成信号：

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

   杂项／占位内容：

   • TODO 标记／未解决的决策
   • 缺少量化标准的模糊形容词（“健壮”“直观”）

   对于状态为 Partial 或 Missing 的每个类别，添加一个候选问题机会，除非：

   • 澄清不会实质性改变实现或验证策略
   • 信息最好留待规划阶段再确定（内部备注）

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

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

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

   • 每次只能提出一个问题。

   • 问题编写质量（适用于每个问题，包括选择题和简答题）：

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

   • 对于选择题：

     • 分析所有选项，并根据以下因素确定最合适的选项：
       • 该项目类型的最佳实践
       • 类似实现中的常见模式
       • 降低风险（安全性、性能、可维护性）
       • 与规范中明确的项目目标或约束相符
     • 在顶部醒目地给出推荐选项，并清楚说明理由（用 1-2 句话解释为何这是最佳选择）。
     • 格式如下：**Recommended:** Option [X] - <reasoning>
     • 然后将所有选项呈现为 Markdown 表格：

     选项	说明
     A	<选项 A 的说明>
     B	<选项 B 的说明>
     C	<选项 C 的说明>（如有需要，可添加 D/E，最多 5 个）
     简答	提供不同的简答（不超过 5 个词）（仅在适合自由回答时包含）

     • 表格后添加：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. 验证（每次写入后及最终检查时执行）：

   • Clarifications 会话中每个已接受的答案恰好对应一条项目符号（不得重复）。
   • 已提问（且已接受）的问题总数 ≤ 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_COMMAND_SPECIFY__（不要在此处创建新规范）。
• 提出的问题总数不得超过 5 个（针对同一个问题的澄清重试不计为新问题）。
• 除非缺少相关信息会妨碍功能明确性，否则避免询问推测性的技术栈问题。
• 尊重用户提前终止的信号（“stop”“done”“proceed”）。
• 如果因信息已完整而未提出问题，请输出简洁的覆盖情况摘要（所有类别均为“清晰”），然后建议继续。
• 如果问题名额已用尽，但仍有未解决的高影响类别，请在“待处理”部分明确指出，并说明理由。

优先级背景：{ARGS}

强制执行后钩子

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

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

• 如果文件不存在，或 hooks.after_clarify 下未注册任何钩子，则跳至“完成报告”。
• 如果文件存在，读取该文件并查找 hooks.after_clarify 键下的条目。
• 如果无法解析 YAML 或 YAML 无效，不得悄然跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），且未检查任何钩子，包括其中注册的强制钩子（optional: false），然后继续“完成报告”。
• 过滤掉 enabled 明确设为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。
• 对于其余每个钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 对于每个可执行钩子，根据其 optional 标志输出以下内容：
  • 强制钩子（optional: false）——必须为每个强制钩子输出 EXECUTE_COMMAND:：

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

    输出上述代码块后，必须实际调用该钩子，并等待其完成后再继续。调用方式与在此 Agent/会话中自行运行命令的方式相同（调用方式可能与字面上的 {command} ID 不同，例如，技能模式 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出代码块并不算运行了钩子。
  • 可选钩子（optional: true）：

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

完成报告

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

• 已提出并回答的问题数量。
• 已更新规格说明的路径。
• 修改过的章节（列出名称）。
• 规格质量检查清单状态（如果重新验证了 FEATURE_DIR/checklists/requirements.md）：显示通过项数量的前后变化（例如，“规格质量检查清单：12/16 → 15/16 项通过”），并列出状态发生变化的所有项目，包括新勾选的项目（未勾选 → 已勾选）和回退的项目（已勾选 → 未勾选）。如果仍有未勾选项，将其列为需关注事项。
• 覆盖情况摘要表：列出每个分类及其状态：已解决（原为部分覆盖/缺失且已处理）、待处理（超出提问配额或更适合在规划阶段处理）、明确（已有充分说明）、未解决（仍为部分覆盖/缺失，但影响较低）。
• 如果仍有未解决或待处理项，建议继续执行 __SPECKIT_COMMAND_PLAN__，或在规划完成后再次运行 __SPECKIT_COMMAND_CLARIFY__。
• 建议的下一条命令。

完成条件

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