检查清单目的:“英文的单元测试”
核心概念:检查清单是需求编写的“单元测试”——它们验证特定领域中需求的质量、清晰度和完整性。
非用于验证/测试:
- ❌ 非“验证按钮点击是否正确”
- ❌ 非“测试错误处理是否生效”
- ❌ 非“确认 API 返回 200”
- ❌ 非检查代码/实现是否匹配规约
用于需求质量验证:
- ✅ “是否为所有卡片类型定义了视觉层级需求?”(完整性)
- ✅ “是否用具体的尺寸/定位量化了‘突出显示’?”(清晰度)
- ✅ “所有交互元素的悬停状态需求是否一致?”(一致性)
- ✅ “是否为键盘导航定义了无障碍需求?”(覆盖度)
- ✅ “规约是否定义了当 logo 图片加载失败时的处理方式?”(边界情况)
比喻:如果你的规约是用英文编写的代码,那么检查清单就是它的单元测试套件。你测试的是需求是否编写良好、完整、无歧义且可以开始实现——而不是实现是否工作。
所有权和复选框生命周期:
- 由此命令生成的自定义检查清单是审阅者拥有的需求质量审查工件。
[x]表示审阅者判断该需求质量标准已满足。[x]并非表示实现工作已完成。- 此命令生成或追加检查清单条目;它绝不能将生成的条目标记为
[x]。 - 仅在审阅者明确要求时,智能体才可以协助评估条目。
checklists/requirements.md是一个由/speckit-specify和/speckit-clarify维护的独立内置规约质量检查清单;不要将该例外应用于此处生成的自定义检查清单。
用户输入
$ARGUMENTS
在继续之前,你必须考虑用户输入(如果不为空)。
执行前检查
检查扩展钩子(在生成检查清单之前):
- 检查项目根目录下是否存在
.specify/extensions.yml。 - 如果存在,读取它并查找
hooks.before_checklist键下的条目。 - 如果 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不存在,则静默跳过。
执行步骤
-
设置:从仓库根目录运行
.specify/scripts/bash/check-prerequisites.sh --json --template checklist-template,并解析 JSON 以获取 FEATURE_DIR、AVAILABLE_DOCS 列表和 TEMPLATE_CONTENT。- 所有文件路径必须是绝对路径。
- 对于参数中的单引号(如“I'm Groot”),请使用转义语法:例如 'I'''m Groot'(如果可能,请使用双引号:“I'm Groot”)。
-
如果存在:加载
.specify/memory/constitution.md以获取项目原则与治理约束。 -
澄清意图(动态):推导出最多三个初始的上下文澄清问题(无预置目录)。它们必须:
- 从用户的措辞 + 从规约/计划/任务中提取的信号生成。
- 仅询问那些会实质性地改变检查清单内容的信息。
- 如果
$ARGUMENTS中已经明确,则逐个跳过。 - 优先追求精确性而非广度。
生成算法:
- 提取信号:功能领域关键词(例如 auth、latency、UX、API)、风险指标(“critical”、“must”、“compliance”)、利益相关者提示(“QA”、“review”、“security team”)和明确的可交付物(“a11y”、“rollback”、“contracts”)。
- 将信号聚类为候选关注领域(最多 4 个),按相关性排序。
- 如果未明确,识别可能的受众与时机(作者、审阅者、QA、发布)。
- 检测缺失的维度:范围广度、深度/严谨性、风险重点、排除边界、可衡量的验收标准。
- 从这些原型中制定问题:
- 范围细化(例如,“是否应包括与 X 和 Y 的集成接触点,还是仅限于局部模块的正确性?”)
- 风险优先级排序(例如,“哪些潜在风险领域应接受强制性的门控检查?”)
- 深度校准(例如,“这是一个轻量级的预提交完整性检查,还是一个正式的发布门禁?”)
- 受众框架(例如,“这是供作者本人使用,还是用于同行审查 PR 期间?”)
- 边界排除(例如,“我们是否应明确排除本轮的性能调优项目?”)
- 场景类别缺口(例如,“未检测到恢复流程——回滚/部分失败路径是否在范围内?”)
问题格式化规则:
- 如果提供选项,生成一个紧凑的表格,包含列:选项 | 候选 | 重要性
- 最多限制为 A–E 选项;如果自由形式的回答更清晰,则省略表格
- 切勿要求用户重述他们已经说过的话
- 避免推测性类别(不要幻觉)。如果不确定,明确提问:“请确认 X 是否属于范围。”
当交互不可能时的默认值:
- 深度:标准
- 受众:如果是代码相关,则为审阅者(PR);否则为作者
- 重点:前 2 个相关性聚类
输出问题(标记为 Q1/Q2/Q3)。在回答后:如果仍有 ≥2 个场景类别(备选/异常/恢复/非功能领域)不明确,你可以最多再询问两个有针对性的后续问题(Q4/Q5),每个问题附带一行理由(例如,“未解决的恢复路径风险”)。总共不超过五个问题。如果用户明确拒绝,则跳过升级。
-
理解用户请求:结合
$ARGUMENTS+ 澄清回答:- 推导检查清单主题(例如,安全、审查、部署、用户体验)
- 汇总用户提到的明确必备项目
- 将焦点选择映射到类别框架
- 从规约/计划/任务中推断任何缺失的上下文(不要幻觉)
-
加载功能上下文:从 FEATURE_DIR 读取:
- spec.md:功能需求和范围
- plan.md(如果存在):技术细节、依赖项
- tasks.md(如果存在):实现任务
上下文加载策略:
- 仅加载与活动关注领域相关的必要部分(避免完整文件转储)
- 优先将长章节总结为简洁的场景/需求要点
- 使用渐进式披露:仅在检测到缺口时添加后续检索
- 如果源文档很大,则生成临时摘要项目,而不是嵌入原始文本
-
生成检查清单 - 使用 TEMPLATE_CONTENT 作为结构模板,创建“需求的单元测试”:
- 如果不存在,则创建
FEATURE_DIR/checklists/目录 - 生成唯一的检查清单文件名:
- 使用基于领域的简短描述性名称(例如,
ux.md、api.md、security.md) - 格式:
[domain].md
- 使用基于领域的简短描述性名称(例如,
- 文件处理行为:
- 如果文件不存在:创建新文件,从 CHK001 开始编号条目
- 如果文件存在:将新条目追加到现有文件,从最后一个 CHK ID 继续编号(例如,如果最后一个条目是 CHK015,则新条目从 CHK016 开始)
- 切勿删除或替换现有的检查清单内容——始终保留并追加
- 将所有新生成的条目保持未选中状态(
[ ]);复选框状态属于审阅者
核心原则——测试需求,而非实现: 每个检查清单条目必须评估需求本身的以下方面:
- 完整性:所有必要的需求是否都存在?
- 清晰度:需求是否无歧义且具体?
- 一致性:需求之间是否相互对齐?
- 可测量性:需求是否可以客观验证?
- 覆盖度:是否涵盖了所有场景/边界情况?
类别结构 - 按需求质量维度对条目进行分组:
- 需求完整性(所有必要的需求是否都已记录?)
- 需求清晰度(需求是否具体且无歧义?)
- 需求一致性(需求之间是否无缝对齐?)
- 验收标准质量(成功标准是否可衡量?)
- 场景覆盖度(是否涵盖了所有流程/情况?)
- 边界情况覆盖度(是否定义了边界条件?)
- 非功能性需求(性能、安全、可访问性等——是否已指定?)
- 依赖项与假设(是否已记录并验证?)
- 歧义与冲突(哪些需要澄清?)
如何编写检查清单条目——“英文的单元测试”:
❌ 错误(测试实现):
- “验证着陆页显示 3 个剧集卡片”
- “测试悬停状态在桌面上正常工作”
- “确认点击 Logo 导航到首页”
✅ 正确(测试需求质量):
- “是否指定了特色剧集的确切数量和布局?”[完整性]
- “是否用具体的尺寸/定位量化了‘突出显示’?”[清晰度]
- “所有交互元素的悬停状态需求是否一致?”[一致性]
- “是否为所有交互式 UI 定义了键盘导航需求?”[覆盖度]
- “当 Logo 图片加载失败时,是否指定了回退行为?”[边界情况]
- “是否为异步剧集数据定义了加载状态?”[完整性]
- “规约是否为竞争性 UI 元素定义了视觉层级?”[清晰度]
条目结构: 每个条目应遵循以下模式:
- 以问题形式询问需求质量
- 关注规约/计划中已编写(或未编写)的内容
- 在方括号中包含质量维度 [完整性/清晰度/一致性/等]
- 在检查现有需求时引用规约章节
[规范 §X.Y] - 在检查缺失需求时使用
[缺口]标记
按质量维度的示例:
完整性:
- “是否为所有 API 故障模式定义了错误处理需求?[缺口]”
- “是否为所有交互元素指定了无障碍需求?[完整性]”
- “是否为响应式布局定义了移动端点需求?[缺口]”
清晰度:
- “是否用量化的时序阈值定义了‘快速加载’?[清晰度,规范 §NFR-2]”
- “‘相关剧集’的选择标准是否明确界定?[清晰度,规范 §FR-5]”
- “是否用可衡量的视觉属性定义了‘突出’?[歧义,规范 §FR-4]”
一致性:
- “所有页面的导航需求是否保持一致?[一致性,规范 §FR-10]”
- “着陆页和详情页的卡片组件需求是否一致?[一致性]”
覆盖度:
- “是否定义了零状态场景(无剧集)的需求?[覆盖度,边界情况]”
- “是否处理了并发用户交互场景?[覆盖度,缺口]”
- “是否指定了部分数据加载失败的需求?[覆盖度,异常流程]”
可测量性:
- “视觉层级需求是否可测量/可测试?[验收标准,规范 §FR-1]”
- “‘平衡的视觉重量’是否可以客观验证?[可测量性,规范 §FR-2]”
场景分类与覆盖度(需求质量重点):
- 检查是否存在以下场景的需求:主场景、备选场景、异常/错误、恢复、非功能性
- 对于每个场景类别,询问:“[场景类型]需求是否完整、清晰且一致?”
- 如果缺少场景类别:“[场景类型]需求是被有意排除还是缺失了?[缺口]”
- 当存在状态变化时,包含弹性/回滚:“是否为迁移失败定义了回滚需求?[缺口]”
可追溯性需求:
- 最低要求:≥80% 的条目必须包含至少一个可追溯性引用
- 每个条目应引用:规约章节
[规范 §X.Y],或使用标记:[缺口]、[歧义]、[冲突]、[假设] - 如果不存在 ID 系统:“是否建立了需求与验收标准 ID 方案?[可追溯性]”
暴露并解决问题(需求质量问题): 提出关于需求本身的问题:
- 歧义:“‘快速’一词是否用具体指标量化了?[歧义,规范 §NFR-1]”
- 冲突:“导航需求在 §FR-10 和 §FR-10a 之间是否存在冲突?[冲突]”
- 假设:“是否验证了‘播客 API 始终可用’的假设?[假设]”
- 依赖项:
- 如果不存在,则创建
…
[为翻译而截断]