深度解析 ：implementation-verificator
本文详细分析 Skill
implementation-verificator的设计理念、工作流程和核心价值。
一、 定位与用途
implementation-verificator 的核心职责是：
将实际代码与已批准的计划/规格/设计文档进行对比，找出偏差、遗漏和风险。
需要强调的是------它不是功能设计工具，也不是纯粹的代码风格审查工具，而是专注于实现与计划的符合性验证。
二、目录结构
~/.codex/skills/implementation-verificator/
├── SKILL.md # 主入口：YAML 元数据 + 完整工作流指令
├── agents/
│ └── openai.yaml # Codex Agent 集成配置
└── references/
└── review-rubric.md # 详细评分标准和检查清单（按需加载）这完全符合 Codex 的 Skill 规范------SKILL.md 是必须的入口文件，references/ 是按需加载的补充材料，agents/openai.yaml 定义了在 Codex UI 中的显示信息。
三、SKILL.md 详解
3.1 YAML 元数据
yaml
name: implementation-verificator
description: Verify an implementation against an approved plan, spec, or design baseline.description 字段是 Skill 触发的核心信号------当用户任务描述匹配时，Codex 自动加载此 Skill。
3.2 基线确定原则
在评判代码之前，必须先确定验证基线：
- 活跃的
PLAN.md、spec、issue 或用户批准的计划 - 相关的
README.md、设计文档和AGENTS.md - 变更文件、涉及的模块和受影响的测试
- 运行时不变量或运维约束（当代码涉及框架、Agent、执行器、邮箱、任务、调度器或恢复逻辑时）
如果没有明确计划，则以最近的批准设计文档作为基线，并显式声明这一点。
3.3 六步验证工作流
步骤 1：锁定范围（Lock The Scope）
明确声明：
- 审查的仓库或包
- 实现范围：全量审查 / 变更文件审查 / 采样审查
- 使用的基线文档
- 实际运行的验证命令
代码库较大时，要刻意采样并说明采样策略。
步骤 2：检查计划与代码一致性（Check Plan And Code Consistency）
逐项对照计划与代码，检查：
- 计划项是否按意图实现
- 部分实现的计划项
- 缺失的计划项
- 计划外的额外范围
- 公共 API 偏移
- 消息流或状态流偏移
- 故障处理或重启/恢复偏移
- 承诺行为缺少测试
关键要求：用具体的覆盖矩阵替代"基本一致"这类模糊表述。
步骤 3：检查设计遗漏（Check Design Omissions）
不仅关注"实现错了什么"，更要关注"忘记定义什么"：
- 所有权边界
- 权威状态定义
- 超时和迟到结果语义
- 重试和重启规则
- 幂等性或单写入者边界
- 可观测性和诊断能力
- 面向运维的恢复规则
- 解析、语义和持久化之间的验证边界
步骤 4：检查性能与质量（Check Performance And Quality）
聚焦实际风险而非理论微优化：
- 可避免的轮询、重复 I/O 或重复序列化
- 粗粒度锁或锁误用
- 无界队列、重试、扫描或线程创建
- 竞态测试模式或不稳定的时序假设
- 会漂移的重复逻辑
- 隐藏根因的错误处理
- 清理缺口（泄漏的 watcher、executor、进程或临时文件）
步骤 5：验证（Validate What You Can）
尽可能实际运行构建和测试。无法验证的部分要精确声明未验证的内容及其对置信度的影响。
步骤 6：报告发现（Report Findings First）
每个发现包含：
- severity ：
high/medium/low - category ：
plan/design/performance/quality/tests - concrete evidence：文件和行号或命令结果
- why it matters：为什么重要
- issue type：计划偏移 / 设计规则遗漏 / 正确性 Bug / 扩展风险 / 验证缺口
四、review-rubric.md 详解
这个文件在需要深度审查时按需加载，包含六个评分维度。
4.1 计划覆盖矩阵
对每个主要计划项分类为：
| 分类 | 含义 |
|---|---|
implemented |
按计划完整实现 |
implemented_with_drift |
实现了但有偏移 |
partial |
部分实现 |
missing |
完全缺失 |
unverifiable |
无法验证 |
extra_unplanned_scope |
计划外的额外范围 |
硬性规则：仅有脚手架代码不算通过。
4.2 设计遗漏检查
API 与边界遗漏
- 公共方法及其语义
- 共享状态的所有权
- 状态转换模型
- 调用方与被调用方的职责划分
- 持久化权限
- 兼容性或迁移边界
故障处理遗漏
- 超时行为
- 取消行为
- 迟到结果处理
- 重试限制
- 重启限制
- 失败时的清理
- 降级模式 vs 硬失败行为
可观测性遗漏
运维人员能否回答：
- 什么失败了
- 哪里失败了
- 哪个 item/worker/stage/request 失败了
- 系统是否重试或降级了
- 重启后什么状态是权威的
4.3 多 Agent 运行时专项检查
这是该 Skill 最具特色的部分------针对 agent/mailbox/task/scheduler 等多 Agent 系统定义了硬性规则：
| 硬性规则 | 检查项 |
|---|---|
| 一个 mailbox 只有一个权威消费者 | worker 邮箱归 worker loop；控制面邮箱归 coordinator |
| 控制流与结果流显式分离 | 路由表或 channel 拆分在代码中可见 |
| 未知类型消息是可见的失败 | 未处理消息不会被静默标记已读 |
| 超时语义显式定义 | 取消、迟到结果、重试、worker 复用都有定义 |
| 锁只保护写操作 | 正确性不依赖锁的时序 |
| 恢复权限显式 | 未读邮箱、任务所有权有明确的真相来源 |
| 副作用有单写入者或 CAS 边界 | claim/update/mutation 路径强制所有权 |
4.4 严重度分级标准
| 级别 | 触发条件 |
|---|---|
| high | 行为违反已批准计划项可能破坏正确性；缺失不变量可能导致邮箱/任务/状态权限损坏；重启/超时/并发行为可能丢失或重复工作；测试明显缺失核心承诺行为 |
| medium | 行为不完整、脆弱或可能回归；性能或清理风险显著但尚未灾难性；设计边界仍然过于隐式不利于安全扩展 |
| low | 问题主要影响可维护性、诊断能力或打磨度；实现正确但不必要地脆弱或难以推理 |
五、openai.yaml 配置
yaml
interface:
display_name: "Implementation Verificator"
short_description: "Check plan drift, design gaps, and code risks."
default_prompt: "Use $implementation-verificator to compare the plan with the code, find design omissions, and review performance and quality risks."用户通过 $implementation-verificator 显式触发，或当任务描述匹配 Skill 的 description 字段时自动触发。
六、设计哲学总结
implementation-verificator 体现了以下核心原则：
- 不信任计划，不信任代码------两者必须交叉验证
- 发现优先于总结------先报告具体问题，再给概括性结论
- 区分四种状态 ：
incorrect（错误）、incomplete（不完整）、unplanned（计划外）、unverified（未验证） - 渐进式加载 ------
SKILL.md包含核心工作流，references/review-rubric.md仅在深度审查时按需读取，节省上下文窗口 - 特别关注多 Agent 运行时------mailbox 所有权、控制/结果流分离、恢复不变量等，这是通用代码审查工具很少覆盖的领域
- 报告格式标准化------统一的发现格式（severity/category/evidence/impact）确保输出可被下游工具解析
七、适用场景
- Sprint 结束时的实现验证
- 代码审查前的自动化预检
- 大型重构后的符合性检查
- 多 Agent 系统的设计规则审计
- CI/CD 流水线中的质量门禁
八、总结
implementation-verificator 是一个设计精良的 Codex Skill，它将传统代码审查中的"计划符合性验证"环节系统化、结构化。其最大价值在于：不仅检查"代码写对了没有"，更检查"代码忘记定义了什么"------后者往往是生产环境中最大的风险来源。
对于使用 Codex CLI 进行日常开发的团队，这个 Skill 可以显著提升实现质量的可追溯性和可审计性。