Communitygithub.com

tangjuyo/reels-blocker

根据用户需求生成当前功能的自定义检查清单。

reels-blocker 是什么?

该技能旨在生成用于评估需求质量的自定义检查清单,其核心理念是将检查清单视为“需求的单元测试”。它要求用户提供功能领域和关注点,然后动态生成一系列问题,用于检验需求规约的完整性、清晰度、一致性、可测量性和覆盖度。技能支持从项目中的 spec.md、plan.md、tasks.md 等文件加载上下文,并根据用户输入和可能的扩展钩子(通过 .specify/extensions.yml 配置)进行前置检查。生成的检查清单会保存在功能目录下的 checklists/ 中,以 [domain].md 格式命名,并支持追加新条目到已有文件。该技能主要适用于 Claude Code、Cursor、Codex 等支持工具调用和自定义命令的 AI 编码助手平台,帮助开发者和审阅者在实现前系统性地发现和解决需求中的缺陷。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/tangjuyo/reels-blocker/tree/HEAD/.claude/skills/speckit-checklist

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

检查清单目的:“英文的单元测试”

核心概念:检查清单是需求编写的“单元测试”——它们验证特定领域中需求的质量、清晰度和完整性。

非用于验证/测试:

  • ❌ 非“验证按钮点击是否正确”
  • ❌ 非“测试错误处理是否生效”
  • ❌ 非“确认 API 返回 200”
  • ❌ 非检查代码/实现是否匹配规约

用于需求质量验证:

  • ✅ “是否为所有卡片类型定义了视觉层级需求?”(完整性)
  • ✅ “是否用具体的尺寸/定位量化了‘突出显示’?”(清晰度)
  • ✅ “所有交互元素的悬停状态需求是否一致?”(一致性)
  • ✅ “是否为键盘导航定义了无障碍需求?”(覆盖度)
  • ✅ “规约是否定义了当 logo 图片加载失败时的处理方式?”(边界情况)

比喻:如果你的规约是用英文编写的代码,那么检查清单就是它的单元测试套件。你测试的是需求是否编写良好、完整、无歧义且可以开始实现——而不是实现是否工作。

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

  • 由此命令生成的自定义检查清单是审阅者拥有的需求质量审查工件。
  • [x] 表示审阅者判断该需求质量标准已满足。
  • [x] 并非表示实现工作已完成。
  • 此命令生成或追加检查清单条目;它绝不能将生成的条目标记为 [x]。
  • 仅在审阅者明确要求时,智能体才可以协助评估条目。
  • checklists/requirements.md 是一个由 /speckit-specify 和 /speckit-clarify 维护的独立内置规约质量检查清单;不要将该例外应用于此处生成的自定义检查清单。

用户输入

$ARGUMENTS

在继续之前,你必须考虑用户输入(如果不为空)。

执行前检查

检查扩展钩子(在生成检查清单之前):

  • 检查项目根目录下是否存在 .specify/extensions.yml。
  • 如果存在,读取它并查找 hooks.before_checklist 键下的条目。
  • 如果 YAML 无法解析或无效,不要静默跳过:告知用户 .specify/extensions.yml 无法读取(包含解析错误),并且没有检查任何钩子(包括其中注册的任何必需(optional: false)钩子),然后正常继续。
  • 过滤掉 enabled 显式为 false 的钩子。将没有 enabled 字段的钩子视为默认启用。
  • 对于每个剩余的钩子,不要尝试解释或评估钩子的 condition 表达式:
    • 如果钩子没有 condition 字段,或它为 null/空,则将钩子视为可执行。
    • 如果钩子定义了非空的 condition,则跳过该钩子,将条件评估留给 HookExecutor 实现。
  • 在从钩子命令名构建命令调用时,将点(.)替换为连字符(-)。例如,speckit.git.commit → /speckit-git-commit。
  • 对于每个可执行的钩子,根据其 optional 标志输出以下内容:
    • 可选钩子(optional: true):
      ## 扩展钩子
      
      **可选前置钩子**:{extension}
      命令:`/{command}`
      描述:{description}
      
      提示:{prompt}
      执行:`/{command}`
      
    • 必需钩子(optional: false):
      ## 扩展钩子
      
      **自动前置钩子**:{extension}
      正在执行:`/{command}`
      EXECUTE_COMMAND: {command}
      
      在继续执行步骤之前,等待钩子命令的结果。
      
      在发出上述代码块后,你必须实际调用该钩子并等待其完成,然后再继续。以你在此智能体/会话中运行命令的相同方式运行它(调用方式可能与上面显示的字面 {command} id 不同,例如,技能模式的智能体可能将其作为 /skill:speckit-... 或 $speckit-... 运行)。仅发出代码块并不会运行钩子。
  • 如果没有注册钩子或 .specify/extensions.yml 不存在,则静默跳过。

