speckit-analyze

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' 添加覆盖"

8. 提供修复

询问用户: "你希望我为前 N 个问题建议具体的修复编辑吗?" (不要自动应用它们.)

操作原则

上下文效率

• 最小高信噪比令牌: 专注于可操作的发现, 而不是详尽的文档
• 渐进式展示: 增量加载制品; 不要将所有内容倾倒到分析中
• 高效令牌输出: 限制发现表为 50 行; 总结溢出部分
• 确定性结果: 无更改重新运行应产生一致的 ID 和计数

分析指南

• 绝不修改文件 (这是只读分析)
• 绝不虚构缺失部分 (如果缺失, 准确报告)
• 优先处理章程违规 (这些总是严重的)
• 使用示例而非详尽规则 (引用具体实例, 而不是通用模式)
• 优雅报告零问题 (发出带有覆盖统计的成功报告)

上下文

$ARGUMENTS