Hooke / mlaj

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
speckit.checklist.md 16.1 KB 
description: 基于用户需求为当前功能生成一份定制检查清单。

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

关键概念（CRITICAL）：检查清单是需求写作的单元测试——用于验证某个领域里需求的质量、清晰度与完整性。

不是用来做验证/测试：

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

用于验证需求质量：

  • ✅ “是否为所有卡片类型定义了视觉层级需求？”（完整性）
  • ✅ “‘突出展示’是否用具体的尺寸/位置进行了量化？”（清晰度）
  • ✅ “悬停态需求在所有可交互元素之间是否一致？”（一致性）
  • ✅ “是否定义了键盘导航的无障碍需求？”（覆盖度）
  • ✅ “spec 是否定义了当 logo 图片加载失败时的行为？”（边界情况）

类比：如果把 spec 看作用英文写成的代码，那么检查清单就是它的单元测试套件。你要测试的是需求是否写得好、是否完整、是否无歧义、是否能直接进入实现阶段——而不是测试实现是否正确。

用户输入

$ARGUMENTS

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

执行步骤

  1. 准备：在仓库根目录运行 .specify/scripts/bash/check-prerequisites.sh --json，并解析 JSON 中的 FEATURE_DIR 与 AVAILABLE_DOCS 列表。

    • 所有文件路径必须是绝对路径。
    • 当参数里包含单引号（例如 "I'm Groot"）时，使用转义写法：如 'I'\''m Groot'（或尽量用双引号："I'm Groot"）。

  2. 澄清意图（动态）：最多生成三个初始的上下文澄清问题（不要使用预制问题库）。这些问题必须：

    • 基于用户的表述 + 从 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 的集成触点，还是仅限本地模块正确性？”）
    • 风险优先级（例如：“以下哪些潜在风险区域需要强制门禁检查？”）
    • 深度校准（例如：“这是轻量的 pre-commit 自查清单，还是正式发布门禁？”）
    • 受众框定（例如：“这份清单仅供作者使用，还是用于 PR 同行评审？”）
    • 边界排除（例如：“这一轮是否明确排除性能调优条目？”）
    • 场景类别缺口（例如：“未检测到恢复流程——回滚/部分失败路径是否在范围内？”）

问题格式规则：

  • 如果提供选项，生成紧凑表格，列为：选项 | 候选项 | 为什么重要
  • 选项最多 A–E；如果自由回答更清晰，则不输出表格
  • 不要让用户重复已经说过的话
  • 避免臆测分类（不要编造）。不确定时，直接问：“请确认 X 是否属于本次范围。”

无法互动时的默认值：

  • 深度：标准
  • 受众：若与代码相关则默认评审者（PR），否则默认作者
  • 聚焦：相关性最高的 2 个聚类方向

输出问题（标记为 Q1/Q2/Q3）。用户回答后：如果仍有 ≥2 类场景（Alternate / Exception / Recovery / Non-Functional domain）不清晰，你可以再追问最多 2 个更有针对性的后续问题（Q4/Q5），并为每个问题给出一行理由（例如：“恢复路径风险仍未明确”）。总问题数不要超过 5 个。若用户明确拒绝更多问题，则跳过加问。

  1. 理解用户诉求：结合 $ARGUMENTS 与澄清答案：

    • 提炼清单主题（例如 security、review、deploy、ux）
    • 汇总用户明确要求必须包含的条目
    • 将关注方向映射到分类骨架
    • 从 spec/plan/tasks 推断缺失上下文（不要编造）

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

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

上下文加载策略：

  • 只加载与当前关注方向相关且必要的部分（避免整文件倾倒）
  • 长段落优先汇总为简短的场景/需求要点
  • 使用渐进式披露：仅当发现缺口时再做补充读取
  • 源文档很大时，用中间摘要条目替代直接嵌入原文
  1. 生成检查清单——创建“需求的单元测试”：
    • 若 FEATURE_DIR/checklists/ 不存在，则创建该目录
    • 生成唯一的检查清单文件名：
      • 根据领域使用短且有描述性的名称（例如 ux.md、api.md、security.md）
      • 格式：[domain].md
      • 如果文件已存在，则追加到现有文件
    • 条目 ID 从 CHK001 开始顺序编号
    • 每次运行 /speckit.checklist 都创建一个新文件（绝不覆盖已有清单）

核心原则：测需求，而不是测实现： 每条清单项都必须从“需求文本本身”出发，评估：

  • Completeness（完整性）：是否包含所有必要需求？
  • Clarity（清晰度）：需求是否明确且具体、无歧义？
  • Consistency（一致性）：需求之间是否一致、无冲突？
  • Measurability（可度量性）：需求是否能客观验证？
  • Coverage（覆盖度）：是否覆盖所有场景/边界情况？

