[CHECKLIST TYPE] Checklist: [FEATURE NAME]

2026-09-06 12:48:30作者：齐冠琰

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.

[Category 1]

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

[Category 2]

[ ] CHK004 Another category item
[ ] CHK005 Item with specific criteria
[ ] CHK006 Final item in this category

Notes

Mark items [x] only after review confirms the requirement-quality criterion is satisfied
Leave items unchecked when they still require clarification, correction, or reviewer evaluation
__SPECKIT_COMMAND_IMPLEMENT__ reads checklist checkbox state as a gate and must not modify markers
checklists/requirements.md has a separate built-in lifecycle maintained by __SPECKIT_COMMAND_SPECIFY__ and __SPECKIT_COMMAND_CLARIFY__
Add comments or findings inline
Link to relevant resources or documentation
Items are numbered sequentially for easy reference


### 2.1 H1 标题：`[CHECKLIST TYPE] Checklist: [FEATURE NAME]`

标题由两个占位符组成：清单类型（如 `UX`、`API`、`Security`、`Performance`）和功能名。命令侧要求生成“短小、描述性、按域命名”的文件名（`ux.md`、`api.md`、`security.md` 等），同一功能目录下可以并存多个不同类型的清单，因此标题中的类型需要与文件名语义一致，便于在 `checklists/` 目录中识别与导航。

### 2.2 元信息区：Purpose / Created / Feature

三行加粗元数据构成清单的“档案头”：

- **Purpose**：一句话说明这份清单覆盖什么评审范围（例如“评审 UX 需求的质量”），防止清单被误用为实现验收单；
- **Created**：生成日期，配合 CHK 编号追加规则可判断清单的演进历史；
- **Feature**：回链到 `spec.md` 或相关文档，建立清单与需求源文件之间的追溯关系。

### 2.3 归属与标记语义：模板中最关键的三条 Note

这三行 Note 是模板的“法律条款”，直接约束了后续所有工作流命令对清单的读写权限：

1. **生成来源声明**：清单由 `__SPECKIT_COMMAND_CHECKLIST__` 命令基于功能上下文与需求生成（`__SPECKIT_COMMAND_CHECKLIST__` 是安装期占位符，会替换为该项目实际注册的命令名，如 `/speckit.checklist`）；
2. **Review Ownership（评审者归属）**：清单是**评审者所有**的需求质量评审产物——只有评审者判定某条质量标准满足时才能打勾。命令生成或追加条目时**严禁**把新条目标记为 `[x]`，Agent 只有在评审者明确要求时才可协助评估；
3. **Marker Semantics（标记语义）**：`[x]` 表示“该需求质量标准已被评审且满足”，**绝不**表示实现工作已完成。

这套语义避免了 SDD 中最常见的概念混淆：把“需求写清楚了”误当成“功能做完了”。

### 2.4 示例条目注释块：必须被替换的占位区

模板中部用 HTML 注释框显式声明 CHK001–CHK006 是**仅为说明格式而存在的样例条目**，并列出生成真实条目时必须依据的四类输入：

- 用户的具体清单请求（`$ARGUMENTS`）；
- `spec.md` 中的功能需求；
- `plan.md` 中的技术上下文；
- `tasks.md` 中的实现细节。

注释最后强调 `DO NOT keep these sample items in the generated checklist file`。这是模板与命令之间的一条硬契约：命令侧 [templates/commands/checklist.md](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/templates/commands/checklist.md?utm_source=gitcode_repo_files) 的第 7 步（Structure Reference）明确要求生成结果“遵循 `templates/checklist-template.md` 中标题、meta 区、分类标题、归属说明、Notes 区与 ID 格式”的规范结构，同时第 6 步规定样例条目必须被真实条目替换。

### 2.5 分类标题与 CHK 编号体系

模板用 `## [Category 1]` / `## [Category 2]` 两级占位分类标题，条目采用 `- [ ] CHK###` 的统一格式：

- **分类维度**：命令侧给出的建议分类是“需求质量维度”，包括 Requirement Completeness（完整性）、Clarity（清晰性）、Consistency（一致性）、Acceptance Criteria Quality（验收标准质量）、Scenario Coverage（场景覆盖）、Edge Case Coverage（边界覆盖）、Non-Functional Requirements（非功能需求）、Dependencies & Assumptions（依赖与假设）、Ambiguities & Conflicts（歧义与冲突）；
- **编号规则**：`CHK` 前缀 + 三位递增序号（CHK001 起）。新清单从 CHK001 开始；若目标文件已存在，则**续接最后一条编号追加**（例如最后是 CHK015 则从 CHK016 继续），且永不删除或替换已有内容。全局递增的 ID 使得评审意见可以直接引用编号定位条目。

### 2.6 Notes 区：五条协作规则

模板尾部的 Notes 区把协作约定写死在每一份生成的清单里：

1. 评审确认需求质量标准满足后才允许 `[x]`；
2. 仍需澄清、修正或评审者评估的条目保持未勾选；
3. `__SPECKIT_COMMAND_IMPLEMENT__` 把清单勾选状态当作**门禁（gate）只读**，不得修改标记；
4. `checklists/requirements.md` 是内置的规格质量清单，生命周期由 `__SPECKIT_COMMAND_SPECIFY__` 与 `__SPECKIT_COMMAND_CLARIFY__` 维护，与本模板生成的**自定义**清单互不干涉；
5. 允许在条目旁内联书写评论/发现，并链接到相关资源文档。

