/checklist

检查清单目的："英文单元测试"

关键概念：检查清单是需求编写的单元测试 - 它们在给定的域中验证需求的质量、清晰度和完整性。

不是用于验证/测试：

• ❌ 不是"验证按钮点击是否正常工作"
• ❌ 不是"测试错误处理是否有效"
• ❌ 不是"确认 API 返回 200"
• ❌ 不是检查代码/实现是否与规范匹配

用于需求质量验证：

• ✅ "是否为所有卡类型定义了视觉层级需求？"（完整性）
• ✅ "是否使用特定的尺寸/位置量化了'突出显示'？"（清晰度）
• ✅ "所有交互元素的悬停状态需求是否一致？"（一致性）
• ✅ "是否为键盘导航定义了无障碍需求？"（覆盖范围）
• ✅ "规范是否定义了徽标图像加载失败时会发生什么？"（边界情况）

隐喻：如果您的规范是用英文编写的代码，检查清单就是它的单元测试套件。您正在测试需求是否编写良好、完整、明确且可以实现 - 而不是实现是否有效。

用户输入

$ARGUMENTS

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

执行步骤

1. 设置：从 repo 根目录运行 $HOME/.claude/scripts/specify/check-prerequisites.sh --json，并解析 JSON 中的 FEATURE_DIR 和 AVAILABLE_DOCS 列表。

   • 所有文件路径必须是绝对路径。
   • 对于参数中的单引号，例如 "I'm Groot"，使用转义语法：例如 'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. 澄清意图（动态）：从用户的措辞 + 从 spec/plan/tasks 中提取的信号派生最多三个初始上下文澄清问题。它们必须：

   • 从用户的措辞 + 从规范/计划/任务中提取的信号生成
   • 仅询问显著改变检查清单内容的信息
   • 如果 $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 个场景类（替代 / 异常 / 恢复 / 非功能域）仍然不清楚，您可以提出最多两个针对性的后续问题（Q4/Q5），每个都有一行理由（例如"未解决的恢复路径风险"）。不要超过五个总问题。如果用户明确拒绝更多，则跳过升级。

3. 理解用户请求：组合 $ARGUMENTS + 澄清答案：

   • 派生检查清单主题（例如安全、审核、部署、ux）
   • 合并用户提及的明确必备项
   • 将焦点选择映射到类别脚手架
   • 从规范/计划/任务推断任何缺失的背景（不要幻觉）

4. 加载功能背景：从 FEATURE_DIR 读取：

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

   背景加载策略：

   • 仅加载与活跃焦点区域相关的必要部分（避免全文转储）
   • 倾向于将长部分总结为简洁的场景/需求项目
   • 使用渐进式披露：仅在检测到间隙时添加后续检索
   • 如果源文档很大，生成中期摘要项目而不是嵌入原始文本

5. 生成检查清单 - 创建"需求的单元测试"：

   • 如果不存在，创建 FEATURE_DIR/checklists/ 目录
   • 生成唯一的检查清单文件名：
     • 使用基于域的简短、描述性名称（例如 ux.md、api.md、security.md）
     • 格式：[domain].md
     • 如果文件存在，追加到现有文件
   • 按顺序编号项目，从 CHK001 开始
   • 每个 /spec-kit:checklist 运行创建一个新文件（从不覆盖现有检查清单）

   核心原则 - 测试需求，而不是实现： 每个检查清单项必须评估需求本身以了解：

   • 完整性：是否存在所有必要的需求？
   • 清晰度：需求是否明确且具体？
   • 一致性：需求是否彼此一致？
   • 可测量性：需求是否可以客观验证？
   • 覆盖范围：所有场景/边界情况是否都已解决？

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

   • 需求完整性（是否记录了所有必要的需求？）
   • 需求清晰度（需求是否具体且明确？）
   • 需求一致性（需求是否一致且无冲突？）
   • 验收标准质量（成功标准是否可测量？）
   • 场景覆盖（所有流程/情况是否都已解决？）
   • 边界情况覆盖（边界条件是否已定义？）
   • 非功能需求（性能、安全、无障碍等 - 是否已指定？）
   • 依赖关系与假设（它们是否已记录和验证？）
   • 模糊性与冲突（什么需要澄清？）

   如何编写检查清单项 - "英文单元测试"：

   ❌ 错误（测试实现）：

   • "验证登陆页面显示 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% 的项必须包含至少一个可追溯性引用
   • 每个项应参考：规范部分 [Spec §X.Y]，或使用标记：[Gap]、[歧义]、[冲突]、[假设]
   • 如果不存在 ID 系统："是否建立了需求和验收标准 ID 方案？[可追溯性]"

   表面与解决问题（需求质量问题）： 询问关于需求本身的问题：

   • 歧义："是否用具体的指标量化了术语'快速'？[歧义, Spec §NFR-1]"
   • 冲突："导航需求在 §FR-10 和 §FR-10a 之间是否冲突？[冲突]"
   • 假设："'始终可用的播客 API'的假设是否已验证？[假设]"
   • 依赖关系："外部播客 API 需求是否已记录？[依赖关系, Gap]"
   • 缺失定义："'视觉层级'是否用可测量的标准定义？[Gap]"

   内容合并：

   • 软上限：如果原始候选项 > 40，按风险/影响优先排序
   • 合并接近重复项，检查相同的需求方面
   • 如果 >5 个低影响边界情况，创建一个项：在需求中是否解决了边界情况 X、Y、Z？[覆盖范围]"

   🚫 绝对禁止 - 这会使其成为实现测试，而不是需求测试：

   • ❌ 任何以"验证"、"测试"、"确认"、"检查" + 实现行为开头的项
   • ❌ 对代码执行、用户操作、系统行为的引用
   • ❌ "正确显示"、"正常工作"、"符合预期"
   • ❌ "点击"、"导航"、"呈现"、"加载"、"执行"
   • ❌ 测试用例、测试计划、QA 程序
   • ❌ 实现细节（框架、API、算法）

   ✅ 必需的模式 - 这些测试需求质量：

   • ✅ "是否为[情景]定义/指定/记录了[需求类型]？"
   • ✅ "是否使用具体标准量化/澄清了[模糊术语]？"
   • ✅ "需求在[第 A 部分]和[第 B 部分]之间是否一致？"
   • ✅ "[需求]是否可以客观测量/验证？"
   • ✅ "需求中是否解决了[边界情况/场景]？"
   • ✅ "规范是否定义了[缺失方面]？"

