适合谁读：已经会让 Codex 修改代码，但经常遇到“改动看起来完成了，运行后才发现漏测、误改或没有解决根因”的开发者。核心结论是：高质量协作的关键不是把实现步骤写得越来越细，而是提前定义可验证的成功标准，并要求 Codex 用测试、Diff 和运行证据闭环。
本文更新：2026 年 7 月 22 日。本文依据当日可访问的 OpenAI 官方资料整理，不涉及套餐、模型价格或未经证实的产品能力。
为什么“请修复这个 Bug”还不够
“修复登录失败”“优化查询速度”“更新依赖”都描述了方向，却没有说明怎样才算完成。Codex 可能修掉表面报错，但没有覆盖边界条件；也可能顺手重构无关代码，让评审范围突然扩大。真正有效的任务描述，应把目标变成一组可以观察的结果。
OpenAI 的模型提示指南强调：对多步骤任务，应给出领域背景、硬约束、审批边界和成功标准；对于修改、构建或修复类请求，可授权执行范围内的本地改动和非破坏性验证，同时把外部写入、破坏性操作和明显扩项留给确认。Codex 官方用例也把“修改、测试、评审并准备交付”放在同一个工作闭环里。换句话说，生成代码只是中间步骤，证明确实解决问题才是交付。
先写一份四段式验收契约
一个实用提示不必很长，可以固定为四段：目标、范围、约束、验收。
目标：修复订单详情页在空数据时崩溃的问题。
范围：只修改订单详情组件及其直接测试，不调整公共接口。
约束：保留现有未提交改动；新增依赖前先确认；不要执行部署。
验收：
1. 空订单、正常订单两种场景都能渲染；
2. 运行该组件的单元测试；
3. 检查最终 Diff，没有无关格式化；
4. 报告改动文件、测试命令、结果和未验证项。这四段分别回答“做什么”“动哪里”“不能越过什么边界”“用什么证据证明完成”。实现方式仍可以交给 Codex判断；如果把每一行代码都预先指定，反而可能限制它发现更小、更符合现有结构的修复方案。
第一步：把现象改写成可观察结果
成功标准应尽量可运行、可比较。不要只写“性能更好”，改成“在现有基准脚本下记录修改前后耗时，查询次数不能增加”；不要只写“兼容旧数据”，改成“为缺少新字段的历史样本增加回归测试”。如果暂时没有自动化测试，也可以要求复现命令、返回码、关键日志或构建产物存在。
同时区分必须通过与最好通过。核心回归测试失败就不能算完成；全仓库耗时数小时的集成测试如果当前环境无法执行，则应明确列为未验证项，而不是让 Codex 用“应该没问题”替代证据。
第二步：验证根因，不只验证补丁
让 Codex 在修改前先复现问题或定位数据流，尤其适用于偶发错误、跨模块调用和配置问题。一个稳妥顺序是：读取相关代码与现有测试，形成根因假设；用最小复现验证假设；再做最小改动。
这里的“最小”不是代码行数越少越好，而是只改变解决目标所需的行为。例如错误来自服务端缺少校验，只在前端隐藏按钮并没有消除根因。验收中可以加入一句：“说明根因证据，以及为什么改动位于正确层级。”这会迫使最终报告把观察与推断分开。
第三步：建立由近到远的测试梯度
验证应先跑最快、最相关的检查，再逐步扩大范围：语法或类型检查、直接单元测试、模块测试、构建或集成测试。前一层失败时先修复，不要一上来运行整个仓库最重的命令，也不要因为全量测试太慢就完全不测。
可以这样要求：“优先运行受影响模块的测试；通过后再运行项目规定的静态检查。若环境、权限或依赖阻塞，保留错误原文并说明没有验证什么。”这样的停止条件既节省时间，也避免重复重试或偷偷改变环境。
第四步：用 Diff 做最后一道质量门
测试通过不代表改动范围合理。交付前还应查看版本控制状态和最终 Diff，重点检查四类问题：无关文件是否被修改、是否出现大面积格式化、调试代码或临时日志是否残留、配置与示例中是否混入令牌或真实地址。
如果仓库本来就有未提交改动，还要区分哪些是任务前已存在、哪些由本次产生。不要为了获得“干净状态”而覆盖或删除用户工作。安全的要求是：“保留已有修改；如果发生重叠，先报告冲突。”
一份可复用的最终交付格式
让最终答复保持证据化，可以要求 Codex按下面四项交付：
- 结果：问题是否解决，核心行为发生了什么变化；
- 改动：列出关键文件和设计理由，不逐行复述代码；
- 验证：给出实际运行的命令及通过、失败或跳过状态；
- 剩余风险：说明未验证环境、人工步骤和需要确认的外部操作。
这份格式还能暴露“假完成”：如果验证栏只有“已修改代码”，没有任何可重复证据，就应继续补测；如果剩余风险写着“尚未确认接口兼容”，就不应直接合并。
三个常见误区
第一，把“运行所有测试”当成万能要求。超大仓库可能因此浪费时间，还掩盖真正相关的回归测试。更好的做法是指定测试梯度和扩大范围的条件。
第二，只要求 Codex 自检一句“确认无误”。自我声明不是证据；命令、退出状态、测试数量、Diff 和页面/API 回读才是证据。
第三，在验收阶段临时扩大权限。测试失败不代表可以自动安装系统软件、修改全局配置或部署生产环境。若验证需要外部写入、付费资源、破坏性命令或新的权限，应停下来说明缺口并请求确认。
最后建议
下一次交给 Codex 的任务，不妨少写几句实现猜测，多写四条可观察的验收条件。最值得固定下来的不是“必须用哪种写法”，而是哪些行为必须保持、哪些测试必须通过、哪些边界不能越过、最终要提交哪些证据。当成功标准清楚后，Codex 才能自主选择实现路径，同时让你用更低的评审成本判断它是否真的完成了工作。