speckit-checklist

清单用途：“英文单元测试”

核心概念：清单是需求编写的单元测试——用于验证特定领域内需求的质量、清晰度和完整性。

不用于验证/测试：

• ❌ 不是“验证按钮是否能正确点击”
• ❌ 不是“测试错误处理是否有效”
• ❌ 不是“确认 API 是否返回 200”
• ❌ 不是检查代码/实现是否符合规范

用于验证需求质量：

• ✅ “是否为所有卡片类型定义了视觉层级要求？”（完整性）
• ✅ “是否用具体的尺寸/位置量化了‘醒目显示’？”（清晰度）
• ✅ “所有交互元素的悬停状态要求是否一致？”（一致性）
• ✅ “是否定义了键盘导航的无障碍要求？”（覆盖范围）
• ✅ “规范是否定义了徽标图像加载失败时的处理方式？”（边缘情况）

比喻：如果你的规范是用英文编写的代码，那么清单就是它的单元测试套件。你测试的是需求是否编写完善、完整、明确且已准备好实施——而不是实现是否有效。

所有权与复选框生命周期：

• 此命令生成的自定义清单由评审人员负责，属于需求质量评审材料。
• [x] 表示评审人员认定需求质量标准已满足。
• [x] 不表示实现工作已完成。
• 此命令会生成或追加清单项；绝不能将生成的项目标记为 [x]。
• 只有在评审人员明确提出要求时，Agent 才能协助评估清单项。
• checklists/requirements.md 是由 /speckit-specify 和 /speckit-clarify 维护的独立内置规范质量清单；不要将该例外套用于此处生成的自定义清单。

用户输入

$ARGUMENTS

继续之前，必须考虑用户输入（若非空）。

执行前检查

检查扩展钩子（生成检查清单之前）：

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，请读取该文件，并查找 hooks.before_checklist 键下的条目。
• 如果无法解析 YAML 或 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} ID 不同，例如，技能模式的 Agent 会将其作为 /skill:speckit-... 或 $speckit-... 运行）。仅输出该内容并不等于运行了钩子。

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

执行步骤

1. 设置：从仓库根目录运行 .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"）。

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

3. 明确意图（动态）：根据上下文拟定最多 THREE 个初始澄清问题（不使用预先编制的问题目录）。这些问题必须：

   • 根据用户的措辞以及从规范/计划/任务中提取的信号生成。
   • 仅询问会实质性改变检查清单内容的信息。
   • 如果 $ARGUMENTS 中已明确相关信息，则单独跳过对应问题。
   • 优先保证问题精准，不求面面俱到。 生成算法：
   1. 提取信号：领域关键词（例如 auth、latency、UX、API）、风险指标（“critical”“must”“compliance”）、利益相关方提示（“QA”“review”“security team”）以及明确的交付项（“a11y”“rollback”“contracts”）。
   2. 将信号聚类为候选重点领域（最多 4 个），并按相关性排序。
   3. 在未明确说明时，识别可能的受众和时间节点（作者、评审者、QA、发布）。
   4. 检测缺失维度：范围广度、深度／严谨程度、风险侧重、排除边界、可衡量的验收标准。
   5. 从以下问题类型中选择并拟定问题：
      • 范围细化（例如：“是否应涵盖与 X 和 Y 的集成接触点，还是仅限于本地模块的正确性？”）
      • 风险优先级排序（例如：“这些潜在风险领域中，哪些应设置强制门禁检查？”）
      • 深度校准（例如：“这是轻量级的提交前健全性检查清单，还是正式的发布门禁？”）
      • 受众界定（例如：“这只供作者使用，还是供同事在 PR 评审期间使用？”）
      • 排除边界（例如：“本轮是否应明确排除性能调优项？”）
      • 场景类别缺口（例如：“未检测到恢复流程——回滚／部分故障路径是否在范围内？”）

   问题格式规则：

   • 如果提供选项，请生成一个精简表格，列为：选项 | 候选项 | 重要性
   • 选项最多 A–E；如果开放式回答更清晰，则省略表格
   • 切勿要求用户重述他们已经说过的内容
   • 避免推测性类别（不得臆造）。如有不确定之处，请明确询问：“确认 X 是否属于范围。”

   无法进行交互时的默认值：

   • 深度：标准
   • 受众：与代码相关时为评审者（PR）；否则为作者
   • 重点：相关性最高的 2 个聚类

   输出问题（标记为 Q1/Q2/Q3）。收到回答后：如果仍有至少 2 类场景（替代／异常／恢复／非功能领域）不明确，可再提出最多 2 个有针对性的后续问题（Q4/Q5），并各附上一行理由（例如：“尚未解决的恢复路径风险”）。总问题数不得超过 5 个。如果用户明确拒绝继续提问，则跳过后续提问。

