Communitygithub.com

tangjuyo/reels-blocker

识别当前功能规格中未充分定义的领域,提出最多5个针对性澄清问题,并将答案编码回规格文档中。

reels-blocker 是什么?

这是一个专门用于软件功能规格澄清的AI代理技能。它的核心目标是系统性地检测和减少规格中的歧义和缺失决策点,特别适用于在进入详细规划阶段(如 `/speckit-plan`)之前使用。该技能首先检查可选的扩展钩子(如 `.specify/extensions.yml` 中的配置),然后通过运行预检查脚本确定当前功能目录和规格文件。接着,它会基于一个全面的分类法(涵盖功能范围、数据模型、交互流程、非功能性需求、集成、边界情况等)对规格进行结构化扫描,以识别不明确或缺失的领域。随后,它会生成一个最多包含5个问题的优先级队列(每个问题都设计为多选或短答案格式),并逐个向用户提出,每个问题都附带推荐答案和清晰的“为何重要”解释。用户回答后,技能会将澄清内容增量地集成回规格文件,维护一个 `## Clarifications` 章节,并立刻更新相关章节(如功能需求、数据模型、边缘情况)。最后,它会重新验证规格质量检查清单(如果存在),更新任务列表的勾选状态。该技能通过逐步细化、基于证据的方法显著降低了因需求误解而导致返工的风险,非常适合任何使用基于规格的开发工作流的团队,并支持包括Claude Code、Cursor、Codex in Skills Mode、Copilot、OpenAI CLI、Google Gemini CLI在内的多种平台。

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

在你喜欢的 AI 中提问

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

文档

用户输入

$ARGUMENTS

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

预执行检查

检查扩展钩子(在澄清之前):

  • 检查项目根目录下是否存在 .specify/extensions.yml。
  • 如果存在,读取它并查找 hooks.before_clarify 键下的条目。
  • 如果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 不存在,则静默跳过。

大纲

目标:检测并减少活动功能规格中的歧义或缺失决策点,并将澄清结果直接记录在规格文件中。

注意:此澄清工作流预计在调用 /speckit-plan 之前运行(并完成)。如果用户明确表示他们正在跳过澄清(例如,探索性冲刺),你可以继续,但必须警告下游返工风险增加。

