checklist

模板： 如果需要下文提及的模板文件（spec-template.md、plan-template.md 等），可在 BB-Skills 仓库的 templates/ 中找到。如果已在本地安装，请检查 ~/.bb-skills/templates/ 或项目的 templates/ 目录。

检查清单的目的：“英文需求的单元测试”

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

不是用于验证/测试：

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

用于验证需求质量：

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

比喻：如果规格说明是用英文编写的代码，那么检查清单就是它的单元测试套件。你要测试的是需求是否写得完善、完整、明确无歧义，并已准备好交付实现——而不是实现是否有效。

用户输入

$ARGUMENTS

如果用户输入不为空，必须先考虑该输入再继续。

执行步骤

1. 准备：定位当前功能目录并确认可用文档。解析 FEATURE_DIR 和 AVAILABLE_DOCS 列表。

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

2. 澄清意图（动态）：根据上下文提出最多三个初步澄清问题（不得使用预设问题目录）。这些问题必须：

   • 根据用户的措辞以及从规格说明/计划/任务中提取的信号生成
   • 只询问会实质性影响检查清单内容的信息
   • 如果 $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 个。如果用户明确拒绝继续提问，则跳过后续提问。

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

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

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

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

   上下文加载策略：

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

5. 生成检查清单——创建“需求的单元测试”：

   • 如果 FEATURE_DIR/checklists/ 目录不存在，则创建该目录
   • 生成唯一的检查清单文件名：
     • 使用简短且能描述领域的名称（例如：ux.md、api.md、security.md）
     • 格式：[domain].md
     • 如果文件已存在，则追加到现有文件
   • 从 CHK001 开始为条目连续编号
   • 每次运行检查清单都创建一个新文件（绝不覆盖现有检查清单）

   核心原则——测试需求，而非实现： 每个检查清单条目都必须评估需求本身的：

   • 完整性：是否涵盖所有必要需求？
   • 清晰度：需求是否明确且具体？
   • 一致性：各项需求是否相互一致？
   • 可衡量性：能否客观地验证需求？
   • 覆盖度：是否涵盖所有场景／边界情况？

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

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

   如何编写检查清单条目——“英语需求的单元测试”：

   错误（测试实现）：

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

   正确（测试需求质量）：

   • “是否明确规定了精选剧集的确切数量和布局？”[完整性]
   • “是否通过具体的尺寸／位置说明量化了‘醒目展示’？”[清晰度]
   • “所有交互元素的悬停状态需求是否一致？”[一致性]
   • “是否定义了所有交互式 UI 的键盘导航需求？”[覆盖度]
   • “徽标图像加载失败时的回退行为是否有明确说明？”[边界情况]
   • “是否为异步剧集数据定义了加载状态？”[完整性]
   • “规格说明是否定义了相互竞争的 UI 元素之间的视觉层级？”[清晰度] 条目结构： 每个条目都应遵循以下模式：
   • 采用询问需求质量的疑问句式
   • 关注规格说明/计划中写了（或没写）什么
   • 在方括号中注明质量维度 [Completeness/Clarity/Consistency 等]
   • 检查现有需求时，引用规格说明章节 [Spec X.Y]
   • 检查缺失需求时，使用 [Gap] 标记

   各质量维度示例：

   完整性：

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

   清晰性：

   • “‘快速加载’是否以具体的时间阈值量化？[Clarity, Spec NFR-2]”
   • “是否明确定义了‘相关剧集’的选择标准？[Clarity, Spec FR-5]”
   • “是否用可衡量的视觉属性定义了‘突出’？[Ambiguity, Spec FR-4]”

   一致性：

   • “各页面的导航需求是否一致？[Consistency, Spec FR-10]”
   • “落地页和详情页的卡片组件需求是否一致？[Consistency]”

   覆盖范围：

   • “是否针对零状态场景（没有剧集）定义了需求？[Coverage, Edge Case]”
   • “是否考虑了并发用户交互场景？[Coverage, Gap]”
   • “是否针对部分数据加载失败指定了需求？[Coverage, Exception Flow]”

   可衡量性：

   • “视觉层级需求是否可衡量、可测试？[Acceptance Criteria, Spec FR-1]”
   • “能否客观验证‘视觉权重均衡’？[Measurability, Spec FR-2]”

   场景分类与覆盖范围（聚焦需求质量）：

   • 检查是否存在以下场景的需求：主要、替代、异常/错误、恢复、非功能性场景
   • 针对每种场景类别，询问：“[场景类型]需求是否完整、清晰且一致？”
   • 如果缺少某种场景类别：“是否有意排除了[场景类型]需求，还是遗漏了？[Gap]”
   • 如果涉及状态变更，则包括恢复能力/回滚：“是否为迁移失败定义了回滚需求？[Gap]”

   可追溯性要求：

   • 最低要求：至少 80% 的条目必须包含至少一个可追溯性引用
   • 每个条目都应引用规格说明章节 [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] 中的需求是否一致？”
   • “是否可以客观地衡量／验证 [需求]？”
   • “是否在需求中涵盖了 [边缘情况／场景]？”
   • “规格说明是否定义了 [缺失方面]？”

6. 结构参考：按照规范模板生成检查清单，模板应包含标题、元信息部分、类别标题和 ID 格式。如果没有模板，请使用以下格式：H1 标题、用途／创建时间元信息行，以及包含 - [ ] CHK### <requirement item> 条目的 ## 类别章节，ID 从 CHK001 开始全局递增。

7. 报告：输出所创建检查清单的完整路径、条目数量，并提醒用户每次运行都会创建一个新文件。总结：

   • 选择的重点领域
   • 深度级别
   • 执行者／时机
   • 已纳入的任何用户明确指定的必备事项

重要：每次调用检查清单技能都会使用简短且描述性强的名称创建一个检查清单文件，除非该文件已存在。这样可以：

• 创建多种类型的检查清单（例如 ux.md、test.md、security.md）
• 使用简单、易记的文件名来体现检查清单的用途
• 轻松识别和浏览 checklists/ 文件夹

为避免内容杂乱，请使用描述性类型，并在完成后清理过时的检查清单。

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

UX 需求质量： ux.md

样例（检验需求，而非实现）：

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