169 lines
6.0 KiB
Markdown
169 lines
6.0 KiB
Markdown
|
---
|
||
|
|
name: openspec-verify-change
|
||
|
|
description: Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.
|
||
|
|
license: MIT
|
||
|
|
compatibility: Requires openspec CLI.
|
||
|
|
metadata:
|
||
|
|
author: openspec
|
||
|
|
version: "1.0"
|
||
|
|
generatedBy: "1.1.1"
|
||
|
|
---
|
||
|
|
|
||
|
|
验证实现是否与变更 artifacts (specs、tasks、design) 匹配。
|
||
|
|
|
||
|
|
**输入**: 可选择指定变更名称。如果省略,检查是否可以从对话上下文中推断。如果模糊或不明确,你**必须**提示可用的变更。
|
||
|
|
|
||
|
|
**步骤**
|
||
|
|
|
||
|
|
1. **如果未提供变更名称,提示用户选择**
|
||
|
|
|
||
|
|
运行 `openspec list --json` 获取可用的变更。使用 **AskUserQuestion 工具**让用户选择。
|
||
|
|
|
||
|
|
显示具有实现任务的变更 (tasks artifact 存在)。
|
||
|
|
如果可用,包含每个变更使用的 schema。
|
||
|
|
将具有未完成任务的变更标记为 "(进行中)"。
|
||
|
|
|
||
|
|
**重要**: 不要猜测或自动选择变更。始终让用户选择。
|
||
|
|
|
||
|
|
2. **检查状态以了解 schema**
|
||
|
|
```bash
|
||
|
|
openspec status --change "<name>" --json
|
||
|
|
```
|
||
|
|
解析 JSON 以了解:
|
||
|
|
- `schemaName`: 正在使用的工作流 (例如: "spec-driven")
|
||
|
|
- 此变更存在哪些 artifacts
|
||
|
|
|
||
|
|
3. **获取变更目录并加载 artifacts**
|
||
|
|
|
||
|
|
```bash
|
||
|
|
openspec instructions apply --change "<name>" --json
|
||
|
|
```
|
||
|
|
|
||
|
|
这将返回变更目录和上下文文件。从 `contextFiles` 读取所有可用的 artifacts。
|
||
|
|
|
||
|
|
4. **初始化验证报告结构**
|
||
|
|
|
||
|
|
创建具有三个维度的报告结构:
|
||
|
|
- **完整性 (Completeness)**: 跟踪任务和 spec 覆盖率
|
||
|
|
- **正确性 (Correctness)**: 跟踪需求实现和场景覆盖
|
||
|
|
- **一致性 (Coherence)**: 跟踪设计遵循情况和模式一致性
|
||
|
|
|
||
|
|
每个维度可以有 CRITICAL、WARNING 或 SUGGESTION 问题。
|
||
|
|
|
||
|
|
5. **验证完整性**
|
||
|
|
|
||
|
|
**任务完成度**:
|
||
|
|
- 如果 contextFiles 中存在 tasks.md,读取它
|
||
|
|
- 解析复选框: `- [ ]` (未完成) vs `- [x]` (已完成)
|
||
|
|
- 统计已完成任务 vs 总任务数
|
||
|
|
- 如果存在未完成的任务:
|
||
|
|
- 为每个未完成的任务添加 CRITICAL 问题
|
||
|
|
- 建议: "完成任务: <描述>" 或 "如果已实现请标记为完成"
|
||
|
|
|
||
|
|
**Spec 覆盖率**:
|
||
|
|
- 如果 `openspec/changes/<name>/specs/` 中存在 delta specs:
|
||
|
|
- 提取所有需求 (标记为 "### Requirement:")
|
||
|
|
- 对于每个需求:
|
||
|
|
- 在代码库中搜索与需求相关的关键字
|
||
|
|
- 评估实现是否可能存在
|
||
|
|
- 如果需求看起来未实现:
|
||
|
|
- 添加 CRITICAL 问题: "未找到需求: <需求名称>"
|
||
|
|
- 建议: "实现需求 X: <描述>"
|
||
|
|
|
||
|
|
6. **验证正确性**
|
||
|
|
|
||
|
|
**需求实现映射**:
|
||
|
|
- 对于 delta specs 中的每个需求:
|
||
|
|
- 在代码库中搜索实现证据
|
||
|
|
- 如果找到,记录文件路径和行范围
|
||
|
|
- 评估实现是否符合需求意图
|
||
|
|
- 如果检测到偏差:
|
||
|
|
- 添加 WARNING: "实现可能偏离 spec: <详情>"
|
||
|
|
- 建议: "根据需求 X 审查 <file>:<lines>"
|
||
|
|
|
||
|
|
**场景覆盖**:
|
||
|
|
- 对于 delta specs 中的每个场景 (标记为 "#### Scenario:"):
|
||
|
|
- 检查代码中是否处理了条件
|
||
|
|
- 检查是否存在覆盖该场景的测试
|
||
|
|
- 如果场景看起来未覆盖:
|
||
|
|
- 添加 WARNING: "场景未覆盖: <场景名称>"
|
||
|
|
- 建议: "为场景添加测试或实现: <描述>"
|
||
|
|
|
||
|
|
7. **验证一致性**
|
||
|
|
|
||
|
|
**设计遵循**:
|
||
|
|
- 如果 contextFiles 中存在 design.md:
|
||
|
|
- 提取关键决策 (查找类似 "Decision:", "Approach:", "Architecture:" 的部分)
|
||
|
|
- 验证实现是否遵循这些决策
|
||
|
|
- 如果检测到矛盾:
|
||
|
|
- 添加 WARNING: "未遵循设计决策: <决策>"
|
||
|
|
- 建议: "更新实现或修订 design.md 以匹配实际情况"
|
||
|
|
- 如果没有 design.md: 跳过设计遵循检查,注明 "没有 design.md 可供验证"
|
||
|
|
|
||
|
|
**代码模式一致性**:
|
||
|
|
- 审查新代码与项目模式的一致性
|
||
|
|
- 检查文件命名、目录结构、编码风格
|
||
|
|
- 如果发现重大偏差:
|
||
|
|
- 添加 SUGGESTION: "代码模式偏差: <详情>"
|
||
|
|
- 建议: "考虑遵循项目模式: <示例>"
|
||
|
|
|
||
|
|
8. **生成验证报告**
|
||
|
|
|
||
|
|
**总结记分卡**:
|
||
|
|
```
|
||
|
|
## 验证报告: <change-name>
|
||
|
|
|
||
|
|
### 总结
|
||
|
|
| 维度 | 状态 |
|
||
|
|
|-----------|-------------------|
|
||
|
|
| 完整性 | X/Y 任务, N 需求 |
|
||
|
|
| 正确性 | M/N 需求已覆盖 |
|
||
|
|
| 一致性 | 已遵循/有问题 |
|
||
|
|
```
|
||
|
|
|
||
|
|
**按优先级分类的问题**:
|
||
|
|
|
||
|
|
1. **CRITICAL** (归档前必须修复):
|
||
|
|
- 未完成的任务
|
||
|
|
- 缺失的需求实现
|
||
|
|
- 每个都有具体、可操作的建议
|
||
|
|
|
||
|
|
2. **WARNING** (应该修复):
|
||
|
|
- Spec/design 偏差
|
||
|
|
- 缺失的场景覆盖
|
||
|
|
- 每个都有具体建议
|
||
|
|
|
||
|
|
3. **SUGGESTION** (最好修复):
|
||
|
|
- 模式不一致
|
||
|
|
- 小改进
|
||
|
|
- 每个都有具体建议
|
||
|
|
|
||
|
|
**最终评估**:
|
||
|
|
- 如果有 CRITICAL 问题: "发现 X 个关键问题。归档前请修复。"
|
||
|
|
- 如果只有警告: "无关键问题。有 Y 个警告需要考虑。准备归档 (带注明的改进)。"
|
||
|
|
- 如果全部通过: "所有检查通过。准备归档。"
|
||
|
|
|
||
|
|
**验证启发式方法**
|
||
|
|
|
||
|
|
- **完整性**: 专注于客观的检查清单项 (复选框、需求列表)
|
||
|
|
- **正确性**: 使用关键字搜索、文件路径分析、合理推断 - 不要求完全确定
|
||
|
|
- **一致性**: 寻找明显的不一致,不要挑剔风格
|
||
|
|
- **误报**: 如果不确定,优先选择 SUGGESTION 而不是 WARNING,WARNING 而不是 CRITICAL
|
||
|
|
- **可操作性**: 每个问题都必须有具体的建议,并在适用时提供文件/行引用
|
||
|
|
|
||
|
|
**优雅降级**
|
||
|
|
|
||
|
|
- 如果只存在 tasks.md: 仅验证任务完成度,跳过 spec/design 检查
|
||
|
|
- 如果 tasks + specs 存在: 验证完整性和正确性,跳过 design
|
||
|
|
- 如果完整 artifacts 存在: 验证所有三个维度
|
||
|
|
- 始终注明跳过了哪些检查以及原因
|
||
|
|
|
||
|
|
**输出格式**
|
||
|
|
|
||
|
|
使用清晰的 markdown:
|
||
|
|
- 总结记分卡使用表格
|
||
|
|
- 问题分组列表 (CRITICAL/WARNING/SUGGESTION)
|
||
|
|
- 代码引用格式: `file.ts:123`
|
||
|
|
- 具体、可操作的建议
|
||
|
|
- 不要使用模糊的建议如 "考虑审查"
|