Speckit.Analyze

用户输入

$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. 构建语义模型

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

• 需求清单: 每个功能和非功能需求, 带有稳定键(基于祈使短语推导 slug; 例如, "User can upload file" → user-can-upload-file)
• 用户故事/操作清单: 带有验收标准的离散用户操作
• 任务覆盖映射: 将每个任务映射到一个或多个需求或故事(通过关键词/显式引用模式推断, 如 ID 或关键短语)
• 章程规则集: 提取原则名称和 MUST/SHOULD 规范性声明

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

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

A. 重复检测

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

B. 模糊性检测

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

C. 规范不足

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

D. 章程对齐

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

E. 覆盖缺口

• 没有关联任务的需求
• 没有映射需求/故事的任务
• 未在任务中反映的非功能需求(例如, 性能、安全性)

F. 不一致性

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

5. 严重性分配

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

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

6. 生成紧凑分析报告

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

规范分析报告

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

**覆盖摘要表: **

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

**未映射任务: **(如果有)

**指标: **

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

7. 提供下一步操作

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

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

8. 提供修复

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

操作原则

上下文效率

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

分析指南

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

上下文

$ARGUMENTS