验证实现是否与变更产出物(规范、任务、设计)匹配。
输入:可选指定变更名称。如果省略,检查是否可以从对话上下文中推断。如果模糊或不明确,你必须提示获取可用变更。
步骤
- 如果没有提供变更名称,提示选择 运行
openspec-cn list --json获取可用变更。使用 AskUserQuestion tool 让用户选择。 显示具有实现任务的变更(存在任务产出物)。 如果可用,包括每个变更使用的 Schema。 将任务未完成的变更标记为 "(进行中)"。 重要提示:不要猜测或自动选择变更。始终让用户选择。 - 检查状态以了解 Schema
openspec-cn status --change "<name>" --jsonParse the JSON to understand:
- schemaName: The workflow being used (e.g., "spec-driven") - Which artifacts exist for this change
- 获取变更目录并加载产出物
openspec-cn instructions apply --change "<name>" --json这会返回变更目录和上下文文件。从contextFiles读取所有可用产出物。 - 初始化验证报告结构 创建具有三个维度的报告结构: 每个维度可以有 CRITICAL、WARNING 或 SUGGESTION 问题。
- 完整性:跟踪任务和规范覆盖率 - 正确性:跟踪需求实现和场景覆盖率 - 一致性:跟踪设计遵循情况和模式一致性
- 验证完整性 任务完成情况: 规范覆盖率:
- 如果 contextFiles 中存在 tasks.md,读取它 - 解析复选框:- [](未完成)vs - [x](已完成) - 统计已完成 vs 总任务数 - 如果存在未完成的任务: - 为每个未完成任务添加 CRITICAL 问题 - 建议:"完成任务:<描述>" 或 "如果已实现则标记为完成" - 如果 openspec/changes/<name>/specs/ 中存在增量规范: - 提取所有需求(标记为 "### Requirement:") - 对于每个需求: - 在代码库中搜索与需求相关的关键词 - 评估实现是否可能存在 - 如果需求看起来未实现: - 添加 CRITICAL 问题:"未找到需求:<需求名称>" - 建议:"实现需求 X:<描述>"
- 验证正确性 需求实现映射: 场景覆盖率:
- 对于增量规范中的每个需求: - 在代码库中搜索实现证据 - 如果找到,记录文件路径和行范围 - 评估实现是否符合需求意图 - 如果检测到偏差: - 添加 WARNING:"实现可能偏离规范:<详情>" - 建议:"根据需求 X 审查 <文件>:<行>" - 对于增量规范中的每个场景(标记为 "#### Scenario:"): - 检查代码中是否处理了条件 - 检查是否存在覆盖该场景的测试 - 如果场景看起来未覆盖: - 添加 WARNING:"场景未覆盖:<场景名称>" - 建议:"为场景添加测试或实现:<描述>"
- 验证一致性 设计遵循情况: 代码模式一致性:
- 如果 contextFiles 中存在 design.md: - 提取关键决策(查找 "Decision:"、"Approach:"、"Architecture:" 等部分) - 验证实现是否遵循这些决策 - 如果检测到矛盾: - 添加 WARNING:"未遵循设计决策:<决策>" - 建议:"更新实现或修订 design.md 以匹配实际情况" - 如果没有 design.md:跳过设计遵循检查,注明 "没有 design.md 可供验证" - 审查新代码与项目模式的一致性 - 检查文件命名、目录结构、编码风格 - 如果发现重大偏差: - 添加 SUGGESTION:"代码模式偏差:<详情>" - 建议:"考虑遵循项目模式:<示例>"
- 生成验证报告 摘要记分卡:
## 验证报告:<change-name> ### 摘要 | 维度 | 状态 | |----------|------------------| | 完整性 | X/Y 任务,N 需求 | | 正确性 | M/N 需求已覆盖 | | 一致性 | 已遵循/存在问题 |按优先级分类的问题: 最终评估:
1. CRITICAL(归档前必须修复): - 未完成的任务 - 缺失的需求实现 - 每个都有具体的、可操作的建议 2. WARNING(应该修复): - 规范/设计偏差 - 缺失的场景覆盖 - 每个都有具体的建议 3. SUGGESTION(最好修复): - 模式不一致 - 小改进 - 每个都有具体的建议 - 如果有 CRITICAL 问题:"发现 X 个关键问题。归档前请修复。" - 如果只有警告:"没有关键问题。有 Y 个警告需要考虑。可以归档(但建议改进)。" - 如果全部通过:"所有检查通过。可以归档。"
验证启发式方法
- 完整性:关注客观的检查清单项(复选框、需求列表)
- 正确性:使用关键词搜索、文件路径分析、合理推断 - 不要求完全确定
- 一致性:寻找明显的不一致,不要挑剔风格
- 误报:不确定时,优先使用 SUGGESTION 而非 WARNING,WARNING 而非 CRITICAL
- 可操作性:每个问题都必须有具体的建议,并在适用时提供文件/行引用
优雅降级
- 如果只存在 tasks.md:仅验证任务完成情况,跳过规范/设计检查
- 如果存在任务 + 规范:验证完整性和正确性,跳过设计
- 如果存在完整产出物:验证所有三个维度
- 始终注明跳过了哪些检查以及原因
输出格式
使用清晰的 Markdown:
- 摘要记分卡使用表格
- 问题按组列出(CRITICAL/WARNING/SUGGESTION)
- 代码引用格式:
file.ts:123 - 具体的、可操作的建议
- 不要使用模糊的建议,如 "考虑审查"