speckit-checklist

speckit-checklist

本技能内容源自 GitHub Spec Kit 官方提示词模板。

• 上游：https://github.com/github/spec-kit
• 许可：MIT License, Copyright GitHub, Inc.（完整文本见同目录 LICENSE.txt）
• 适配说明：官方模板面向斜杠命令场景；原文中的 $ARGUMENTS 指用户在对话中给出的请求， 跨命令引用（如 speckit.plan）在本技能体系中对应同名的 speckit-* 技能。 其余内容保持与上游一致，未作改写。

---

清单目的：“英文的单元测试”

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

不用于验证或测试：

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

用于验证需求质量：

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

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

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

• 此命令生成的自定义清单由审查者负责维护，属于需求质量审查产物。
• [x] 表示审查者判定需求质量标准已满足。
• [x] 不表示实现工作已完成。
• 此命令会生成或追加清单项；它不得将生成的项目标记为 [x]。
• 只有在审查者明确要求时，Agent 才能协助评估清单项。
• checklists/requirements.md 是单独的内置规范质量清单，由 __SPECKIT_COMMAND_SPECIFY__ 和 __SPECKIT_COMMAND_CLARIFY__ 维护；不要将此例外视为适用于此处生成的自定义清单。

用户输入

$ARGUMENTS

如果用户输入不为空，你必须在继续之前予以考虑。

执行前检查

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

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，读取该文件，并查找 hooks.before_checklist 键下的条目
• 如果无法解析 YAML 或其格式无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（包括解析器错误），且未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后正常继续
• 过滤掉 enabled 明确设为 false 的钩子。未包含 enabled 字段的钩子默认视为已启用。
• 对于其余每个钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估交由 HookExecutor 实现处理
• 对于每个可执行钩子，根据其 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. 设置：从仓库根目录运行 {SCRIPT}，并解析 JSON 以获取 FEATURE_DIR、AVAILABLE_DOCS 列表和 TEMPLATE_CONTENT。

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

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

3. 澄清意图（动态）：根据用户的表述以及从 spec/plan/tasks 中提取的信号，生成至多三个初始上下文澄清问题（不得使用预设问题目录）。这些问题必须：

   • 根据用户的措辞以及从 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 类场景（替代／异常／恢复／非功能领域）不明确，可再提出最多 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% 的条目必须至少包含一个可追溯性引用
   • 每个条目都应引用：规范章节 [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. 结构参考：生成检查清单时，标题、元信息部分、类别标题、所有权说明、备注部分和 ID 格式均遵循规范模板 templates/checklist-template.md。如果模板不可用，则使用：H1 标题、用途／创建时间元信息行、说明 [x] 表示评审者认可需求质量的所有权说明、包含 - [ ] CHK### <requirement item> 行且 ID 从 CHK001 开始全局递增的 ## 类别章节，以及说明 __SPECKIT_COMMAND_IMPLEMENT__ 会读取检查清单状态但不会修改标记的备注。

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

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

重要：每次调用 __SPECKIT_COMMAND_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 或其格式无效，请勿默默跳过：告知用户无法读取 .specify/extensions.yml（包含解析器错误），并说明未检查任何钩子，包括在那里注册的任何强制（optional: false）钩子，然后正常继续
• 过滤掉 enabled 明确为 false 的钩子。未设置 enabled 字段的钩子默认视为已启用。
• 对于其余每个钩子，不要尝试解释或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空值，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 对于每个可执行钩子，根据其 optional 标志输出以下内容：
  • 可选钩子（optional: true）：

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • 强制钩子（optional: false）：

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

    输出上述代码块后，你必须实际调用该钩子，并等待其执行完毕后再继续。调用方式应与在此 Agent/会话中自行运行该命令的方式相同（调用形式可能不同于上方显示的字面 {command} ID，例如，技能模式下的 Agent 会以 /skill:speckit-... 或 $speckit-... 的形式运行）。 仅输出代码块并不能运行该钩子。
• 如果未注册任何钩子，或 .specify/extensions.yml 不存在，则静默跳过