speckit-analyze

speckit-analyze

此技能内容源自 GitHub Spec Kit 官方提示词模板。

• 上游：https://github.com/github/spec-kit
• 许可：MIT License，Copyright GitHub, Inc.（完整文本见同目录 LICENSE.txt）
• 适配说明：官方模板面向斜杠命令场景；原文中的 $ARGUMENTS 指用户在对话中给出的请求， 跨命令引用（如 speckit.plan）在本技能体系中对应同名的 speckit-* 技能。 其余内容与上游保持一致，未作改写。

---

用户输入

$ARGUMENTS

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

执行前检查

检查扩展钩子（分析前）：

• 检查项目根目录下是否存在 .specify/extensions.yml。
• 如果存在，读取该文件并查找 hooks.before_analyze 键下的条目。
• 如果 YAML 无法解析或无效，不要默默跳过：告知用户无法读取 .specify/extensions.yml（附上解析器错误），并说明未检查任何钩子，包括其中注册的任何强制钩子（optional: false），然后正常继续。
• 筛除 enabled 明确设为 false 的钩子。未设置 enabled 字段的钩子默认视为启用。
• 对于其余钩子，不要尝试解读或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空，则视为可执行钩子。
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现。
• 对于每个可执行钩子，根据其 optional 标志输出以下内容：
  • 可选钩子（optional: true）：

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • 强制钩子（optional: false）：

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to the Goal.
    

    输出以上代码块后，必须实际调用该钩子，并等待其完成后再继续。调用方式应与在当前 Agent/会话中执行命令的方式相同（调用方式可能不同于上方显示的字面 {command} 标识，例如，技能模式下的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出代码块并不会运行钩子。
• 如果未注册任何钩子，或 .specify/extensions.yml 不存在，则静默跳过。

目标

在实现之前，识别三个核心工件（spec.md、plan.md、tasks.md）中的不一致、重复、歧义和未充分说明的条目。只有在 __SPECKIT_COMMAND_TASKS__ 成功生成完整的 tasks.md 后，才能运行此命令。

操作约束

严格只读：不得修改任何文件。输出结构化分析报告。可提供可选的修复计划（用户必须明确批准，之后才可手动调用任何后续编辑命令）。

宪章权威性：项目宪章（/memory/constitution.md）在此分析范围内具有不可协商的效力。与宪章冲突的事项自动视为严重问题，必须调整规范、计划或任务；不得弱化、重新解释或默默忽略该原则。如果某项原则本身需要修改，必须在 __SPECKIT_COMMAND_ANALYZE__ 之外单独、明确地更新宪章。

执行步骤

1. 初始化分析上下文

从仓库根目录运行 {SCRIPT} 一次，并解析 JSON 以获取 FEATURE_DIR 和 AVAILABLE_DOCS。推导绝对路径：

• SPEC = FEATURE_DIR/spec.md
• PLAN = FEATURE_DIR/plan.md
• TASKS = FEATURE_DIR/tasks.md

如果缺少任何必需文件，则中止并显示错误消息（指示用户运行缺失的前置命令）。 对于类似 "I'm Groot" 的参数中的单引号，使用转义语法，例如 'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。

2. 加载工件（渐进式披露）

仅从每个工件中加载必要的最少上下文：

从 spec.md 中加载：

• 概述/背景
• 功能需求
• 成功标准（可衡量的结果，例如性能、安全性、可用性、用户成功度、业务影响）
• 用户故事
• 边缘情况（如有）

从 plan.md 中加载：

• 架构/技术栈选择
• 数据模型引用
• 阶段
• 技术约束

从 tasks.md 中加载：

• 任务 ID
• 描述
• 阶段分组
• 并行标记 [P]
• 引用的文件路径

从 constitution 中加载：

• 加载 /memory/constitution.md，用于原则验证

3. 构建语义模型

创建内部表示（不要在输出中包含原始工件）：

• 需求清单：为每个功能需求（FR-###）和成功标准（SC-###）记录一个稳定键。存在明确的 FR-/SC-标识符时，将其用作主键；也可选择派生一个便于阅读的祈使短语 slug（例如，“用户可以上传文件” → user-can-upload-file）。仅包含需要构建工作的成功标准（例如，负载测试基础设施、安全审计工具），排除上线后的结果指标和业务 KPI（例如，“减少 50% 的支持工单”）。
• 用户故事/操作清单：包含验收标准的离散用户操作
• 任务覆盖映射：将每项任务映射到一个或多个需求或故事（根据关键词或明确引用模式推断，例如 ID 或关键短语）
• 宪章规则集：提取原则名称以及 MUST/SHOULD 规范性陈述

4. 检测环节（令牌高效分析）

聚焦高信号发现。发现总数上限为 50 项；其余内容汇总到溢出摘要中。

A. 重复检测

• 找出近似重复的需求
• 标记质量较低、需要合并的表述

B. 歧义检测

• 标记缺少可衡量标准的模糊形容词（快速、可扩展、安全、直观、健壮）
• 标记未解决的占位符（TODO、TKTK、???、<placeholder> 等）

C. 规范不足

