变更实现验证技能：归档前先自检，确认代码真的把规格落地了
- 一句话定位：在变更归档之前，自动核查「代码实现」是否真的匹配「规格、任务、设计」这三份变更工件，避免文档写得很漂亮、代码却没跟上。
- 三个验证维度：完整性（任务是否勾完、需求是否都有实现）、正确性（需求与场景是否被真正覆盖）、一致性（是否遵循设计决策与项目代码模式）。
- 问题分级清晰：所有发现按 CRITICAL / WARNING / SUGGESTION 三级输出，每条都附带具体、可操作的修复建议，而不是含糊的"建议再检查一下"。
- 依赖明确：需要配合 openspec CLI 使用，通过
openspec list、openspec status、openspec instructions apply三条命令完成上下文加载。 - 优雅降级：项目里只有 tasks.md 就只查任务，有任务加规格就查两个维度，工件齐全才做三维全量验证，并会注明跳过了哪些检查以及原因。
1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 中文名 | 变更实现验证技能Skill |
| 英文名 | openspec-verify-change |
| 技能 ID | 8165 |
| 许可证 | MIT |
| 兼容性 | 需要 openspec CLI |
| 作者 / 版本 | openspec / 1.0 |
它解决什么问题
在规格驱动（spec-driven）的开发方式中，一次变更通常会被拆成三份工件：tasks.md（任务清单）、specs/（增量规格，里面有 ### Requirement: 和 #### Scenario:）、design.md（设计决策）。问题在于——任务打了勾，不等于需求真实现了；需求写了，不等于场景被覆盖；设计定了，不等于代码照着做了。
人工检查这三件事既费时又容易漏，而传统的 CI 只能告诉你"测试有没有过"，说不出"规格里的第 7 条需求在代码里到底有没有落地"。这个技能就是把这段"归档前的最后一道人工核查"变成一次结构化的对话式检查。
一键安装的思路与步骤
- 准备安装前提：技能在元数据里明确标注「需要 openspec CLI」，因此第一步是先在本地环境中装好并可用 openspec CLI，同时确认目标项目已经按 openspec 的组织方式存在变更目录（如
openspec/changes/<名称>/）。CLI 的具体安装方式以官方说明为准。 - 获取并安装技能：在 AI 助手的技能市场或技能仓库中，按技能 ID
8165或英文名openspec-verify-change检索并安装；如果你的环境支持命令行安装，具体命令请以官方说明为准。安装的本质是把技能说明文件放进 AI 助手能够读取的技能目录，让模型在合适时机被唤起。 - 验证是否生效：在对话里直接说一句「帮我验证一下 xxx 变更的实现是否完整」。如果技能已生效，它会先执行
openspec list --json拉取可用变更，并用提问工具让你挑选目标变更，而不是自己瞎猜一个。这一步出现，就说明装好了。 - 补充验证：再试一次不带变更名的说法，正常情况下它应当提示你从列表中选择，而不是自动选择——这也是判断技能是否被正确加载的好方法。
说明：技能详情中未提供具体的下载地址、安装命令与费用信息，请以官方说明为准；本文不虚构任何链接与价格。
2. 该技能的主要功能和特点
- 三维度结构化验证：把"实现是否靠谱"拆成完整性（任务清单完成率、需求覆盖率）、正确性（每条需求的实现证据与场景覆盖）、一致性（设计决策遵循、代码模式统一）三个可核查的维度，避免"感觉差不多就归档"。
- 客观解析任务复选框：读取
tasks.md，区分- [ ]（未完成）与- [x]（完成），统计完成数与总数；每一个未完成任务都会被列为 CRITICAL 问题，并给出"完成该任务"或"若已实现请标记完成"的建议。 - 需求级实现映射：从增量规格中提取所有
### Requirement:条目，逐条在代码库中搜索相关关键词，评估实现是否可能存在；找不到证据就直接报"未找到需求：<需求名称>"。 - 场景覆盖检查：对每个
#### Scenario:检查代码是否处理了对应条件、是否存在覆盖该场景的测试，缺失则给出"为场景添加测试或实现"的具体建议。 - 设计遵循校验：读取
design.md中的 Decision / Approach / Architecture 等关键决策，与实际实现对照，检测矛盾；若没有 design.md，则明确注明"没有 design.md 可验证"，而不是默默跳过。 - 代码模式一致性审查：检查新代码的文件命名、目录结构、编码风格是否与项目既有约定一致，偏离时以 SUGGESTION 级别提示。
- 分级问题清单 + 可定位引用：所有问题按 CRITICAL（归档前必须修）、WARNING（应该修）、SUGGESTION（最好修）分组，并采用
file.ts:123这类文件与行号引用，方便直接跳转修改。 - 防误报的启发式：不确定时优先降级——能报 SUGGESTION 就不报 WARNING，能报 WARNING 就不报 CRITICAL；只找明显不一致，不吹毛求疵地挑风格问题。
- 绝不猜测变更：如果用户没指定变更名，它必须列出可用变更让用户选择，并标注哪些是"（进行中）"，还会尽可能显示每个变更使用的架构。
和普通工具比强在哪：一般的测试与 CI 只能验证"代码能跑"，代码评审工具只能看"这行改动好不好"。这个技能是少数把规格文档当作验收基准来反向核查代码的工具，输出的不是"代码质量评分"，而是"这次变更能不能归档"的可执行结论。
3. 如何使用该技能？
第一步：唤起技能并确定目标变更
直接描述意图即可，例如：
“我准备归档 add-user-auth 这个变更，先帮我验证实现是否匹配规格。”
如果你没说变更名，技能会执行 openspec list --json，然后通过提问工具让你选择。列表中会显示所有存在任务工件的变更，并尽量标注所用架构与"（进行中）"状态。注意：它不会替你自动挑一个，这是刻意的设计。
第二步：了解该变更的架构与工件构成
技能内部执行：
openspec status --change "<名称>" --json
解析返回的 JSON，重点看 schemaName（例如 spec-driven、tdd）以及该变更实际存在哪些工件——这决定了后面能查哪几个维度。
第三步：加载变更目录与上下文文件
openspec instructions apply --change "<名称>" --json
返回变更目录和上下文文件清单，随后从头到尾读取 contextFiles 中所有可用工件，作为后续比对的"事实基准"。
第四步：初始化报告骨架
报告一开始就确立三个维度的跟踪框架（完整性、正确性、一致性），每个维度下面预留 CRITICAL / WARNING / SUGGESTION 三档问题位。
第五步：逐维度执行验证
- 完整性：解析 tasks.md 复选框；提取增量规格中的全部需求，逐条搜索实现证据。
- 正确性：对每条需求记录实现所在文件与行范围，判断是否偏离规格意图；对每个场景检查条件处理与测试覆盖。
- 一致性：对照 design.md 的关键决策；再看新代码的命名、目录与风格是否符合项目惯例。
第六步：输出验证报告
报告形如：
## 验证报告：<变更名称>
### 总结
| 维度 | 状态 |
|------------|----------------|
| 完整性 | X/Y 任务, N 需求 |
| 正确性 | M/N 需求覆盖 |
| 一致性 | 遵循/问题 |
随后按优先级列出问题，每条都带推荐动作，例如：
- CRITICAL：
未找到需求：登录失败次数限制→ 推荐「实现需求 X：<描述>」 - WARNING：
实现可能偏离规格：<详细信息>→ 推荐「针对需求 X 审查 auth/login.ts:88」 - SUGGESTION：
代码模式偏离：<详细信息>→ 推荐「考虑遵循项目模式：<示例>」
最后给出总评：有 CRITICAL 就是"找到 X 个关键问题，归档前修复"；只有警告是"无关键问题，可归档（附注改进）“；全部通过则是"所有检查通过，可归档”。
输入输出小结：输入是"变更名称（可选）+ 代码库"，输出是"一份带计分卡、分级问题清单与具体修复建议的 Markdown 报告"。报告的写法固定收敛为表格 + 分组列表 + 文件行号引用，不会出现"建议再审查一下"这类空话。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| openspec-verify-change（本技能） | 归档前的"规格—实现"对账器 | 三维度验证、任务复选框解析、需求与场景覆盖、设计遵循检查、分级问题清单 | 需 openspec CLI；需项目采用 openspec 变更工件结构 | 规格驱动开发、TDD 变更收尾、交付前自检 | 优势：以规格为验收基准，输出可执行结论，定位到文件行；不足：强依赖 CLI 与工件规范，未采用该体系的项目无法直接使用 |
| 人工代码评审（Code Review） | 由人判断改动质量 | 阅读 diff、讨论设计取舍 | 无需安装，但需要评审者投入时间 | 所有项目、所有变更 | 优势：能捕捉语义与业务层面的问题；不足：耗时、标准不统一、容易漏掉"没被写进代码的需求" |
| CI 流水线 + 测试覆盖率工具 | 自动化质量门禁 | 跑单测、统计行/分支覆盖率、静态检查 | 需要配置流水线与测试框架 | 持续集成、回归防护 | 优势：稳定、可重复、无人值守；不足：只回答"测试过没过"，无法回答"规格里的需求有没有被实现" |
| 通用 AI 代码审查助手 | 针对 diff 给建议 | 逐行点评风格与潜在缺陷 | 门槛低，接入 IDE 即可 | 日常编码、快速改进 | 优势：上手快、即写即评；不足：缺乏项目内部的规格与设计上下文，容易给出泛化建议，也无法给出"能否归档"的判断 |
怎么选：如果你的项目已经在用 openspec 组织变更工件，本技能几乎是"归档按钮"前的自然一环；如果没有，先用人工评审 + CI 兜底，再考虑把变更工件体系搭建起来。
5. 该技能的典型应用场景与实际体验情况
场景一：独立开发者的归档前自检
独立开发者常常是"自己写规格、自己写代码、自己勾任务"，缺少第二双眼睛。归档前跑一次验证，能把自己漏掉的需求、忘勾的复选框、只写了一半的场景一次性摊开。实际体验是：报告的计分卡最有用，X/Y 任务 和 M/N 需求覆盖 两个数字能在十秒内告诉你"这次变更到底做完没有"。
场景二：技术负责人做变更验收
团队里每人负责一块变更，负责人不可能逐行读完全部代码。用这个技能先跑一遍，只处理输出的 CRITICAL 清单，就能把验收时间压到很小。需要注意的是：技能用的是关键词搜索与合理推断来判定"实现可能存在"，属于启发式判断而非形式化证明，因此作为验收线索非常高效，但最终仍需人来确认。
场景三：TDD 工作流下的场景覆盖率核查
当 schemaName 显示为 tdd 时，场景覆盖检查尤其有价值——它会逐个 #### Scenario: 检查代码是否处理了条件、是否有对应测试。实践中最常见的问题是"实现写了，测试没跟上"，报告会明确提示"为场景添加测试或实现"。
场景四：交接与审计
变更需要交接给他人或进入归档留痕时，design.md 里写下的决策是否被真正执行，是一个很难回溯的问题。技能的"设计遵循"检查会提取 Decision / Approach / Architecture 段落逐一比对，发现矛盾时给出"更新实现或修订 design.md 以匹配现实"的二选一建议——这一点很实用，因为很多矛盾其实是设计文档过期了。
实际体验情况
- 上手难度：低。 不需要记命令，用自然语言说"验证 xxx 变更"即可，命令由技能在内部调用。
- 效果： 对完整性（复选框、需求列表）这类客观项判定准确；正确性与一致性属于启发式推断，更适合当作"重点复查清单"而不是"判决书"。
- 注意事项一： 必须让它列变更让你选，不要图省事直接说"随便挑一个"——技能本身设计上是拒绝自动选择的，这能避免验证错对象。
- 注意事项二： 项目没有设计文档时，一致性维度会退化；技能会主动注明跳过了哪些检查，看到这类说明不要以为是 bug。
- 注意事项三： 需求命名如果过于抽象，关键词搜索的命中率会下降，建议规格中的需求标题尽量包含可检索的业务词。
6. 该技能能为用户带来的价值
- 把"归档"从主观判断变成有据可依的动作：以前是"感觉做完了"，现在是一张计分卡加一份分级问题清单，归档决策有了明确的通过条件。
- 节省核查时间：跨文件对比规格、任务与代码，原本是半天到一天的人工活，现在几轮对话就能得到结构化结论，人只需要处理输出的 CRITICAL 清单。
- 降低遗漏风险：未完成任务、未实现需求、未覆盖场景这三类"静默失败"是最容易在交付后暴露的问题，技能把它们提前到归档前拦截。
- 让规格文档真正生效：当规格能被自动对账，团队写规格的动力会明显提升，文档不再是"写完就没人看"的摆设。
- 可操作的修复路径：每条问题都带
file.ts:123级别的定位与具体建议，避免了"发现问题但不知道从哪改"的空转成本。 - 长期价值：随着变更不断累积，一致性与代码模式检查会逐步牵引团队形成统一的工程约定，减少后续维护的理解成本。
7. 常见问题 FAQ
Q1：这个技能怎么安装？必须先装 openspec CLI 吗？
是的。技能元数据中明确标注「需要 openspec CLI」，因此 CLI 是前置条件；具体安装方式以官方说明为准。装好 CLI 后，在技能市场按技能 ID 8165 或英文名 openspec-verify-change 检索安装即可。安装完成后，说一句"验证 xxx 变更"，若它能列出变更让你选择，就说明生效了。
Q2：这个技能收费吗？
不收费。技能元数据中标注的许可证为 MIT，作者为 openspec，版本 1.0。至于你使用的 AI 助手平台本身是否收费，取决于该平台的策略，以官方说明为准。
Q3：适合谁用？我不用 openspec 体系能用吗？
最适合已经采用规格驱动开发、用 openspec 组织变更工件的开发者与团队，尤其是独立开发者、技术负责人和需要做变更验收的人。如果你的项目里没有 openspec/changes/<名称>/ 这类结构、没有 tasks.md 与增量规格，技能就缺少比对基准，效果会很有限。
Q4：为什么它总是让我选变更，不能自动判断吗？
这是刻意的设计。技能明确要求「不要猜测或自动选择变更，始终让用户选择」，因为验证错对象比不验证更浪费时间。它只会列出存在任务工件的变更并标注"（进行中）"，把选择权交给你。
Q5：它判定"需求未实现"一定准确吗？
不一定，需要区分问题级别来看。完整性维度基于复选框和需求列表，属于客观检查，可信度高；正确性与一致性依赖关键词搜索、文件路径分析与合理推断，技能本身也说明这"不需要完美确定性"。同时它内置了防误报启发式：不确定时优先报 SUGGESTION 而非 WARNING。因此建议把 CRITICAL 当必须处理项，把 WARNING 与 SUGGESTION 当复查线索。
Q6：项目里没有 design.md 会怎样？
会优雅降级。技能会跳过设计遵循检查，并明确注明"没有 design.md 可验证"。同理，只有 tasks.md 时仅验证任务完成情况；任务与规格都有时验证完整性与正确性。每次跳过都会注明跳过了哪些检查及原因，不会静默略过。