4. 理解用户请求：合并 $ARGUMENTS 和澄清答复：

   • 确定检查清单主题（例如安全、评审、部署、UX）
   • 汇总用户提及的明确必备项
   • 将重点选择映射到类别框架
   • 从规格说明／计划／任务中推断缺失的上下文（不得臆造）

5. 加载功能上下文：从 FEATURE_DIR 读取：

   • spec.md：功能需求和范围
   • plan.md（如果存在）：技术细节、依赖项
   • tasks.md（如果存在）：实施任务

   上下文加载策略：

   • 仅加载与当前重点领域相关的必要部分（避免倾倒整个文件）
   • 对较长章节，优先总结为简洁的场景／需求要点
   • 逐步披露：仅在发现缺口时检索后续内容
   • 如果源文档较大，则生成中间摘要条目，而不是嵌入原始文本

6. 生成检查清单——使用 TEMPLATE_CONTENT 作为结构模板，并创建“需求的单元测试”：

   • 如果 FEATURE_DIR/checklists/ 目录不存在，则创建该目录
   • 生成唯一的检查清单文件名：
     • 根据领域使用简短、明确的名称（例如 ux.md、api.md、security.md）
     • 格式：[domain].md
   • 文件处理行为：
     • 如果文件不存在：创建新文件，条目编号从 CHK001 开始
     • 如果文件已存在：在现有文件末尾追加新条目，接续最后一个 CHK ID（例如，最后一项为 CHK015，则从 CHK016 开始）
   • 切勿删除或替换现有检查清单内容——始终保留并追加
   • 所有新生成的条目都保持未勾选状态（[ ]）；复选框状态由评审者决定 核心原则——测试需求，而非实现方式： 每个检查清单项都必须评估需求本身的以下方面：
   • 完整性：是否涵盖了所有必要需求？
   • 清晰度：需求是否明确且具体？
   • 一致性：各项需求是否相互吻合？
   • 可衡量性：能否客观验证需求？
   • 覆盖范围：是否涵盖了所有场景和边界情况？

   类别结构——按需求质量维度对项目分组：

   • 需求完整性（是否记录了所有必要需求？）
   • 需求清晰度（需求是否具体且明确？）
   • 需求一致性（各项需求是否相互吻合且没有冲突？）
   • 验收标准质量（成功标准是否可衡量？）
   • 场景覆盖范围（是否涵盖了所有流程和情况？）
   • 边界情况覆盖范围（是否定义了边界条件？）
   • 非功能需求（是否明确规定了性能、安全性、无障碍性等要求？）
   • 依赖项与假设（是否记录并验证了这些内容？）
   • 歧义与冲突（哪些内容需要澄清？）

   如何编写检查清单项——“英语的单元测试”：

   ❌ 错误（测试实现方式）：

   • “确认首页显示 3 张剧集卡片”
   • “测试桌面端悬停状态是否正常”
   • “确认点击徽标后会跳转到主页”

   ✅ 正确（测试需求质量）：

   • “是否指定了精选剧集的确切数量和布局？”[完整性]
   • “是否通过具体的尺寸和位置量化了‘醒目显示’？”[清晰度]
   • “所有交互元素的悬停状态要求是否一致？”[一致性]
   • “是否为所有交互式 UI 定义了键盘导航要求？”[覆盖范围]
   • “徽标图像加载失败时是否指定了回退行为？”[边界情况]
   • “是否为异步剧集数据定义了加载状态？”[完整性]
   • “规范是否定义了相互竞争的 UI 元素之间的视觉层级？”[清晰度]

   条目结构： 每个条目都应遵循以下模式：

   • 采用提问形式，询问需求质量
   • 关注规范或计划中写明（或未写明）的内容
   • 在方括号中注明质量维度 [完整性/清晰度/一致性等]
   • 检查现有需求时，引用规范章节 [Spec §X.Y]
   • 检查缺失需求时，使用 [Gap] 标记

   各质量维度示例：

   完整性：

   • “是否为所有 API 故障模式定义了错误处理要求？[Gap]”
   • “是否为所有交互元素指定了无障碍性要求？[完整性]”
   • “是否为响应式布局定义了移动端断点要求？[Gap]”

   清晰度：

   • “是否通过具体的时间阈值量化了‘快速加载’？[清晰度，Spec §NFR-2]”
   • “是否明确定义了‘相关剧集’的选择标准？[清晰度，Spec §FR-5]”
   • “是否通过可衡量的视觉属性定义了‘醒目’？[歧义，Spec §FR-4]”

   一致性：

   • “各页面的导航要求是否一致？[一致性，Spec §FR-10]”
   • “首页和详情页的卡片组件要求是否一致？[一致性]”

   覆盖范围：

   • “是否为零状态场景（没有剧集）定义了相关需求？[覆盖范围，边界情况]”
   • “是否涵盖了用户并发交互场景？[覆盖范围，Gap]”
   • “是否针对部分数据加载失败指定了相关需求？[覆盖范围，异常流程]”

   可衡量性：

   • “视觉层级要求是否可衡量或可测试？[验收标准，Spec §FR-1]”
   • “‘均衡的视觉权重’能否得到客观验证？[可衡量性，Spec §FR-2]” 场景分类与覆盖（侧重需求质量）：
   • 检查是否存在以下场景的需求：主要场景、备选场景、异常／错误场景、恢复场景、非功能场景
   • 对每类场景，询问：“[场景类型]需求是否完整、清晰且一致？”
   • 如果缺少某类场景：“是否有意排除或遗漏了[场景类型]需求？[Gap]”
   • 状态发生变更时，包含弹性／回滚要求：“是否为迁移失败定义了回滚要求？[Gap]”

   可追溯性要求：

   • 最低要求：≥80% 的条目 MUST 至少包含一个可追溯性引用
   • 每个条目都应引用：规范章节 [Spec §X.Y]，或使用标记：[Gap]、[Ambiguity]、[Conflict]、[Assumption]
   • 如果没有 ID 体系：“是否已建立需求和验收标准的 ID 方案？[Traceability]”

   发现并解决问题（需求质量问题）： 针对需求本身提问：

   • 歧义：“是否用具体指标量化了‘快速’一词？[Ambiguity，Spec §NFR-1]”
   • 冲突：“§FR-10 和 §FR-10a 中的导航需求是否冲突？[Conflict]”
   • 假设：“‘播客 API 始终可用’这一假设是否经过验证？[Assumption]”
   • 依赖项：“是否记录了外部播客 API 的需求？[Dependency，Gap]”
   • 缺失的定义：“是否通过可衡量的标准定义了‘视觉层次结构’？[Gap]”

   内容整合：

   • 软上限：如果原始候选条目 > 40，则按风险／影响排序
   • 合并检查同一需求方面的近似重复项
   • 如果低影响边缘案例 >5 项，则合并为一项：“需求是否涵盖了 X、Y、Z 边缘案例？[Coverage]”

   🚫 严禁——以下内容会使其成为实现测试，而非需求测试：

   • ❌ 任何以“验证”“测试”“确认”“检查”+ 实现行为开头的条目
   • ❌ 引用代码执行、用户操作、系统行为
   • ❌ “显示正确”“运行正常”“功能符合预期”
   • ❌ “点击”“导航”“渲染”“加载”“执行”
   • ❌ 测试用例、测试计划、QA 流程
   • ❌ 实现细节（框架、API、算法）

   ✅ 必须采用的模式——这些模式用于测试需求质量：

   • ✅“是否为[场景]定义／指定／记录了[需求类型]？”
   • ✅“是否通过具体标准量化／阐明了[模糊术语]？”
   • ✅“[章节 A] 与 [章节 B] 中的需求是否一致？”
   • ✅“能否客观地衡量／验证[需求]？”
   • ✅“需求是否涵盖了[边缘案例／场景]？”
   • ✅“规范是否定义了[缺失方面]？”

