在 spec-kit 项目中为当前功能生成需求质量检查清单…

已使用 spec-kit 且需要针对用户指定关注点审查 spec/plan/tasks 的需求质量时，生成或追加自定义 checklist。

适用场景

解决思路

1. 先确认项目是 spec-kit 结构，检查项目根存在 `.specify/` 目录；所有路径按绝对路径处理。
2. 在执行生成前检查扩展钩子：若项目根存在 `.specify/extensions.yml`，读取 `hooks.before_checklist` 下的条目。
3. 若 YAML 无法解析或无效，不要静默跳过：告诉用户 `.specify/extensions.yml` 无法读取（包含解析器错误），并说明未检查任何钩子，包括其中注册的强制（`optional: false`）钩子，然后正常继续。
4. 过滤掉 `enabled` 显式为 `false` 的钩子；没有 `enabled` 字段的钩子默认视为启用。
5. 对剩余钩子不要尝试解释或求值 `condition`：无 `condition` 字段或为 null/空时视为可执行；定义了非空 `condition` 时跳过，把条件求值留给 HookExecutor 实现。
6. 从钩子命令名构造调用时，把点号 `.` 替换为连字符 `-`，例如 `speckit.git.commit` → `/speckit-git-commit`。
7. 对每个可执行钩子按 `optional` 标志输出：可选钩子（`optional: true`）输出 `## Extension Hooks`、`**Optional Pre-Hook**: {extension}`、`Command: /{command}`、`Description: {description}`、`Prompt: {prompt}`、`To execute: /{command}`。
8. 强制钩子（`optional: false`）输出 `## Extension Hooks`、`**Automatic Pre-Hook**: {extension}`、`Executing: /{command}`、`EXECUTE_COMMAND: {command}`，并说明等待钩子结果后再进入执行步骤。
9. 输出强制钩子块后必须实际调用该钩子，并等待其完成后再继续；调用方式按当前 agent/会话运行命令的同样方式执行（例如 skills-mode agent 用 `/skill:speckit-...` 或 `$speckit-...`），只输出块不算执行。
10. 若没有注册钩子或 `.specify/extensions.yml` 不存在，静默跳过预执行钩子检查。
11. 运行 `.specify/scripts/bash/check-prerequisites.sh --json --template checklist-template`（从仓库根目录），解析 JSON 得到 `FEATURE_DIR`、`AVAILABLE_DOCS` 列表和 `TEMPLATE_CONTENT`。
12. 所有文件路径使用绝对路径；参数中含单引号如 `I'm Groot` 时用转义语法，如 `'I'\''m Groot'`，或尽量用双引号如 `'I'm Groot'`。
13. 若存在 `.specify/memory/constitution.md`，加载它，获取项目原则和治理约束。
14. 动态澄清意图：最多生成三个初始上下文澄清问题，不使用预置问题目录；问题必须由用户措辞及从 spec/plan/tasks 提取的信号生成；只问会实质改变 checklist 内容的信息；若 `$ARGUMENTS` 中已无歧义则分别跳过；优先精确而非广泛。
15. 澄清问题生成算法：提取信号，包括功能领域关键词（如 auth、latency、UX、API）、风险指标（“critical”“must”“compliance”）、干系人提示（“QA”“review”“security team”）、显式交付物（“a11y”“rollback”“contracts”）。
16. 将信号聚类为候选关注领域（最多 4 个），按相关性排序。
17. 若未显式说明，识别可能受众与时机（作者、审查者、QA、发布）。
18. 检测缺失维度：范围广度、深度/严格度、风险强调、排除边界、可度量验收标准。
19. 从以下问题原型中拟定问题：范围细化、风险优先级、深度校准、受众框定、边界排除、场景类缺口。
20. 问题格式规则：若提供选项，生成紧凑表格，列为 Option | Candidate | Why It Matters；最多 A–E 个选项；若自由文本更清楚则不用表格；不要让用户复述已说过的内容；避免推测性类别（不臆造）；不确定时明确问“确认 X 是否在范围内”。
21. 交互不可用时使用默认值：深度 Standard；受众为 Reviewer (PR)（若与代码相关），否则 Author；关注点为相关性最高的前 2 个聚类。
22. 输出问题并标注 Q1/Q2/Q3。收到回答后，若仍有 ≥2 个场景类（Alternate / Exception / Recovery / Non-Functional domain）不清楚，可以再问最多两个有针对性的后续问题 Q4/Q5，每个附一行理由（如“未解决的恢复路径风险”）。总问题数不超过五个；用户明确拒绝继续时跳过升级。
23. 理解用户请求：合并 `$ARGUMENTS` 与澄清回答；推导 checklist 主题（如 security、review、deploy、ux）；整合用户明确提到的 must-have 项；把关注点选择映射到类别脚手架；从 spec/plan/tasks 推断缺失上下文（不要臆造）。
24. 加载功能上下文：从 `FEATURE_DIR` 读取 `spec.md`；若存在则读取 `plan.md`、`tasks.md`。
25. 上下文加载策略：只加载与当前关注领域相关的必要部分，避免整文件倾倒；长段落优先概括为简洁场景/需求要点；采用渐进披露，只在发现缺口时追加检索；源文档很大时生成临时摘要条目，而不是嵌入原始文本。
26. 生成 checklist：使用 `TEMPLATE_CONTENT` 作为结构模板，创建“需求的单元测试”。
27. 若 `FEATURE_DIR/checklists/` 不存在则创建。
28. 生成唯一 checklist 文件名：基于领域使用简短描述性名称（如 `ux.md`、`api.md`、`security.md`），格式为 `[domain].md`。
29. 文件处理行为：若文件不存在，创建新文件并从 `CHK001` 开始编号；若文件已存在，向现有文件追加新条目，从上一条 CHK ID 继续（例如最后是 CHK015，则新条目从 CHK016 开始）。
30. 绝不删除或替换现有 checklist 内容，始终保留并追加；所有新生成条目保持未勾选 `[ ]`；复选框状态属于审查者。
31. 核心原则：测试需求，不测试实现。每个条目必须评估需求本身，包括 Completeness（完整性）、Clarity（清晰度）、Consistency（一致性）、Measurability（可测性）、Coverage（覆盖率）。
32. 按需求质量维度分组：Requirement Completeness（所有必要需求是否记录）、Requirement Clarity（需求是否具体无歧义）、Requirement Consistency（需求是否一致无冲突）、Acceptance Criteria Quality（成功标准是否可度量）、Scenario Coverage（所有流程/用例是否覆盖）、Edge Case Coverage（边界条件是否定义）、Non-Functional Requirements（性能、安全、可访问性等是否规定）、Dependencies & Assumptions（依赖与假设是否记录并验证）、Ambiguities & Conflicts（需要澄清什么）。
33. 写条目时采用“英文单元测试”方式：问需求是否写清楚，而不是问实现是否工作。错误示例：`Verify landing page displays 3 episode cards`、`Test hover states work on desktop`、`Confirm logo click navigates home`；正确示例：`Are the exact number and layout of featured episodes specified? [Completeness]`、`Is 'prominent display' quantified with specific sizing/positioning? [Clarity]`、`Are hover state requirements consistent across all interactive elements? [Consistency]`、`Are keyboard navigation requirements defined for all interactive UI? [Coverage]`、`Is the fallback behavior specified when logo image fails to load? [Edge Cases]`、`Are loading states defined for asynchronous episode data? [Completeness]`、`Does the spec define visual hierarchy for competing UI elements? [Clarity]`。
34. 条目结构：使用询问需求质量的问句；聚焦 spec/plan 中写了或没写什么；在方括号中标注质量维度 `[Completeness/Clarity/Consistency/...]`；检查已有需求时引用 spec 章节 `[Spec §X.Y]`；检查缺失需求时使用 `[Gap]` 标记。
35. 按质量维度示例：完整性：`Are error handling requirements defined for all API failure modes? [Gap]`、`Are accessibility requirements specified for all interactive elements? [Completeness]`、`Are mobile breakpoint requirements defined for responsive layouts? [Gap]`。
36. 清晰度示例：`Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]`、`Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]`、`Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]`。
37. 一致性示例：`Do navigation requirements align across all pages? [Consistency, Spec §FR-10]`、`Are card component requirements consistent between landing and detail pages? [Consistency]`。
38. 覆盖示例：`Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]`、`Are concurrent user interaction scenarios addressed? [Coverage, Gap]`、`Are requirements specified for partial data loading failures? [Coverage, Exception Flow]`。
39. 可测性示例：`Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]`、`Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]`。
40. 场景分类与覆盖：检查需求是否存在 Primary、Alternate、Exception/Error、Recovery、Non-Functional 场景；对每个场景类问“该场景类需求是否完整、清晰、一致？”；若缺失则问“该场景类需求是有意排除还是缺失？[Gap]”；发生状态变更时纳入韧性/回滚，如“Are rollback requirements defined for migration failures? [Gap]”。
41. 可追溯性要求：至少 ≥80% 的条目必须包含至少一个可追溯引用；每个条目应引用 spec 章节 `[Spec §X.Y]`，或使用标记 `[Gap]`、`[Ambiguity]`、`[Conflict]`、`[Assumption]`；若没有 ID 体系，则写“Is a requirement & acceptance criteria ID scheme established? [Traceability]”。
42. 暴露并解决需求质量问题：询问歧义，如 `Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]`；冲突，如 `Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]`；假设，如 `Is the assumption of 'always available podcast API' validated? [Assumption]`；依赖，如 `Are external podcast API requirements documented? [Dependency, Gap]`；缺失定义，如 `Is 'visual hierarchy' defined with measurable criteria? [Gap]`。
43. 内容合并：软上限为若原始候选条目 >40，按风险/影响优先排序；合并检查同一需求方面的近似重复项；若低影响边界用例 >5 个，合并为一个条目，如 `Are edge cases X, Y, Z addressed in requirements? [Coverage]`。
44. 绝对禁止：任何以 `Verify`、`Test`、`Confirm`、`Check` 开头并针对实现行为的条目；引用代码执行、用户操作、系统行为；`Displays correctly`、`works properly`、`functions as expected`；`Click`、`navigate`、`render`、`load`、`execute`；测试用例、测试计划、QA 流程；实现细节（框架、API、算法）。
45. 必须采用模式：`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]?`。
46. 结构参考：按 `.specify/templates/checklist-template.md` 生成 checklist，包含标题、meta 部分、类别标题、所有权说明、notes 部分、ID 格式。若模板不可用，使用 fallback：H1 标题、purpose/created meta 行、所有权说明（解释 `[x]` 表示审查者批准需求质量）、`##` 类别小节、包含 `- [ ] CHK### <requirement item>` 的行，全局递增 ID 从 `CHK001` 开始，并注明 `/speckit-implement` 会读取 checklist 状态但不修改标记。
47. 报告：输出 checklist 文件完整路径、条目数量，并总结本次是新建文件还是追加到现有文件；总结所选关注领域、深度级别、行为者/时机、纳入的任何用户指定 must-have 项。
48. 重要：每次 `/speckit-checklist` 调用使用简短描述性 checklist 文件名，并新建或追加文件；这样可支持多种类型 checklist（如 `ux.md`、`test.md`、`security.md`）；文件名应简单易记表明用途；便于在 `checklists/` 文件夹中识别和导航。
49. 为避免杂乱，使用描述性类型，并在完成后清理过时 checklist。
50. 示例 checklist 类型与条目：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]`。
51. 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]`。
52. 性能质量 `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]`。
53. 安全质量 `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]`。
54. 反例：错误条目 `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]`；这些都是测试实现而非需求。
55. 正例：`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 被清楚规定了吗？”。
56. 后执行检查扩展钩子：检查 `.specify/extensions.yml` 是否存在；若存在读取 `hooks.after_checklist` 下条目。
57. 后执行钩子的无效 YAML、enabled、condition、点号替换、可选/强制输出和实际调用等待规则与预执行检查相同，只是钩子键为 `hooks.after_checklist`，输出标题用可选/强制 Hook（非 Pre-Hook）。
58. 若无钩子或文件不存在，静默跳过。
59. 所有权与生命周期：本命令生成的自定义 checklist 是审查者拥有的需求质量审查产物；`[x]` 表示审查者判定需求质量标准已满足，不表示实现完成；本命令只能生成或追加条目，绝不能把生成项标为 `[x]`；只有审查者明确要求时 agent 才可协助评估条目；`checklists/requirements.md` 是 `/speckit-specify` 和 `/speckit-clarify` 维护的内置 spec-quality checklist，不要把该例外套用到本命令生成的自定义 checklist。
60. 清单目的比喻：如果 spec 是用英文写的代码，checklist 就是它的单元测试套件；测试需求是否写得好、完整、无歧义、可实施，而不是测试实现是否工作。

适用边界 · 注意事项

• 不适用于非 spec-kit 项目或缺少 `.specify/` 目录、脚本与模板的环境。
• 不要用它测试代码实现、API 行为、UI 交互或编写 QA 测试用例；它只审查需求写得是否合格。
• 不要把它当作 `/speckit-specify` 和 `/speckit-clarify` 维护的 `checklists/requirements.md` 的替代；自定义 checklist 由审查者拥有，生成时不得勾选 `[x]`。