• 存在动词但缺少对象或可衡量结果的需求
• 缺少验收标准对齐的用户故事
• 引用了 spec/plan 中未定义文件或组件的任务

D. 宪章对齐

• 与 MUST 原则冲突的需求或计划要素
• 缺少宪章规定的章节或质量门禁

E. 覆盖缺口

• 没有关联任务的需求
• 没有映射需求/故事的任务
• 需要构建工作（性能、安全性、可用性）的成功标准未体现在任务中

F. 不一致

• 术语漂移（同一概念在不同文件中使用不同名称）
• 计划中引用但 spec 中缺失（或反之）的数据实体
• 任务顺序矛盾（例如，在没有依赖说明的情况下，集成任务排在基础设置任务之前）
• 需求冲突（例如，一个要求使用 Next.js，另一个指定 Vue）

5. 严重性分级

使用以下启发式规则对发现进行优先级排序：

• CRITICAL：违反宪章 MUST、缺少核心规范工件，或没有任何任务覆盖且会阻碍基线功能的需求
• HIGH：重复或冲突的需求、含糊的安全/性能属性、不可测试的验收标准
• MEDIUM：术语漂移、缺少非功能性任务覆盖、规范不足的边缘情况
• LOW：风格/措辞改进、不影响执行顺序的轻微冗余

6. 输出简洁的分析报告

输出一份 Markdown 报告（不写入文件），结构如下：

规格分析报告

ID	类别	严重程度	位置	摘要	建议
A1	重复	HIGH	spec.md:L120-134	两项相似的需求 ...	合并表述；保留更清晰的版本

（每项发现添加一行；生成以类别首字母为前缀的稳定 ID。）

覆盖情况摘要表：

需求键	是否有任务？	任务 ID	备注

与宪章的一致性问题：（如有）

未映射的任务：（如有）

指标：

• 需求总数
• 任务总数
• 覆盖率（至少有 1 个任务的需求占比）
• 模糊项数量
• 重复项数量
• 严重问题数量

7. 提供后续行动

在报告末尾输出简洁的后续行动部分：

• 如果存在 CRITICAL 问题：建议在 __SPECKIT_COMMAND_IMPLEMENT__ 之前解决
• 如果只有 LOW/MEDIUM 问题：用户可以继续，但请提供改进建议
• 提供明确的命令建议，例如：“运行 SPECKIT_COMMAND_SPECIFY 并进行细化”、“运行 SPECKIT_COMMAND_PLAN 以调整架构”、“手动编辑 tasks.md，为 'performance-metrics' 添加覆盖”

8. 提供修复建议

询问用户：“您希望我针对排名靠前的 N 个问题提出具体的修复编辑建议吗？”（不要自动应用。）

9. 检查扩展钩子

报告后，检查项目根目录中是否存在 .specify/extensions.yml。

• 如果存在，读取文件并查找 hooks.after_analyze 键下的条目
• 如果 YAML 无法解析或无效，不要静默跳过：告知用户无法读取 .specify/extensions.yml（包含解析器错误），且未检查任何钩子，包括其中注册的任何强制（optional: false）钩子，然后正常继续
• 过滤掉 enabled 明确为 false 的钩子。没有 enabled 字段的钩子默认视为启用。
• 对于其余钩子，不要尝试解读或评估钩子的 condition 表达式：
  • 如果钩子没有 condition 字段，或该字段为 null/空值，则视为可执行
  • 如果钩子定义了非空的 condition，则跳过该钩子，并将条件评估留给 HookExecutor 实现
• 对于每个可执行钩子，根据其 optional 标志输出以下内容：
  • 可选钩子（optional: true）：

    ## 扩展钩子
    
    **可选钩子**：{extension}
    命令：`/{command}`
    描述：{description}
    
    提示词：{prompt}
    执行方式：`/{command}`
    

  • 强制钩子（optional: false）：

    ## 扩展钩子
    
    **自动钩子**：{extension}
    正在执行：`/{command}`
    EXECUTE_COMMAND: {command}
    

    输出上述代码块后，必须实际调用钩子并等待其完成，然后才能继续。调用方式应与在此 Agent/会话中自行运行命令的方式相同（调用方式可能与显示的 {command} ID 不同，例如，skills 模式的 Agent 会将其作为 /skill:speckit-... 或 $speckit-... 运行）。仅输出代码块并不会运行钩子。
• 如果没有注册钩子，或 .specify/extensions.yml 不存在，则静默跳过

操作原则

上下文效率

• 尽量使用精简且信息量高的 Token：聚焦于可执行的发现，而非详尽的文档
• 渐进式披露：逐步加载工件；不要一次性倾倒所有内容进行分析
• 输出节省 Token：发现表最多保留 50 行；超出部分汇总
• 结果确定性：在无更改的情况下重新运行，应得到一致的 ID 和计数

分析指南

• 绝不修改文件（这是只读分析）
• 绝不臆造缺失的章节（若章节不存在，请如实报告）
• 优先处理违反章程的问题（这些始终属于严重问题）
• 优先使用示例，而非穷尽所有规则（引用具体实例，而非泛泛而谈）
• 妥善报告零问题的情况（输出包含覆盖率统计信息的成功报告）

上下文

{ARGS}