执行步骤:

  1. 从仓库根目录运行 .specify/scripts/bash/check-prerequisites.sh --json --paths-only 一次(组合的 --json --paths-only 模式 / -Json -PathsOnly)。解析最小的 JSON 负载字段:

    • FEATURE_DIR
    • FEATURE_SPEC
    • (可选地捕获 IMPL_PLAN、TASKS 用于未来的链式流程。)
    • 如果 JSON 解析失败,中止并指示用户重新运行 /speckit-specify 或验证功能分支环境。
    • 对于参数中的单引号,例如 "I'm Groot",使用转义语法:例如 'I'''m Groot'(如果可能,使用双引号:"I'm Groot")。
  2. 如果存在:加载 .specify/memory/constitution.md 以获取项目原则和治理约束。

  3. 加载当前的规格文件。使用此分类法执行结构化的歧义和覆盖范围扫描。对于每个类别,标记状态:清晰 / 部分 / 缺失。生成用于优先级的内部覆盖图(如果没有要问的问题,则不要输出原始图)。

    功能范围与行为:

    • 核心用户目标与成功标准
    • 明确的范围外声明
    • 用户角色 / 角色区分

    领域与数据模型:

    • 实体、属性、关系
    • 身份与唯一性规则
    • 生命周期/状态转换
    • 数据量/规模假设

    交互与用户体验流程:

    • 关键用户旅程/序列
    • 错误/空/加载状态
    • 可访问性或本地化说明

    非功能性质量属性:

    • 性能(延迟、吞吐量目标)
    • 可扩展性(水平/垂直、限制)
    • 可靠性与可用性(正常运行时间、恢复预期)
    • 可观测性(日志、指标、追踪信号)
    • 安全与隐私(认证/授权、数据保护、威胁假设)
    • 合规性/监管约束(如果有)

    集成与外部依赖:

    • 外部服务/API 及故障模式
    • 数据导入/导出格式
    • 协议/版本假设

    边界情况与故障处理:

    • 负面场景
    • 速率限制/节流
    • 冲突解决(例如,并发编辑)

    约束与权衡:

    • 技术约束(语言、存储、托管)
    • 明确的权衡或被拒绝的替代方案

    术语与一致性:

    • 规范术语表术语
    • 避免的同义词/废弃术语

    完成信号:

    • 验收标准的可测试性
    • 可度量的完成定义风格指标

    杂项/占位符:

    • TODO 标记/未解决的决策
    • 缺乏量化的模糊形容词("健壮"、"直观")

    对于每个状态为“部分”或“缺失”的类别,添加候选问题机会,除非:

    • 澄清不会实质上改变实现或验证策略
    • 该项是专门关于实现方法、技术栈比较或任务分解的(内部记录)
  4. (内部)生成一个优先的候选澄清问题队列(最多5个)。不要一次全部输出。应用这些约束:

    • 整个会话中最多5个总问题。
    • 每个问题必须可以使用以下任一方式回答:
      • 一个简短的多项选择(2-5个不同的、互斥的选项),或
      • 一个单词/短语答案(明确约束:"答案最多5个单词")。
    • 仅包括其答案实质上影响架构、数据建模、任务分解、测试设计、用户体验行为、运营准备或合规性验证的问题。
    • 确保类别覆盖平衡:首先尝试覆盖影响最大的未解决类别;避免在单个高影响力领域(例如安全态势)未解决时提出两个低影响力问题。
    • 排除已回答的问题、琐碎的风格偏好或计划级别的执行细节(除非阻塞正确性)。
    • 优先选择减少下游返工风险或防止验收测试错位的澄清。
    • 如果超过5个类别仍未解决,则选择(影响 * 不确定性)启发式得分最高的5个。
  5. 顺序提问循环(交互式):

    • 一次只展示恰好一个问题。

    • 问题写作质量(适用于每个问题,无论是多项选择还是简短回答):

      • 以 **问题:** 开头,后跟一个以 ? 结尾的完整疑问句。? 之前的问题文本必须能够独立理解。
      • 绝不要使用主题标签、章节标题或需求 ID 作为问题本身。例如,验收设备/运行时矩阵 (FR-023) 是无效的——它是一个标签,而不是一个问题。
      • 在 ? 之后,唯一允许的后缀是可选的在括号内的需求/问题 ID。确切格式:**问题:** <疑问句>? 或 **问题:** <疑问句>? (FR-023)。绝不要将 ID 放在 ? 之前,也绝不要使用 ID(单独或与主题标签一起)作为整个提示。
      • 在问题行之后,立即在推荐/选项之前添加一句通俗易懂的“为何重要”句子(相关于验收或发布的利害关系)。
      • 使用日常用语;仅当在同一句子中定义时才引入术语。自我检查:不了解 Spec Kit 的读者必须能够仅从问题行回答。简洁是可以的;模糊的标签则不行。
    • 对于多项选择问题:

      • 分析所有选项并根据以下条件确定最合适的选项:
        • 项目类型的最佳实践
        • 类似实现中的常见模式
        • 风险降低(安全性、性能、可维护性)
        • 与规格中可见的任何明确项目目标或约束的一致性
      • 在顶部突出显示你的推荐选项,并附上清晰的推理(1-2句解释为什么这是最佳选择)。
      • 格式化为:**推荐:** 选项 [X] - <推理>
      • 然后将所有选项呈现为 Markdown 表格:
      选项描述
      A<选项 A 描述>
      B<选项 B 描述>
      C<选项 C 描述>(根据需要添加 D/E,最多5个)
      简短提供不同的简短答案(最多5个单词)(仅当自由格式替代方案合适时包括)
      • 表格后添加:你可以回复选项字母(例如,“A”),通过说“是”或“推荐”来接受推荐,或者提供你自己的简短答案。
    • 对于短答案风格(没有有意义的分立选项):

      • 根据最佳实践和上下文提供你的建议答案。
      • 格式化为:**建议:** <你提出的答案> - <简要推理>
      • 然后输出:格式:短答案(最多5个单词)。你可以通过说“是”或“建议”来接受建议,或者提供你自己的答案。
    • 在用户回答后:

      • 如果用户回复“是”、“推荐”或“建议”,则使用你之前陈述的推荐/建议作为答案。
      • 否则,验证答案是否映射到一个选项或符合 <=5 个单词的约束。
      • 如果模棱两可,要求快速澄清(计数仍属于同一问题;不要前进)。
      • 一旦满意,将其记录在工作记忆中(尚不写入磁盘)并移至下一个排队问题。
    • 在以下情况下停止提问:

      • 所有关键歧义已提前解决(剩余排队项目变得不必要),或
      • 用户表示完成("完成"、"好"、"没有更多了"),或
      • 你已经问了5个问题。
    • 绝不要提前透露未来排队的问题。

    • 如果一开始就没有有效问题,立即报告没有关键歧义。

  6. 在每个接受的答案之后进行集成(增量更新方法):

    • 在内存中维护规格的表示(开始时加载一次)以及原始文件内容。
    • 对于本会话中第一个集成的答案:
      • 确保存在 ## 澄清说明 章节(如果缺失,则在规格模板中最高级别的上下文/概述章节之后立即创建)。
      • 在其下,为今天创建一个(如果不存在)### 会话 YYYY-MM-DD 子标题。
    • 在接受后立即追加一个项目符号行:- 问:<问题> → 答:<最终答案>。
    • 然后立即将澄清应用于最合适的章节:
      • 功能歧义 → 在功能需求中更新或添加一个项目符号。
      • 用户交互/参与者区分 → 更新用户故事或参与者子章节(如果存在),包含澄清的角色、约束或场景。
      • 数据形状/实体 → 更新数据模型(添加字段、类型、关系),保持顺序;简洁地说明添加的约束。
      • 非功能性约束 → 在成功标准 > 可度量结果中添加/修改可度量标准(将模糊形容词转换为指标或明确目标)。
      • 边界情况/负面流程 → 在边界情况/错误处理下添加一个新的项目符号(如果模板为此提供了占位符,则创建这样的子章节)。
      • 术语冲突 → 在整个规格中标准化术语;仅当必要时通过添加 (以前称为“X”) 来保留原术语。
    • 如果澄清使先前模糊的陈述无效,则替换该陈述而不是复制;不留过时的矛盾文本。
    • 在每次集成后保存规格文件,以最大限度减少上下文丢失的风险(原子覆盖)。
    • 保持格式:不要重新排序不相关的章节;保持标题层次结构完整。
    • 保持每个插入的澄清最小且可测试(避免叙述漂移)。
  7. 验证(在每次写入后以及最终通过后执行):

    • 澄清说明会话每个接受的答案恰好包含一个项目符号(无重复)。
    • 总提问(接受)的问题 ≤ 5。
    • 更新的章节不包含新的答案本应解决的残留模糊占位符。
    • 没有残留矛盾的前一个陈述(扫描是否删除了现在无效的替代选择)。
    • Markdown 结构有效;只允许新的标题:## 澄清说明、### 会话 YYYY-MM-DD。
    • 术语一致性:在所有更新的章节中使用相同的规范术语。
  8. 将更新后的规格写回 FEATURE_SPEC。

  9. 重新验证规格质量检查清单(如果存在):

    • 检查 FEATURE_DIR/checklists/requirements.md 是否存在。
    • 如果不存在,则静默跳过此步骤。
    • 如果存在:
      1. 读取检查清单文件。
      2. 识别所有 GitHub 任务列表复选框行——匹配 - [ ]、- [x] 或 - [X](不区分大小写,容忍前导空格以支持嵌套项)且不在代码块内的行。忽略所有其他内容(标题、注释、非复选框项目符号、元数据)。
      3. 对于每个复选框行,将其当前标记状态(已选中或未选中)和项目文本记录到“之前”快照列表中。
      4. 根据更新后的规格(步骤7中刚刚保存的版本)重新评估每个复选框项。
      5. 对于每个复选框项,仅在选中/未选中状态实际更改时更新:
        • 如果项目现在通过并且之前未选中:将 [ ] 更改为 [x]。
        • 如果项目现在失败并且之前已选中:将 [x]/[X] 更改为 [ ]。
        • 如果状态未更改:保持不变。
        • 跳过任何无法客观从规格本身确定的项目(例如,需要人工判断或外部测试的),其状态不变。
      6. 如果至少一个复选框更改了状态,请输出一个包含已更改项摘要的 Markdown 表格:
        项目之前状态之后状态
        <项目文本>[ ] 或 [x][ ] 或 [x]
      7. 在表格后,添加一个最终项目符号:- 向用户建议他们现在可以运行 /speckit-plan 来继续。
      8. 将更新后的检查清单写回其文件。
  10. 输出最终结果:

    • ## 验证摘要 章节,包含:
      • 总接受的问题数:<数字>
      • 更新的章节:<逗号分隔的列表>
      • 是否更新了检查清单:是/否

Individual skills in this repo

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

相关技能