6. 结构参考：使用 $HOME/.claude/templates/specify/checklist-template.md 中的规范模板生成检查清单，用于标题、元部分、类别标题和 ID 格式。如果模板不可用，使用：H1 标题、目的/创建日期元行、包含全局递增 ID（从 CHK001 开始）的 ## 类别部分包含 - [ ] CHK### <需求项> 行。

7. 报告：输出创建的检查清单的完整路径、项目计数，并提醒用户每次运行创建一个新文件。摘要：

   • 选定的焦点区域
   • 深度等级
   • 参与者/时间
   • 任何用户指定的必备项合并

重要：每个 /spec-kit:checklist 命令调用使用简短的、描述性的名称创建一个检查清单文件，除非文件已存在。这允许：

• 不同类型的多个检查清单（例如 ux.md、test.md、security.md）
• 简单的、可记忆的文件名，指示检查清单目的
• 轻松识别和导航 checklists/ 文件夹

为了避免混乱，使用描述性类型并在完成时清理过时的检查清单。

示例检查清单类型与示例项

UX 需求质量：ux.md

示例项（测试需求，而不是实现）：

• "是否用可测量的标准定义了视觉层级需求？[清晰度, Spec §FR-1]"
• "是否明确指定了 UI 元素的数量和位置？[完整性, Spec §FR-1]"
• "交互状态需求（悬停、焦点、活跃）是否一致定义？[一致性]"
• "是否为所有交互元素指定了无障碍需求？[覆盖范围, Gap]"
• "图像加载失败时的备选行为是否已定义？[边界情况, Gap]"
• "'突出显示'是否可以客观测量？[可测量性, Spec §FR-4]"

API 需求质量：api.md

示例项：

• "是否为所有故障场景指定了错误响应格式？[完整性]"
• "速率限制需求是否用具体阈值量化？[清晰度]"
• "所有端点的认证需求是否一致？[一致性]"
• "是否为外部依赖定义了重试/超时需求？[覆盖范围, Gap]"
• "版本控制策略是否在需求中记录？[Gap]"

性能需求质量：performance.md

示例项：

• "性能需求是否用具体指标量化？[清晰度]"
• "是否为所有关键用户旅程定义了性能目标？[覆盖范围]"
• "是否指定了不同负载条件下的性能需求？[完整性]"
• "性能需求是否可以客观测量？[可测量性]"
• "高负载场景的降级需求是否已定义？[边界情况, Gap]"

安全需求质量：security.md

示例项：

• "是否为所有受保护的资源指定了认证需求？[覆盖范围]"
• "是否为敏感信息定义了数据保护需求？[完整性]"
• "威胁模型是否已记录且需求与其对齐？[可追溯性]"
• "安全需求是否与合规义务一致？[一致性]"
• "是否定义了安全故障/漏洞响应需求？[Gap, 异常流]"

反面示例：不要做什么

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

- [ ] CHK001 - 验证登陆页面显示 3 个情节卡 [Spec §FR-001]
- [ ] CHK002 - 测试悬停状态在桌面上正常工作 [Spec §FR-003]
- [ ] CHK003 - 确认徽标点击导航到主页 [Spec §FR-010]
- [ ] CHK004 - 检查相关情节部分显示 3-5 个项 [Spec §FR-005]

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

- [ ] CHK001 - 特色情节的数量和布局是否明确指定？[完整性, Spec §FR-001]
- [ ] CHK002 - 所有交互元素的悬停状态需求是否一致定义？[一致性, Spec §FR-003]
- [ ] CHK003 - 所有可点击品牌元素的导航需求是否清楚？[清晰度, Spec §FR-010]
- [ ] CHK004 - 相关情节的选择标准是否已记录？[Gap, Spec §FR-005]
- [ ] CHK005 - 异步情节数据的加载状态需求是否已定义？[Gap]
- [ ] CHK006 - '视觉层级'需求是否可以客观测量？[可测量性, Spec §FR-001]

关键差异：

• 错误：测试系统是否工作正常
• 正确：测试需求是否编写正确
• 错误：行为验证
• 正确：需求质量验证
• 错误："它是否做到了 X？"
• 正确："X 是否清楚指定？"