分类结构——按需求质量维度分组：

  • 需求完整性（Requirement Completeness）：是否记录了所有必要需求？
  • 需求清晰度（Requirement Clarity）：需求是否具体明确、无歧义？
  • 需求一致性（Requirement Consistency）：需求是否相互对齐且无冲突？
  • 验收标准质量（Acceptance Criteria Quality）：成功标准是否可度量？
  • 场景覆盖（Scenario Coverage）：是否覆盖所有流程/用例？
  • 边界情况覆盖（Edge Case Coverage）：是否定义了边界条件？
  • 非功能需求（Non-Functional Requirements）：性能/安全/无障碍等是否被明确规定？
  • 依赖与假设（Dependencies & Assumptions）：是否记录并验证？
  • 歧义与冲突（Ambiguities & Conflicts）：哪些点需要澄清？

如何编写清单项——“英文需求的单元测试”：

❌ 错误示例（在测实现）：

  • “验证落地页展示 3 张剧集卡片”
  • “测试桌面端悬停态是否生效”
  • “确认点击 logo 会跳回首页”

✅ 正确示例（在测需求质量）：

  • “是否明确规定了精选剧集的数量与布局？”[完整性]
  • “‘突出展示’是否用具体的尺寸/位置进行了量化？”[清晰度]
  • “悬停态需求在所有可交互元素之间是否一致？”[一致性]
  • “是否为所有可交互 UI 定义了键盘导航需求？”[覆盖度]
  • “当 logo 图片加载失败时，是否规定了兜底行为？”[边界情况]
  • “是否为异步剧集数据定义了加载态？”[完整性]
  • “spec 是否定义了存在竞争 UI 元素时的视觉层级？”[清晰度]

条目结构（结构规范）： 每条清单项应遵循以下模式：

  • 用问题句式询问需求质量
  • 聚焦 spec/plan 中“写了什么/没写什么”
  • 在方括号中标注质量维度 [Completeness/Clarity/Consistency/etc.]
  • 检查既有需求时引用 spec 章节 [Spec §X.Y]
  • 检查缺失需求时使用 [Gap] 标记

按质量维度的示例（维度示例）：

Completeness:

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

Clarity:

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

Consistency:

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

Coverage:

  • “是否定义了空状态场景（没有剧集）的需求？[Coverage, Edge Case]”
  • “是否覆盖了并发用户交互场景？[Coverage, Gap]”
  • “是否规定了部分数据加载失败时的需求？[Coverage, Exception Flow]”

Measurability:

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

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

  • 检查是否存在以下场景的需求：Primary、Alternate、Exception/Error、Recovery、Non-Functional
  • 对每个场景类别提问：“[scenario type] 的需求是否完整、清晰且一致？”
  • 若缺失某类场景：提问“[scenario type] 的需求是有意排除还是遗漏？[Gap]”
  • 当存在状态变更时，包含韧性/回滚要求：例如“是否定义了迁移失败时的回滚需求？[Gap]”

可追溯性要求（Traceability Requirements）：

  • 最低要求：≥80% 的条目必须包含至少一个可追溯引用
  • 每条应引用 spec 章节 [Spec §X.Y]，或使用标记：[Gap]、[Ambiguity]、[Conflict]、[Assumption]
  • 若没有 ID 体系：提问“是否建立了需求与验收标准的 ID 体系？[Traceability]”

暴露并推动解决问题（需求质量问题）： 围绕“需求文本本身”提问：

  • 歧义："'fast' 是否用具体指标量化？[Ambiguity, Spec §NFR-1]"
  • 冲突：“§FR-10 与 §FR-10a 的导航需求是否冲突？[Conflict]”
  • 假设：“‘播客 API 永远可用’这一假设是否得到验证？[Assumption]”
  • 依赖：“是否记录了外部播客 API 的需求？[Dependency, Gap]”
  • 定义缺失：“‘visual hierarchy’ 是否用可度量标准定义？[Gap]”

内容收敛（Content Consolidation）：

  • 软上限：若候选条目 > 40，按风险/影响优先级筛选
  • 合并检查同一需求点的近似重复条目
  • 若低影响边界情况 > 5 个，合并为一条：“边界情况 X、Y、Z 是否在需求中被覆盖？[Coverage]”

🚫 绝对禁止——这些会把它变成“实现测试”，而不是“需求测试”：

  • ❌ 任何以 “Verify/Test/Confirm/Check” 开头并描述实现行为的条目
  • ❌ 引用代码执行、用户操作或系统行为
  • ❌ “显示正确”“工作正常”“符合预期”等模糊描述
  • ❌ “点击”“跳转”“渲染”“加载”“执行”等实现层动作
  • ❌ 测试用例、测试计划、QA 流程
  • ❌ 实现细节（框架、API、算法）

