name	speckit-analyze
description	在任务生成后, 对 spec.md, plan.md 和 tasks.md 执行非破坏性的跨制品一致性和质量分析.
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"templates/commands/analyze.md"}
disable-model-invocation	true

用户输入

$ARGUMENTS

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

目标

在实施之前, 识别三个核心制品(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-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]
引用的文件路径

从章程:

加载 .specify/memory/constitution.md 进行原则验证

3. 构建语义模型

创建内部表示(输出中不包含原始制品):

需求清单: 为每个功能需求(FR-###)和成功标准(SC-###)记录一个稳定键. 当存在显式 FR-/SC- 标识符时, 使用该标识符作为主键, 并可选择推导一个祈使短语 slug 以提高可读性(例如, "User can upload file" → user-can-upload-file). 仅包含需要构建工作的成功标准项(例如, 负载测试基础设施, 安全审计工具), 排除发布后的结果指标和业务 KPI(例如, "将支持工单减少 50%").
用户故事/操作清单: 带有验收标准的离散用户操作
任务覆盖映射: 将每个任务映射到一个或多个需求或故事(通过关键词/显式引用模式推断, 如 ID 或关键短语)
章程规则集: 提取原则名称和 MUST/SHOULD 规范性声明

4. 检测过程(高效令牌分析)

专注于高信号发现. 限制总共 50 个发现; 在溢出摘要中聚合其余部分.

A. 重复检测

识别近似重复的需求
标记较低质量的表述以进行合并

B. 模糊性检测

标记缺乏可测量标准的模糊形容词(快速, 可扩展, 安全, 直观, 稳健)
标记未解决的占位符(TODO, TKTK, ???, <placeholder> 等)

C. 规范不足

有动词但缺少对象或可测量结果的需求
缺少验收标准对齐的用户故事
引用规范/计划中未定义的文件或组件的任务

D. 章程对齐

与 MUST 原则冲突的任何需求或计划元素
章程中缺失的强制部分或质量门控

E. 覆盖缺口

没有关联任务的需求
没有映射需求/故事的任务
需要构建工作的成功标准(性能, 安全性, 可用性)未在任务中反映

F. 不一致性

术语漂移(相同概念在不同文件中命名不同)
计划中引用但在规范中缺失的数据实体(反之亦然)
任务排序矛盾(例如, 集成任务在基础设置任务之前而没有依赖说明)
冲突需求(例如, 一个要求 Next.js 而另一个指定 Vue)

5. 严重性分配

使用此启发式方法对发现进行优先级排序:

严重: 违反章程 MUST, 缺失核心规范制品, 或零覆盖的需求阻止基线功能
高: 重复或冲突需求, 模糊的安全/性能属性, 不可测试的验收标准
中: 术语漂移, 缺失非功能任务覆盖, 规范不足的边缘情况
低: 风格/措辞改进, 不影响执行顺序的轻微冗余

6. 生成紧凑分析报告

输出 Markdown 报告(不写入文件), 结构如下:

规范分析报告

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

(每个发现添加一行; 生成以类别首字母为前缀的稳定 ID.)

覆盖摘要表:

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

章程对齐问题: (如果有)

未映射任务: (如果有)

指标:

总需求数
总任务数
覆盖率%(有 >=1 个任务的需求)
模糊性计数
重复计数
严重问题计数

7. 提供下一步操作

在报告末尾, 输出简洁的下一步操作块:

如果存在严重问题: 建议在 /speckit.implement 之前解决
如果只有低/中问题: 用户可以继续, 但提供改进建议
提供明确的命令建议: 例如, "运行 /speckit.specify 进行细化", "运行 /speckit.plan 调整架构", "手动编辑 tasks.md 为 'performance-metrics' 添加覆盖"