深度解析 implementation-verificator本文详细分析 Skillimplementation-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 元数据name:implementation-verificatordescription: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每个发现包含severityhigh/medium/lowcategoryplan/design/performance/quality/testsconcrete 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 配置interface:display_name:Implementation Verificatorshort_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 可以显著提升实现质量的可追溯性和可审计性。
深度解析 implementation-verificator本文详细分析 Skillimplementation-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 元数据name:implementation-verificatordescription: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每个发现包含severityhigh/medium/lowcategoryplan/design/performance/quality/testsconcrete 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 配置interface:display_name:Implementation Verificatorshort_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 可以显著提升实现质量的可追溯性和可审计性。