✅ 必须使用的句式——这些才是在测需求质量：

  • ✅ “是否为 [scenario] 定义/规定/记录了 [requirement type]？”
  • ✅ “[vague term] 是否用具体标准量化/澄清？”
  • ✅ “[section A] 与 [section B] 的需求是否一致？”
  • ✅ “[requirement] 是否能客观测量/验证？”
  • ✅ “需求是否覆盖了 [edge cases/scenarios]？”
  • ✅ “spec 是否定义了 [missing aspect]？”

  1. 结构参考：按 .specify/templates/checklist-template.md 里的权威模板生成清单（标题、元信息、分类标题、ID 格式）。如果模板不可用，使用：一级标题（H1）+ purpose/created 元信息行 + ## 分类段落；段落内使用 - [ ] CHK### <清单项>，ID 从 CHK001 全局递增。

  2. 报告（Report）：输出生成的清单完整路径、条目数量，并提醒用户每次运行都会创建新文件。总结：

    • 已选择的关注方向
    • 深度等级
    • 角色/时机
    • 已纳入的用户显式 must-have 条目

重要：每次执行 /speckit.checklist 都会创建一个用短且有描述性的名称命名的清单文件（如果文件已存在则追加）。这使得：

  • 多种类型的检查清单可并存（例如 ux.md、test.md、security.md）
  • 文件名简短易记，并能表达用途
  • 在 checklists/ 目录中易于识别与定位

为避免杂乱，请使用清晰的类型命名，并在完成后清理过时的清单文件。

清单类型示例与样例条目

UX 需求质量： ux.md

样例条目（测需求，不测实现）：

  • “视觉层级需求是否用可度量标准定义？[Clarity, Spec §FR-1]”
  • “UI 元素的数量与位置是否被明确规定？[Completeness, Spec §FR-1]”
  • “交互状态（hover/focus/active）的需求是否一致地被规定？[Consistency]”
  • “是否为所有可交互元素规定了无障碍需求？[Coverage, Gap]”
  • “图片加载失败时的兜底行为是否被规定？[Edge Case, Gap]”
  • “‘突出展示’是否能被客观度量？[Measurability, Spec §FR-4]”

API 需求质量： api.md

样例条目：

  • “是否为所有失败场景规定了错误响应格式？[Completeness]”
  • “限流需求是否用具体阈值量化？[Clarity]”
  • “所有端点的认证需求是否一致？[Consistency]”
  • “是否为外部依赖定义了重试/超时需求？[Coverage, Gap]”
  • “需求中是否记录了版本管理策略？[Gap]”

性能需求质量： performance.md

样例条目：

  • “性能需求是否用具体指标量化？[Clarity]”
  • “是否为所有关键用户旅程定义了性能目标？[Coverage]”
  • “是否规定了不同负载条件下的性能需求？[Completeness]”
  • “性能需求是否能被客观测量？[Measurability]”
  • “高负载场景下的降级需求是否被规定？[Edge Case, Gap]”

安全需求质量： security.md

样例条目：

  • “是否为所有受保护资源规定了认证需求？[Coverage]”
  • “是否为敏感信息定义了数据保护需求？[Completeness]”
  • “是否已文档化威胁模型，并且需求与之对齐？[Traceability]”
  • “安全需求是否与合规义务保持一致？[Consistency]”
  • “是否定义了安全失败/泄露后的响应需求？[Gap, Exception Flow]”

反例：不要这样做

❌ 错误——这些在测实现，不是在测需求：

- [ ] CHK001 - 验证落地页展示 3 张剧集卡片 [Spec §FR-001]
- [ ] CHK002 - 测试桌面端悬停态是否正常 [Spec §FR-003]
- [ ] CHK003 - 确认点击 logo 会跳转回首页 [Spec §FR-010]
- [ ] CHK004 - 检查相关剧集区域是否展示 3-5 条 [Spec §FR-005]

✅ 正确——这些在测需求质量：

- [ ] CHK001 - 是否明确规定了精选剧集的数量与布局？[Completeness, Spec §FR-001]
- [ ] CHK002 - 是否为所有可交互元素一致地规定了悬停态需求？[Consistency, Spec §FR-003]
- [ ] CHK003 - 是否为所有可点击的品牌元素明确规定了导航需求？[Clarity, Spec §FR-010]
- [ ] CHK004 - 是否记录了相关剧集的筛选条件？[Gap, Spec §FR-005]
- [ ] CHK005 - 是否为异步剧集数据定义了加载态需求？[Gap]
- [ ] CHK006 - “视觉层级”需求是否能被客观测量？[Measurability, Spec §FR-001]

关键差异：

  • 错误：测试系统是否工作正常
  • 正确：测试需求是否写得正确
  • 错误：验证行为
  • 正确：验证需求质量
  • 错误：“它是否做了 X？”
  • 正确：“X 是否被清晰规定？”