验证实现是否与变更 artifact(specs、tasks、design)一致。
输入:可选指定变更名称。若未提供,尝试从对话上下文中推断。若含糊不清,必须提示用户选择可用的变更。
步骤
若未提供变更名称,提示用户选择
运行
openspec list --json获取可用变更。使用 AskUserQuestion 工具让用户选择。只显示有实现任务的变更(tasks artifact 存在)。 若可用,显示每个变更所用的 schema。 将有未完成任务的变更标记为"(进行中)"。
重要:不要猜测或自动选择变更,始终让用户做选择。
检查状态以了解 schema
openspec status --change "<name>" --json解析 JSON 以了解:
schemaName:正在使用的工作流(例如 "spec-driven")- 此变更存在哪些 artifact
获取变更目录并加载 artifact
openspec instructions apply --change "<name>" --json返回变更目录和上下文文件。从
contextFiles读取所有可用的 artifact。初始化验证报告结构
创建包含三个维度的报告结构:
- 完整性(Completeness):跟踪任务和 spec 覆盖情况
- 正确性(Correctness):跟踪需求实现和场景覆盖情况
- 连贯性(Coherence):跟踪设计遵从情况和模式一致性
每个维度可包含 CRITICAL(严重)、WARNING(警告)或 SUGGESTION(建议)类型的问题。
验证完整性
任务完成情况:
- 若 contextFiles 中存在 tasks.md,读取它
- 解析复选框:
- [ ](未完成)与- [x](已完成) - 统计已完成与总任务数
- 若存在未完成任务:
- 对每个未完成任务添加 CRITICAL 问题
- 建议:"完成任务:<描述>"或"若已实现则标记为完成"
Spec 覆盖情况:
- 若
openspec/changes/<name>/specs/中存在增量 spec:- 提取所有需求(标有 "### Requirement:" 的行)
- 对每个需求:
- 在代码库中搜索与需求相关的关键词
- 评估实现是否可能存在
- 若需求似乎未实现:
- 添加 CRITICAL 问题:"未找到需求:<需求名称>"
- 建议:"实现需求 X:<描述>"
验证正确性
需求实现映射:
- 对增量 spec 中的每个需求:
- 在代码库中搜索实现证据
- 若找到,记录文件路径和行范围
- 评估实现是否符合需求意图
- 若发现偏差:
- 添加 WARNING:"实现可能偏离 spec:<详情>"
- 建议:"对照需求 X 检查 :"
场景覆盖情况:
- 对增量 spec 中的每个场景(标有 "#### Scenario:" 的行):
- 检查代码中是否处理了该条件
- 检查是否存在覆盖该场景的测试
- 若场景似乎未覆盖:
- 添加 WARNING:"场景未覆盖:<场景名称>"
- 建议:"为场景添加测试或实现:<描述>"
- 对增量 spec 中的每个需求:
验证连贯性
设计遵从情况:
- 若 contextFiles 中存在 design.md:
- 提取关键决策(查找 "Decision:"、"Approach:"、"Architecture:" 等节)
- 验证实现是否遵循了这些决策
- 若发现矛盾:
- 添加 WARNING:"未遵循设计决策:<决策>"
- 建议:"更新实现或修改 design.md 以匹配现实"
- 若不存在 design.md:跳过设计遵从检查,注明"无 design.md 可供验证"
代码模式一致性:
- 检查新代码与项目模式的一致性
- 检查文件命名、目录结构、编码风格
- 若发现明显偏差:
- 添加 SUGGESTION:"代码模式偏差:<详情>"
- 建议:"考虑遵循项目模式:<示例>"
- 若 contextFiles 中存在 design.md:
生成验证报告
摘要评分卡:
## 验证报告:<change-name> ### 摘要 | 维度 | 状态 | |----------|--------------------| | 完整性 | X/Y 任务,N 个需求 | | 正确性 | M/N 个需求已覆盖 | | 连贯性 | 已遵循/有问题 |按优先级分组的问题:
CRITICAL 严重(归档前必须修复):
- 未完成的任务
- 缺失的需求实现
- 每项附有具体、可操作的建议
WARNING 警告(应该修复):
- Spec/设计偏差
- 缺少场景覆盖
- 每项附有具体建议
SUGGESTION 建议(可选修复):
- 模式不一致
- 小改进
- 每项附有具体建议
最终评估:
- 若有 CRITICAL 问题:"发现 X 个严重问题。归档前请修复。"
- 若只有警告:"无严重问题。有 Y 个警告供参考。可以归档(注意已提及的改进点)。"
- 若全部通过:"所有检查通过。可以归档了。"
验证启发式方法
- 完整性:聚焦于客观的清单项(复选框、需求列表)
- 正确性:使用关键词搜索、文件路径分析、合理推断——不需要完全确定
- 连贯性:查找明显的不一致,不要吹毛求疵
- 误报处理:不确定时,倾向于 SUGGESTION 而非 WARNING,WARNING 而非 CRITICAL
- 可操作性:每个问题必须附有具体建议,尽可能带文件/行号引用
降级处理
- 若只存在 tasks.md:仅验证任务完成情况,跳过 spec/design 检查
- 若存在 tasks + specs:验证完整性和正确性,跳过设计
- 若存在完整 artifact:验证所有三个维度
- 始终注明跳过了哪些检查及原因
输出格式
使用清晰的 Markdown,包括:
- 摘要评分卡表格
- 按问题类型分组的列表(CRITICAL/WARNING/SUGGESTION)
- 代码引用格式:
file.ts:123 - 具体、可操作的建议
- 不使用"考虑审查"之类的模糊建议