## 三、模板如何被加载：`--template checklist-template` 解析栈

`__SPECKIT_COMMAND_CHECKLIST__` 命令的 frontmatter 声明了三套等价的前置脚本（见 [templates/commands/checklist.md](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/templates/commands/checklist.md?utm_source=gitcode_repo_files) 第 1–7 行）：

```yaml
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

执行第一步（Setup）时，Agent 在仓库根目录运行该脚本并解析 JSON 输出，其中关键字段为：

FEATURE_DIR：当前功能目录（由分支名解析得到）；
AVAILABLE_DOCS：当前功能可用的文档列表（research.md、data-model.md、contracts/、quickstart.md 等）；
TEMPLATE_CONTENT：组合后的 checklist-template 完整内容，即命令用来约束输出结构的“结构模板”。

在 scripts/bash/check-prerequisites.sh 中，--template 参数最终调用 resolve_template_content 完成模板解析（约 185–192 行），该函数定义于 scripts/bash/common.sh（约 610 行起）。从源码结构看，解析遵循一个优先级覆盖栈：

项目级 override：.specify/templates/overrides/checklist-template.md，策略恒为 replace，存在即直接返回；
已安装 preset：按 .specify/presets/.registry 中登记的 priority 排序，逐个读取 preset manifest（preset.yml）声明的模板合成策略（replace / prepend / append / wrap）逐层合成；
扩展模板（按注册顺序尝试）；
核心模板：.specify/templates/checklist-template.md，即 specify init 从 templates/checklist-template.md 复制来的基线。

此外还有前置校验：功能目录必须存在、plan.md 必须存在，否则脚本会以非零退出码报错并提示先运行 specify/plan 命令（scripts/bash/check-prerequisites.sh 约 139–149 行）。这解释了 checklist 命令的工作流位置——它运行在 specify 与 plan 之后，因为只有需求与计划就绪，清单才有可评审的对象。

模板名合法性也有约束：resolve_template_content 开头对模板名做 case ... in ""|*[!a-z0-9-]*) return 1 校验，只接受小写字母、数字和连字符，checklist-template 正符合该命名规范。

四、模板如何被填充：从占位符到真实清单

理解了加载机制后，命令侧如何“使用”这份模板可以归纳为以下几条硬规则（均来自 templates/commands/checklist.md）：

文件落点：FEATURE_DIR/checklists/ 目录下，文件名为 [domain].md（如 ux.md、api.md、security.md）；
创建或追加：文件不存在则新建并从 CHK001 开始编号；存在则追加、续接编号；
保持未勾选：所有新生成条目一律 [ ]，勾选权归属评审者——这正是模板 Note/Ownership 区的执行面；
结构对齐模板：标题、meta 区、归属说明、分类标题、Notes 区、ID 格式全部以 templates/checklist-template.md 为准；即使模板解析失败，命令也给出了兜底结构（H1 + purpose/created meta + 归属说明 + ## 分类 + - [ ] CHK### 条目 + implement 只读门禁的 Notes）；
条目内容规范：每条条目必须是“需求质量提问”而非实现验证，包含质量维度标签 [Completeness/Clarity/Consistency/...]、规格章节引用 [Spec §X.Y] 或缺口标记 [Gap]/[Ambiguity]/[Conflict]/[Assumption]，且至少 80% 的条目携带可追溯引用。

命令文档中的正误对比例子直观体现了模板要守护的边界：

❌ 错误（在测实现）
- [ ] CHK001 - Verify landing page displays 3 episode cards

✅ 正确（在测需求质量）
- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]

按质量维度，命令文档还给出了完整样例族（Completeness / Clarity / Consistency / Coverage / Measurability），例如：

“Are error handling requirements defined for all API failure modes? [Gap]”
“Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]”
“Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]”

这些条目形态与模板 Notes 区“items are numbered sequentially for easy reference”的引用友好性设计互为印证。

五、模板的第二重身份：implement 阶段的只读门禁

模板 Notes 区第 3 条（__SPECKIT_COMMAND_IMPLEMENT__ reads checklist checkbox state as a gate and must not modify markers）在 templates/commands/implement.md 中有对应的执行实现：

只读扫描：implement 若发现 FEATURE_DIR/checklists/ 目录存在，则扫描其中所有清单文件，仅读取复选框状态，报告每个清单的勾选/未勾选数量，绝不改写清单文件或标记（约 56–61 行）；
PASS/FAIL 判定：所有清单未勾选项为 0 → PASS；任一清单存在未勾选项 → FAIL；
STOP 语义：FAIL 时实现流程停下来询问 “Some checklists have unchecked items. Do you want to proceed with implementation anyway? (yes/no)”，由人显式放行（约 76–81 行）。

这就形成了模板设计的闭环：模板声明 [x] 的语义与只读门禁契约 → 评审者按条目逐项判定需求质量 → implement 把未决条目变成硬门禁 → 人类决定是继续澄清需求还是带风险推进。checklists/requirements.md（内置规格质量清单）与自定义清单在此处被明确区分：前者由 specify/clarify 维护，后者由本模板生成、评审者拥有，两条生命周期互不干扰。

六、覆盖与定制：用 preset 替换 checklist-template

从模板解析栈可以推断，checklist-template 是可被 preset 覆盖的核心模板之一。仓库中的 presets/self-test/preset.yml 给出了完整示例：

- type: "template"
  name: "checklist-template"
  file: "templates/checklist-template.md"
  description: "Self-test checklist template"
  replaces: "checklist-template"