[CHECKLIST TYPE] Checklist: [FEATURE NAME]

Purpose: [Brief description of what this checklist covers] Created: [DATE] Feature: [Link to spec.md or relevant documentation]

Note: This custom checklist is generated by the __SPECKIT_COMMAND_CHECKLIST__ command based on feature context and requirements. Review Ownership: This checklist is a reviewer-owned requirements-quality review artifact. Mark an item [x] only when the reviewer determines the requirements-quality criterion is satisfied. Marker Semantics: [x] means the criterion has been reviewed and satisfied for requirements quality. It does not mean implementation work is complete.

并配有分类小节与连续编号项：

```markdown
## [Category 1]

- [ ] CHK001 First checklist item with clear action
- [ ] CHK002 Second checklist item
- [ ] CHK003 Third checklist item

模板末尾的 Notes 部分还固化了两条下游契约：/speckit.implement 只读清单项状态作为门禁、不得修改标记；checklists/requirements.md 拥有独立的内置生命周期。

命令 Frontmatter 与前置检查脚本

checklist.md 文件头部的 YAML frontmatter 声明了命令描述与三套等价的预检脚本：

---
description: Generate a custom checklist for the current feature based on user requirements.
scripts:
  sh: scripts/bash/check-prerequisites.sh --json --template checklist-template
  ps: scripts/powershell/check-prerequisites.ps1 -Json -Template checklist-template
  py: scripts/python/check_prerequisites.py --json --template checklist-template
---

执行命令时，$ARGUMENTS 会被填入用户的原始输入，{SCRIPT} 会被替换为上述对应平台的脚本路径。这组脚本是 Spec Kit 各核心命令共享的"前置检查"基础设施，仓库中同时提供 Bash/PowerShell/Python 三种实现：

• scripts/bash/check-prerequisites.sh
• scripts/powershell/check-prerequisites.ps1
• scripts/python/check_prerequisites.py

以 Bash 版本为例，脚本头部注释列出了其参数面：

参数	作用
--json	以 JSON 格式输出结果
--require-spec	要求 spec.md 存在（分析阶段用）
--require-tasks	要求 tasks.md 存在（实现阶段用）
--include-tasks	将 tasks.md 纳入 AVAILABLE_DOCS 列表
--paths-only	只输出路径变量，不做校验
--template NAME	在 JSON 输出中附带组合后的模板内容

checklist 命令使用的是 --json --template checklist-template 组合：解析出当前 feature 的路径与可用文档列表，同时把 checklist-template.md 的内容作为 TEMPLATE_CONTENT 一并返回。脚本内部的 get_feature_paths 负责定位 FEATURE_DIR（结合 Git 分支与 .specify/feature.json），--paths-only 模式下还会通过 --no-persist 规避 feature.json 的写入副作用（见脚本第 100 行附近的注释）。Python 版本 check_prerequisites.py 通过 common.py 中的 get_feature_paths 与 resolve_template_content 实现同一逻辑，三种语言在参数解析行为上保持一致。

执行流程逐步骤解析

checklist.md 的 "Execution Steps" 部分定义了完整的 8 步流程。下面按原文顺序展开，并补齐每步的操作细节。

1. 前置检查与扩展钩子

进入执行步骤前，命令要求先检查项目根目录的 .specify/extensions.yml 是否存在，并读取 hooks.before_checklist 键下的钩子：

• YAML 无法解析或非法时，静默跳过钩子检查并正常继续；
• enabled: false 的钩子被过滤，没有 enabled 字段的默认视为启用；
• 命令不解释、不评估钩子的 condition 表达式：无 condition（或为 null/空）视为可执行；带非空 condition 的钩子交由 HookExecutor 实现处理；
• 可选钩子（optional: true）只输出提示块（含命令、描述与 Prompt:），由用户决定是否执行；
• 强制钩子（optional: false）输出 EXECUTE_COMMAND: {command} 块后，必须真正调用该命令并等待其结束——仅输出块并不会执行钩子，且调用方式可能与字面命令 id 不同（例如 skills 模式下的 agent 会以 /skill:speckit-... 或 $speckit-... 形式运行）。

没有注册钩子或 extensions.yml 不存在时同样静默跳过。

2. 运行前置脚本并加载上下文

第一步执行 {SCRIPT}（即上面 frontmatter 中的三选一脚本），从 JSON 中解析 FEATURE_DIR、AVAILABLE_DOCS 列表与 TEMPLATE_CONTENT，并要求所有文件路径为绝对路径；对含单引号的参数（如 I'm Groot）使用转义语法 'I'\''m Groot' 或改用双引号。

第二步若 /memory/constitution.md 存在则加载，用于引入项目原则与治理约束。

3. 动态澄清问题（最多 3 个初始问题）

这是该命令中最具"自适应"设计的一步：不预置问题目录，而是从用户措辞加上 spec/plan/tasks 中提取的信号，动态生成至多 3 个上下文澄清问题。生成算法分为五步：

1. 提取信号：feature 领域关键词（auth、latency、UX、API 等）、风险指示词（"critical"、"must"、"compliance"）、利益相关者线索（QA、review、security team）、显式交付物（a11y、rollback、contracts）；
2. 聚类：信号聚成至多 4 个候选关注域并按相关性排序；
3. 推断受众与时机：author、reviewer、QA、release 等；
4. 检测缺失维度：范围广度、深度/严格度、风险侧重、排除边界、可度量的验收标准；
5. 从以下原型中选题提问：范围细化、风险优先级、深度校准、受众定位、边界排除、场景类缺口（例如"未发现恢复流程——回滚/部分失败路径是否在范围内？"）。

格式规则同样明确：

• 呈现选项时生成紧凑表格，列为 Option | Candidate | Why It Matters，选项最多 A–E；自由文本回答更清晰时则省略表格；
• 绝不要求用户复述已说过的内容；
• 避免臆测分类，不确定时显式提问："确认 X 是否属于范围内。"

当无法交互时的默认值：深度取 Standard，受众取 Reviewer（PR 相关）否则 Author，关注点取相关性前 2 的聚类。输出问题标记为 Q1/Q2/Q3；若回答后仍有 ≥2 个场景类（Alternate / Exception / Recovery / Non-Functional）不明确，允许追加最多 2 个追问（Q4/Q5），每个附一行理由（如"Recovery path 风险未解决"），总数不超过 5 个；用户明确拒绝追问时不再升级。

4. 理解用户请求

将 $ARGUMENTS 与澄清答案合并后：推导清单主题（security、review、deploy、ux 等）、汇总用户显式点名的 must-have 项、把关注域选择映射到分类骨架、从 spec/plan/tasks 推断缺失上下文（不允许幻觉）。

5. 加载 feature 上下文

从 FEATURE_DIR 读取：spec.md（需求与范围）、plan.md（技术细节与依赖，若存在）、tasks.md（实现任务，若存在）。上下文加载策略强调渐进披露：只读取与当前关注域相关的片段、优先把长段落摘要为精炼的需求要点、仅在发现缺口时追加检索、源文档过大时生成中间摘要项而非嵌入原文。

6. 生成清单：核心规则全解

这是整篇模板信息密度最高的部分。生成的文件写入 FEATURE_DIR/checklists/ 目录，文件处理行为为：

• 文件名采用短而有描述的领域名，格式为 [domain].md（如 ux.md、api.md、security.md）；
• 文件不存在：新建，编号从 CHK001 开始；
• 文件已存在：追加新项，从最后一个 CHK ID 之后继续（若末项是 CHK015，新项从 CHK016 开始）；
• 永不删除或替换已有内容——始终保留并追加；
• 所有新生成项保持未勾选（[ ]），勾选状态属于评审者。

五项质量维度（每条清单项必须评估需求本身）：完整性（必要需求是否齐全）、清晰度（是否无歧义且具体）、一致性（需求之间是否自洽）、可度量性（能否客观验证）、覆盖度（场景/边界是否都覆盖）。

九大分类结构，按需求质量维度分组：

1. Requirement Completeness（必要需求是否都已记录）
2. Requirement Clarity（需求是否具体无歧义）
3. Requirement Consistency（需求间是否无冲突）
4. Acceptance Criteria Quality（成功标准是否可度量）
5. Scenario Coverage（各流程/用例是否覆盖）
6. Edge Case Coverage（边界条件是否定义）
7. Non-Functional Requirements（性能、安全、无障碍等是否写明）
8. Dependencies & Assumptions（是否记录并经过验证）
9. Ambiguities & Conflicts（哪些需要澄清）

条目书写规范（"Unit Tests for English"）：

• 错误示范（在测实现）："Verify landing page displays 3 episode cards"、"Test hover states work on desktop"；
• 正确示范（在测需求质量）："Are the exact number and layout of featured episodes specified? [Completeness]"、"Is 'prominent display' quantified with specific sizing/positioning? [Clarity]"。

每条项的结构：以疑问句形式询问需求质量；聚焦 spec/plan 中写了什么（或没写什么）；方括号标注质量维度 [Completeness/Clarity/Consistency/etc.]；检查既有需求时引用 spec 章节 [Spec §X.Y]；检查缺失需求时使用 [Gap] 标记。

模板还给出了按质量维度分类的条目示例（节选）：

• Completeness："Are error handling requirements defined for all API failure modes? [Gap]"
• Clarity："Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
• Consistency："Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
• Coverage："Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
• Measurability："Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"

场景分类与覆盖：检查 Primary、Alternate、Exception/Error、Recovery、Non-Functional 五类场景的需求是否存在；某场景类缺失时写入 "Are [scenario type] requirements intentionally excluded or missing? [Gap]"；涉及状态变更时补一条韧性/回滚检查。

可追溯性要求（硬性指标）：

• 至少 80% 的条目必须包含至少一个可追溯性引用；
• 引用形式为 spec 章节 [Spec §X.Y]，或标记 [Gap]、[Ambiguity]、[Conflict]、[Assumption]；
• 若项目尚无 ID 体系，应包含一条 "Is a requirement & acceptance criteria ID scheme established? [Traceability]"。

问题暴露（针对需求本身）：歧义（"'fast' 是否已量化？[Ambiguity, Spec §NFR-1]"）、冲突（"§FR-10 与 §FR-10a 是否冲突？[Conflict]"）、假设（"podcast API 始终可用的假设是否验证过？[Assumption]"）、依赖、缺失定义。

内容收敛：候选项超过 40 条时按风险/影响做软性截断并合并近似重复；超过 5 条低影响边界情况时合并为一条 "Are edge cases X, Y, Z addressed in requirements? [Coverage]"。

绝对禁止模式（一旦出现就沦为实现测试）：以 "Verify/Test/Confirm/Check + 实现行为" 开头的项；涉及代码执行、用户操作、系统行为的描述；"displays correctly"、"works properly" 之类措辞；"click/navigate/render/load/execute" 等动词；测试用例、QA 流程；框架/API/算法等实现细节。

必需模式（需求质量测试的标准句式）：

"Are [requirement type] defined/specified/documented for [scenario]?"
"Is [vague term] quantified/clarified with specific criteria?"
"Are requirements consistent between [section A] and [section B]?"
"Can [requirement] be objectively measured/verified?"
"Are [edge cases/scenarios] addressed in requirements?"
"Does the spec define [missing aspect]?"

7. 结构参考与 8. 报告

第 7 步要求按 checklist-template.md 的规范结构生成标题、元信息、分类标题、所有权说明、Notes 小节与 ID 格式；若模板不可用，则退化为最小结构：H1 标题、purpose/created 元信息行、所有权说明、## 分类小节内含从 CHK001 起全局递增的 - [ ] CHK### <requirement item> 行，以及"/speckit.implement 只读清单状态、不修改标记"的说明。

第 8 步要求报告：清单文件完整路径、条目数量、本次是新建还是追加，并总结选定的关注域、深度等级、受众/时机、以及用户显式指定的 must-have 项的落实情况。

每次调用都使用短而有描述的文件名并支持多份清单并存（ux.md、test.md、security.md），便于在 checklists/ 目录中快速定位；文档同时提醒：用完及时清理过期清单，避免目录杂乱。

反例对照：同一功能的两套写法

模板最后用 "Anti-Examples" 一节给出完整对照。错误写法（在测实现）：

- [ ] 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]

两者的本质区别可以浓缩为一句：错误写法回答 "Does it do X?"，正确写法回答 "Is X clearly specified?"——前者是行为验证，后者是需求质量验证。

典型清单类型与样例条目

文档给出了四个领域的成例，可直接作为生成时的参照基线：

UX 需求质量（ux.md）：

- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"

API 需求质量（api.md）：

- "Are error response formats specified for all failure scenarios? [Completeness]"
- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
- "Are authentication requirements consistent across all endpoints? [Consistency]"
- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
- "Is versioning strategy documented in requirements? [Gap]"

性能需求质量（performance.md）：

- "Are performance requirements quantified with specific metrics? [Clarity]"
- "Are performance targets defined for all critical user journeys? [Coverage]"
- "Are performance requirements under different load conditions specified? [Completeness]"
- "Can performance requirements be objectively measured? [Measurability]"
- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"

安全需求质量（security.md）：

- "Are authentication requirements specified for all protected resources? [Coverage]"
- "Are data protection requirements defined for sensitive information? [Completeness]"
- "Is the threat model documented and requirements aligned to it? [Traceability]"
- "Are security requirements consistent with compliance obligations? [Consistency]"
- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"

与流程其余环节的衔接

/speckit.checklist 不是孤立存在的，它在 SDD 命令链中的位置见 docs/reference/agentic-sdd.md：

/speckit.constitution -> /speckit.specify -> /speckit.clarify -> /speckit.plan
-> /speckit.checklist -> /speckit.tasks -> /speckit.analyze -> /speckit.implement
-> /speckit.converge

其中 clarify、checklist、analyze 属于"有实质歧义时才需要加上的质量门禁"。在 quickstart.md 的完整路径中，/speckit.checklist 位于 plan 与 tasks 之间，作用是"在拆解工作之前确认 spec 完整、清晰、一致"。三个相邻命令与清单的关系各有分工：

• /speckit.specify（specify.md）在创建 spec 时同步生成内置的 checklists/requirements.md 骨架（spec 质量清单），这是与自定义清单相互独立的第二套清单生命周期；
• /speckit.clarify（clarify.md）在对 spec 收紧后重新评估 FEATURE_DIR/checklists/requirements.md 的状态（如 "12/16 → 15/16 items passing"），该例外同样只适用于内置 requirements 清单，不触及自定义清单；
• /speckit.implement（implement.md）把 checklist 目录当作只读门禁：扫描 checklists/ 下所有文件，按 - [ ]/- [x]/- [X] 统计总数、已勾选与未勾选数，生成状态表（全部已勾选为 ✓ PASS，否则 ✗ FAIL）；存在未勾选项时停下并询问是否继续实现，且全程不修改任何清单文件或标记。

因此完整的闭环是：checklist 命令生成"需求质量测试" → 评审者（或其明确要求协助的 agent）逐条确认并勾选 → implement 命令在实现前以勾选状态为准入门禁。这正好呼应了 frontmatter 中 --template checklist-template 的存在——生成的产物从第一天起就携带了被下游消费的元信息与标记语义。

使用方式与适用前提

在已初始化的 Spec Kit 项目中（通过 specify init 生成 .specify/ 结构与对应 agent 命令文件），按 quickstart.md 与 agentic-sdd.md 的用法调用：

/speckit.checklist
/speckit.checklist Focus on the Kanban board interactions and comment permissions.