# Openspec Verify Change

> 验证实现是否与变更 artifact 一致。当用户想在归档前验证实现是否完整、正确且连贯时使用。

- Skill: `txyzznc/openspec-verify-change` (Agent Skill)
- Install (CLI): `npx skillmds@latest add txyzznc/openspec-verify-change`
- Raw SKILL.md: https://api.skillmd.com/api/skills/txyzznc/openspec-verify-change/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: txyzznc (https://skillmd.com/u/txyzznc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/txyzznc/openspec-verify-change

---


验证实现是否与变更 artifact（specs、tasks、design）一致。

**输入**：可选指定变更名称。若未提供，尝试从对话上下文中推断。若含糊不清，**必须**提示用户选择可用的变更。

**步骤**

1. **若未提供变更名称，提示用户选择**

   运行 `openspec list --json` 获取可用变更。使用 **AskUserQuestion 工具**让用户选择。

   只显示有实现任务的变更（tasks artifact 存在）。
   若可用，显示每个变更所用的 schema。
   将有未完成任务的变更标记为"（进行中）"。

   **重要**：不要猜测或自动选择变更，始终让用户做选择。

2. **检查状态以了解 schema**
   ```bash
   openspec status --change "<name>" --json
   ```
   解析 JSON 以了解：
   - `schemaName`：正在使用的工作流（例如 "spec-driven"）
   - 此变更存在哪些 artifact

3. **获取变更目录并加载 artifact**

   ```bash
   openspec instructions apply --change "<name>" --json
   ```

   返回变更目录和上下文文件。从 `contextFiles` 读取所有可用的 artifact。

4. **初始化验证报告结构**

   创建包含三个维度的报告结构：
   - **完整性（Completeness）**：跟踪任务和 spec 覆盖情况
   - **正确性（Correctness）**：跟踪需求实现和场景覆盖情况
   - **连贯性（Coherence）**：跟踪设计遵从情况和模式一致性

   每个维度可包含 CRITICAL（严重）、WARNING（警告）或 SUGGESTION（建议）类型的问题。

5. **验证完整性**

   **任务完成情况**：
   - 若 contextFiles 中存在 tasks.md，读取它
   - 解析复选框：`- [ ]`（未完成）与 `- [x]`（已完成）
   - 统计已完成与总任务数
   - 若存在未完成任务：
     - 对每个未完成任务添加 CRITICAL 问题
     - 建议："完成任务：<描述>"或"若已实现则标记为完成"

   **Spec 覆盖情况**：
   - 若 `openspec/changes/<name>/specs/` 中存在增量 spec：
     - 提取所有需求（标有 "### Requirement:" 的行）
     - 对每个需求：
       - 在代码库中搜索与需求相关的关键词
       - 评估实现是否可能存在
     - 若需求似乎未实现：
       - 添加 CRITICAL 问题："未找到需求：<需求名称>"
       - 建议："实现需求 X：<描述>"

6. **验证正确性**

   **需求实现映射**：
   - 对增量 spec 中的每个需求：
     - 在代码库中搜索实现证据
     - 若找到，记录文件路径和行范围
     - 评估实现是否符合需求意图
     - 若发现偏差：
       - 添加 WARNING："实现可能偏离 spec：<详情>"
       - 建议："对照需求 X 检查 <file>:<lines>"

   **场景覆盖情况**：
   - 对增量 spec 中的每个场景（标有 "#### 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/设计偏差
      - 缺少场景覆盖
      - 每项附有具体建议

   3. **SUGGESTION 建议**（可选修复）：
      - 模式不一致
      - 小改进
      - 每项附有具体建议

   **最终评估**：
   - 若有 CRITICAL 问题："发现 X 个严重问题。归档前请修复。"
   - 若只有警告："无严重问题。有 Y 个警告供参考。可以归档（注意已提及的改进点）。"
   - 若全部通过："所有检查通过。可以归档了。"

**验证启发式方法**

- **完整性**：聚焦于客观的清单项（复选框、需求列表）
- **正确性**：使用关键词搜索、文件路径分析、合理推断——不需要完全确定
- **连贯性**：查找明显的不一致，不要吹毛求疵
- **误报处理**：不确定时，倾向于 SUGGESTION 而非 WARNING，WARNING 而非 CRITICAL
- **可操作性**：每个问题必须附有具体建议，尽可能带文件/行号引用

**降级处理**

- 若只存在 tasks.md：仅验证任务完成情况，跳过 spec/design 检查
- 若存在 tasks + specs：验证完整性和正确性，跳过设计
- 若存在完整 artifact：验证所有三个维度
- 始终注明跳过了哪些检查及原因

**输出格式**

使用清晰的 Markdown，包括：
- 摘要评分卡表格
- 按问题类型分组的列表（CRITICAL/WARNING/SUGGESTION）
- 代码引用格式：`file.ts:123`
- 具体、可操作的建议
- 不使用"考虑审查"之类的模糊建议