执行步骤

  1. 设置:从仓库根目录运行 .specify/scripts/bash/check-prerequisites.sh --json --template checklist-template,并解析 JSON 以获取 FEATURE_DIR、AVAILABLE_DOCS 列表和 TEMPLATE_CONTENT。

    • 所有文件路径必须是绝对路径。
    • 对于参数中的单引号(如“I'm Groot”),请使用转义语法:例如 'I'''m Groot'(如果可能,请使用双引号:“I'm Groot”)。
  2. 如果存在:加载 .specify/memory/constitution.md 以获取项目原则与治理约束。

  3. 澄清意图(动态):推导出最多三个初始的上下文澄清问题(无预置目录)。它们必须:

    • 从用户的措辞 + 从规约/计划/任务中提取的信号生成。
    • 仅询问那些会实质性地改变检查清单内容的信息。
    • 如果 $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 个场景类别(备选/异常/恢复/非功能领域)不明确,你可以最多再询问两个有针对性的后续问题(Q4/Q5),每个问题附带一行理由(例如,“未解决的恢复路径风险”)。总共不超过五个问题。如果用户明确拒绝,则跳过升级。

  4. 理解用户请求:结合 $ARGUMENTS + 澄清回答:

    • 推导检查清单主题(例如,安全、审查、部署、用户体验)
    • 汇总用户提到的明确必备项目
    • 将焦点选择映射到类别框架
    • 从规约/计划/任务中推断任何缺失的上下文(不要幻觉)
  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 个剧集卡片”
    • “测试悬停状态在桌面上正常工作”
    • “确认点击 Logo 导航到首页”

    ✅ 正确(测试需求质量):

    • “是否指定了特色剧集的确切数量和布局?”[完整性]
    • “是否用具体的尺寸/定位量化了‘突出显示’?”[清晰度]
    • “所有交互元素的悬停状态需求是否一致?”[一致性]
    • “是否为所有交互式 UI 定义了键盘导航需求?”[覆盖度]
    • “当 Logo 图片加载失败时,是否指定了回退行为?”[边界情况]
    • “是否为异步剧集数据定义了加载状态?”[完整性]
    • “规约是否为竞争性 UI 元素定义了视觉层级?”[清晰度]

    条目结构: 每个条目应遵循以下模式:

    • 以问题形式询问需求质量
    • 关注规约/计划中已编写(或未编写)的内容
    • 在方括号中包含质量维度 [完整性/清晰度/一致性/等]
    • 在检查现有需求时引用规约章节 [规范 §X.Y]
    • 在检查缺失需求时使用 [缺口] 标记

    按质量维度的示例:

    完整性:

    • “是否为所有 API 故障模式定义了错误处理需求?[缺口]”
    • “是否为所有交互元素指定了无障碍需求?[完整性]”
    • “是否为响应式布局定义了移动端点需求?[缺口]”

    清晰度:

    • “是否用量化的时序阈值定义了‘快速加载’?[清晰度,规范 §NFR-2]”
    • “‘相关剧集’的选择标准是否明确界定?[清晰度,规范 §FR-5]”
    • “是否用可衡量的视觉属性定义了‘突出’?[歧义,规范 §FR-4]”

    一致性:

    • “所有页面的导航需求是否保持一致?[一致性,规范 §FR-10]”
    • “着陆页和详情页的卡片组件需求是否一致?[一致性]”

    覆盖度:

    • “是否定义了零状态场景(无剧集)的需求?[覆盖度,边界情况]”
    • “是否处理了并发用户交互场景?[覆盖度,缺口]”
    • “是否指定了部分数据加载失败的需求?[覆盖度,异常流程]”

    可测量性:

    • “视觉层级需求是否可测量/可测试?[验收标准,规范 §FR-1]”
    • “‘平衡的视觉重量’是否可以客观验证?[可测量性,规范 §FR-2]”

    场景分类与覆盖度(需求质量重点):

    • 检查是否存在以下场景的需求:主场景、备选场景、异常/错误、恢复、非功能性
    • 对于每个场景类别,询问:“[场景类型]需求是否完整、清晰且一致?”
    • 如果缺少场景类别:“[场景类型]需求是被有意排除还是缺失了?[缺口]”
    • 当存在状态变化时,包含弹性/回滚:“是否为迁移失败定义了回滚需求?[缺口]”

    可追溯性需求:

    • 最低要求:≥80% 的条目必须包含至少一个可追溯性引用
    • 每个条目应引用:规约章节 [规范 §X.Y],或使用标记:[缺口]、[歧义]、[冲突]、[假设]
    • 如果不存在 ID 系统:“是否建立了需求与验收标准 ID 方案?[可追溯性]”

    暴露并解决问题(需求质量问题): 提出关于需求本身的问题:

    • 歧义:“‘快速’一词是否用具体指标量化了?[歧义,规范 §NFR-1]”
    • 冲突:“导航需求在 §FR-10 和 §FR-10a 之间是否存在冲突?[冲突]”
    • 假设:“是否验证了‘播客 API 始终可用’的假设?[假设]”
    • 依赖项:

…

[为翻译而截断]

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

相关技能