speckit-analyze

用户输入

$ARGUMENTS

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

执行前检查

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

• 检查项目根目录中是否存在 .specify/extensions.yml。
• 如果存在，读取该文件并查找 hooks.before_analyze 键下的条目。
• 如果 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}
    
    继续执行目标前，等待钩子命令的结果。
    

    输出上述内容后，必须实际调用该钩子并等待其执行完成，然后才能继续。按照在此 Agent/会话中自行运行命令的方式运行它（调用方式可能不同于显示的 {command} ID，例如，技能模式 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出该内容并不能运行钩子。

• 如果没有注册任何钩子，或 .specify/extensions.yml 不存在，则静默跳过。

目标

在开始实施之前，找出三个核心文档（spec.md、plan.md、tasks.md）中的不一致、重复、歧义和未充分说明的事项。只有在 /speckit-tasks 成功生成完整的 tasks.md 后，才能运行此命令。

操作约束

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

宪法具有最高效力：在本分析范围内，项目宪法（.specify/memory/constitution.md）不可协商。违反宪法的内容一律视为严重问题，必须调整规范、计划或任务，而不能弱化、重新解释或默默忽略相关原则。如需修改原则本身，必须在 /speckit-analyze 之外，通过单独、明确的宪法更新进行。

执行步骤

1. 初始化分析上下文

从仓库根目录运行一次 .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks，并解析 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 中加载：

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

3. 构建语义模型

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

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

4. 检测环节（节省 Token 的分析）

重点关注高信号问题。发现总数最多为 50 条；其余内容汇总到溢出摘要中。

A. 重复检测

• 识别近似重复的需求
• 标记质量较低、需要合并的措辞

B. 歧义检测

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

C. 规范不足

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

D. 宪章一致性

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

E. 覆盖缺口

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

F. 不一致

• 术语漂移（在不同文件中以不同名称指代同一概念）
• 计划中引用、但 spec 中未定义的数据实体（反之亦然）
• 任务顺序矛盾（例如，未注明依赖关系，却在基础设置任务之前安排集成任务）
• 相互冲突的需求（例如，一个要求使用 Next.js，另一个指定 Vue）

5. 分配严重程度

使用以下启发式规则确定问题优先级：

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

6. 生成精简分析报告

输出一份 Markdown 报告（不写入文件），并采用以下结构：

规范分析报告

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

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

覆盖率摘要表：

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

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

未映射的任务：（如有）

指标：

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

7. 提供后续行动

在报告末尾输出简洁的“后续行动”区块：

• 如果存在严重问题：建议在 /speckit-implement 之前解决
• 如果只有低/中严重程度问题：用户可以继续，但请提供改进建议
• 提供明确的命令建议，例如：“运行 /speckit-specify 并进行完善”“运行 /speckit-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 实现
• 根据钩子命令名称构造命令调用时，将句点（.）替换为连字符（-）。例如，speckit.git.commit → /speckit-git-commit。
• 对于每个可执行钩子，根据其 optional 标志输出以下内容：

  • 可选钩子（optional: true）：

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

  • 强制钩子（optional: false）：

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

    输出上述区块后，必须实际调用该钩子并等待其执行完毕，然后才能继续。按照你在此 Agent/会话中运行命令的方式执行（调用方式可能与显示的 {command} ID 不同，例如，技能模式的 Agent 会运行 /skill:speckit-... 或 $speckit-...）。仅输出该区块并不等于运行了钩子。

• 如果没有注册钩子，或 .specify/extensions.yml 不存在，则静默跳过

操作原则

上下文效率

• 精简且高信号的内容：聚焦于可执行的发现，而非详尽的文档
• 渐进式披露：逐步加载工件；不要一次性倾倒所有内容
• 令牌高效的输出：发现表最多列出 50 行；超出部分应汇总
• 结果确定性：在没有变更的情况下重新运行，应生成一致的 ID 和计数

分析指南

• 绝不修改文件（这是只读分析）
• 绝不臆造缺失章节（如果缺失，请如实报告）
• 优先处理违反 constitution 的问题（这类问题始终属于严重问题）
• 优先使用示例，而非穷举规则（引用具体实例，而非泛泛的模式）
• 妥善报告零问题的情况（输出附带覆盖率统计的成功报告）

上下文

$ARGUMENTS