7. 结构参考：按照 .specify/templates/checklist-template.md 中的规范模板生成检查清单，包括标题、元信息部分、类别标题、所有权说明、备注部分和 ID 格式。如果模板不可用，则使用：H1 标题、用途／创建时间元信息行、说明 [x] 表示审核者已认可需求质量的所有权说明、包含 - [ ] CHK### <requirement item> 行且 ID 全局递增并从 CHK001 开始的 ## 类别部分，以及说明 /speckit-implement 会读取检查清单状态但不会修改标记的备注。

8. 报告：输出检查清单文件的完整路径和条目数，并总结本次运行是创建了新文件还是追加到现有文件。总结：

   • 选定的关注领域
   • 深度级别
   • 参与者／时机
   • 已纳入的任何用户明确指定的必备项

重要：每次调用 /speckit-checklist 命令都应使用简短、描述性的检查清单文件名，并选择创建新文件或追加到现有文件。这样可以：

• 创建多个不同类型的检查清单（例如 ux.md、test.md、security.md）
• 使用简单易记的文件名表明检查清单用途
• 便于在 checklists/ 文件夹中查找和导航 为避免内容杂乱，请使用描述性类型，并在完成后清理过时的检查清单。

检查清单类型示例和样例条目

UX 需求质量： ux.md

