用户输入
$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} 等待钩子命令的结果后再继续到大纲。{command}ID 不同,例如,技能模式代理可能将其运行为/skill:speckit-...或$speckit-...)。仅发出代码块并不运行钩子。
- 可选钩子 (
- 如果没有注册钩子或
.specify/extensions.yml不存在,则静默跳过。
大纲
目标:检测并减少活动功能规格中的歧义或缺失决策点,并将澄清结果直接记录在规格文件中。
注意:此澄清工作流预计在调用 /speckit-plan 之前运行(并完成)。如果用户明确表示他们正在跳过澄清(例如,探索性冲刺),你可以继续,但必须警告下游返工风险增加。
执行步骤:
-
从仓库根目录运行
.specify/scripts/bash/check-prerequisites.sh --json --paths-only一次(组合的--json --paths-only模式 /-Json -PathsOnly)。解析最小的 JSON 负载字段:FEATURE_DIRFEATURE_SPEC- (可选地捕获
IMPL_PLAN、TASKS用于未来的链式流程。) - 如果 JSON 解析失败,中止并指示用户重新运行
/speckit-specify或验证功能分支环境。 - 对于参数中的单引号,例如 "I'm Groot",使用转义语法:例如 'I'''m Groot'(如果可能,使用双引号:"I'm Groot")。
-
如果存在:加载
.specify/memory/constitution.md以获取项目原则和治理约束。 -
加载当前的规格文件。使用此分类法执行结构化的歧义和覆盖范围扫描。对于每个类别,标记状态:清晰 / 部分 / 缺失。生成用于优先级的内部覆盖图(如果没有要问的问题,则不要输出原始图)。
功能范围与行为:
- 核心用户目标与成功标准
- 明确的范围外声明
- 用户角色 / 角色区分
领域与数据模型:
- 实体、属性、关系
- 身份与唯一性规则
- 生命周期/状态转换
- 数据量/规模假设
交互与用户体验流程:
- 关键用户旅程/序列
- 错误/空/加载状态
- 可访问性或本地化说明
非功能性质量属性:
- 性能(延迟、吞吐量目标)
- 可扩展性(水平/垂直、限制)
- 可靠性与可用性(正常运行时间、恢复预期)
- 可观测性(日志、指标、追踪信号)
- 安全与隐私(认证/授权、数据保护、威胁假设)
- 合规性/监管约束(如果有)
集成与外部依赖:
- 外部服务/API 及故障模式
- 数据导入/导出格式
- 协议/版本假设
边界情况与故障处理:
- 负面场景
- 速率限制/节流
- 冲突解决(例如,并发编辑)
约束与权衡:
- 技术约束(语言、存储、托管)
- 明确的权衡或被拒绝的替代方案
术语与一致性:
- 规范术语表术语
- 避免的同义词/废弃术语
完成信号:
- 验收标准的可测试性
- 可度量的完成定义风格指标
杂项/占位符:
- TODO 标记/未解决的决策
- 缺乏量化的模糊形容词("健壮"、"直观")
对于每个状态为“部分”或“缺失”的类别,添加候选问题机会,除非:
- 澄清不会实质上改变实现或验证策略
- 该项是专门关于实现方法、技术栈比较或任务分解的(内部记录)
-
(内部)生成一个优先的候选澄清问题队列(最多5个)。不要一次全部输出。应用这些约束:
- 整个会话中最多5个总问题。
- 每个问题必须可以使用以下任一方式回答:
- 一个简短的多项选择(2-5个不同的、互斥的选项),或
- 一个单词/短语答案(明确约束:"答案最多5个单词")。
- 仅包括其答案实质上影响架构、数据建模、任务分解、测试设计、用户体验行为、运营准备或合规性验证的问题。
- 确保类别覆盖平衡:首先尝试覆盖影响最大的未解决类别;避免在单个高影响力领域(例如安全态势)未解决时提出两个低影响力问题。
- 排除已回答的问题、琐碎的风格偏好或计划级别的执行细节(除非阻塞正确性)。
- 优先选择减少下游返工风险或防止验收测试错位的澄清。
- 如果超过5个类别仍未解决,则选择(影响 * 不确定性)启发式得分最高的5个。
-
顺序提问循环(交互式):
-
一次只展示恰好一个问题。
-
问题写作质量(适用于每个问题,无论是多项选择还是简短回答):
- 以
**问题:**开头,后跟一个以?结尾的完整疑问句。?之前的问题文本必须能够独立理解。 - 绝不要使用主题标签、章节标题或需求 ID 作为问题本身。例如,
验收设备/运行时矩阵 (FR-023)是无效的——它是一个标签,而不是一个问题。 - 在
?之后,唯一允许的后缀是可选的在括号内的需求/问题 ID。确切格式:**问题:** <疑问句>?或**问题:** <疑问句>? (FR-023)。绝不要将 ID 放在?之前,也绝不要使用 ID(单独或与主题标签一起)作为整个提示。 - 在问题行之后,立即在推荐/选项之前添加一句通俗易懂的“为何重要”句子(相关于验收或发布的利害关系)。
- 使用日常用语;仅当在同一句子中定义时才引入术语。自我检查:不了解 Spec Kit 的读者必须能够仅从问题行回答。简洁是可以的;模糊的标签则不行。
- 以
-
对于多项选择问题:
- 分析所有选项并根据以下条件确定最合适的选项:
- 项目类型的最佳实践
- 类似实现中的常见模式
- 风险降低(安全性、性能、可维护性)
- 与规格中可见的任何明确项目目标或约束的一致性
- 在顶部突出显示你的推荐选项,并附上清晰的推理(1-2句解释为什么这是最佳选择)。
- 格式化为:
**推荐:** 选项 [X] - <推理> - 然后将所有选项呈现为 Markdown 表格:
选项 描述 A <选项 A 描述> B <选项 B 描述> C <选项 C 描述>(根据需要添加 D/E,最多5个) 简短 提供不同的简短答案(最多5个单词)(仅当自由格式替代方案合适时包括) - 表格后添加:
你可以回复选项字母(例如,“A”),通过说“是”或“推荐”来接受推荐,或者提供你自己的简短答案。
- 分析所有选项并根据以下条件确定最合适的选项:
-
对于短答案风格(没有有意义的分立选项):
- 根据最佳实践和上下文提供你的建议答案。
- 格式化为:
**建议:** <你提出的答案> - <简要推理> - 然后输出:
格式:短答案(最多5个单词)。你可以通过说“是”或“建议”来接受建议,或者提供你自己的答案。
-
在用户回答后:
- 如果用户回复“是”、“推荐”或“建议”,则使用你之前陈述的推荐/建议作为答案。
- 否则,验证答案是否映射到一个选项或符合 <=5 个单词的约束。
- 如果模棱两可,要求快速澄清(计数仍属于同一问题;不要前进)。
- 一旦满意,将其记录在工作记忆中(尚不写入磁盘)并移至下一个排队问题。
-
在以下情况下停止提问:
- 所有关键歧义已提前解决(剩余排队项目变得不必要),或
- 用户表示完成("完成"、"好"、"没有更多了"),或
- 你已经问了5个问题。
-
绝不要提前透露未来排队的问题。
-
如果一开始就没有有效问题,立即报告没有关键歧义。
-
-
在每个接受的答案之后进行集成(增量更新方法):
- 在内存中维护规格的表示(开始时加载一次)以及原始文件内容。
- 对于本会话中第一个集成的答案:
- 确保存在
## 澄清说明章节(如果缺失,则在规格模板中最高级别的上下文/概述章节之后立即创建)。 - 在其下,为今天创建一个(如果不存在)
### 会话 YYYY-MM-DD子标题。
- 确保存在
- 在接受后立即追加一个项目符号行:
- 问:<问题> → 答:<最终答案>。 - 然后立即将澄清应用于最合适的章节:
- 功能歧义 → 在功能需求中更新或添加一个项目符号。
- 用户交互/参与者区分 → 更新用户故事或参与者子章节(如果存在),包含澄清的角色、约束或场景。
- 数据形状/实体 → 更新数据模型(添加字段、类型、关系),保持顺序;简洁地说明添加的约束。
- 非功能性约束 → 在成功标准 > 可度量结果中添加/修改可度量标准(将模糊形容词转换为指标或明确目标)。
- 边界情况/负面流程 → 在边界情况/错误处理下添加一个新的项目符号(如果模板为此提供了占位符,则创建这样的子章节)。
- 术语冲突 → 在整个规格中标准化术语;仅当必要时通过添加
(以前称为“X”)来保留原术语。
- 如果澄清使先前模糊的陈述无效,则替换该陈述而不是复制;不留过时的矛盾文本。
- 在每次集成后保存规格文件,以最大限度减少上下文丢失的风险(原子覆盖)。
- 保持格式:不要重新排序不相关的章节;保持标题层次结构完整。
- 保持每个插入的澄清最小且可测试(避免叙述漂移)。
-
验证(在每次写入后以及最终通过后执行):
- 澄清说明会话每个接受的答案恰好包含一个项目符号(无重复)。
- 总提问(接受)的问题 ≤ 5。
- 更新的章节不包含新的答案本应解决的残留模糊占位符。
- 没有残留矛盾的前一个陈述(扫描是否删除了现在无效的替代选择)。
- Markdown 结构有效;只允许新的标题:
## 澄清说明、### 会话 YYYY-MM-DD。 - 术语一致性:在所有更新的章节中使用相同的规范术语。
-
将更新后的规格写回
FEATURE_SPEC。 -
重新验证规格质量检查清单(如果存在):
- 检查
FEATURE_DIR/checklists/requirements.md是否存在。 - 如果不存在,则静默跳过此步骤。
- 如果存在:
- 读取检查清单文件。
- 识别所有 GitHub 任务列表复选框行——匹配
- [ ]、- [x]或- [X](不区分大小写,容忍前导空格以支持嵌套项)且不在代码块内的行。忽略所有其他内容(标题、注释、非复选框项目符号、元数据)。 - 对于每个复选框行,将其当前标记状态(已选中或未选中)和项目文本记录到“之前”快照列表中。
- 根据更新后的规格(步骤7中刚刚保存的版本)重新评估每个复选框项。
- 对于每个复选框项,仅在选中/未选中状态实际更改时更新:
- 如果项目现在通过并且之前未选中:将
[ ]更改为[x]。 - 如果项目现在失败并且之前已选中:将
[x]/[X]更改为[ ]。 - 如果状态未更改:保持不变。
- 跳过任何无法客观从规格本身确定的项目(例如,需要人工判断或外部测试的),其状态不变。
- 如果项目现在通过并且之前未选中:将
- 如果至少一个复选框更改了状态,请输出一个包含已更改项摘要的 Markdown 表格:
项目 之前状态 之后状态 <项目文本> [ ] 或 [x] [ ] 或 [x] - 在表格后,添加一个最终项目符号:
- 向用户建议他们现在可以运行 /speckit-plan 来继续。 - 将更新后的检查清单写回其文件。
- 检查
-
输出最终结果:
## 验证摘要章节,包含:- 总接受的问题数:<数字>
- 更新的章节:<逗号分隔的列表>
- 是否更新了检查清单:是/否