样例条目（测试需求，而非实现）：

• “是否使用可衡量的标准定义了视觉层级要求？[清晰度，Spec §FR-1]”
• “是否明确规定了 UI 元素的数量和位置？[完整性，Spec §FR-1]”
• “是否一致地定义了交互状态要求（悬停、聚焦、激活）？[一致性]”
• “是否为所有交互元素指定了无障碍要求？[覆盖范围，缺漏]”
• “是否定义了图像加载失败时的回退行为？[边缘情况，缺漏]”
• “‘醒目显示’是否可以客观衡量？[可衡量性，Spec §FR-4]”

API 需求质量： api.md

样例条目：

• “是否为所有失败场景指定了错误响应格式？[完整性]”
• “是否使用具体阈值量化了速率限制要求？[清晰度]”
• “所有端点的身份验证要求是否一致？[一致性]”
• “是否为外部依赖定义了重试／超时要求？[覆盖范围，缺漏]”
• “是否在需求中记录了版本控制策略？[缺漏]”

性能需求质量： performance.md

样例条目：

• “是否使用具体指标量化了性能要求？[清晰度]”
• “是否为所有关键用户流程定义了性能目标？[覆盖范围]”
• “是否指定了不同负载条件下的性能要求？[完整性]”
• “性能要求是否可以客观衡量？[可衡量性]”
• “是否为高负载场景定义了性能降级要求？[边缘情况，缺漏]”

安全需求质量： security.md

样例条目：

• “是否为所有受保护资源指定了身份验证要求？[覆盖范围]”
• “是否为敏感信息定义了数据保护要求？[完整性]”
• “是否记录了威胁模型，且需求是否与之保持一致？[可追溯性]”
• “安全要求是否符合合规义务？[一致性]”
• “是否定义了安全故障／违规事件的响应要求？[缺漏，异常流程]”

反面示例：不要这样做

❌ 错误 - 这些测试的是实现，而非需求：

- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]

✅ 正确 - 这些测试的是需求质量：

- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]

主要区别：

• 错误：测试系统是否正常运行
• 正确：测试需求是否编写正确
• 错误：验证行为
• 正确：验证需求质量
• 错误：“它是否执行 X？”
• 正确：“X 是否得到了明确说明？”

执行后检查

检查扩展钩子（生成检查清单后）： 检查项目根目录中是否存在 .specify/extensions.yml。

• 如果存在，请读取该文件，并查找 hooks.after_checklist 键下的条目
• 如果无法解析 YAML 或 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} ID 不同，例如，技能模式的 Agent 会将其作为 /skill:speckit-... 或 $speckit-... 运行）。仅输出代码块并不算运行钩子。

• 如果未注册任何钩子，或 .specify/extensions.yml 不存在，则静默跳过