Codex修Bug总翻车？先检查你的任务描述里有没有这3个坑

1. 为什么你的 Codex 总在同一个 Bug 上翻车如果你用 Codex 修过 Bug大概率经历过这种循环描述一句“登录报错了帮我修一下”它改了三四个文件跑完测试说“已修复”你一看 Diff登录逻辑没动反而把请求封装重构了一遍。再让它重试它又换了个方向猜旧问题没解决新问题冒出来。这时候很容易得出一个结论模型太弱。但实测下来多数翻车现场的问题不在模型而在任务描述本身。Codex 这类编码 Agent 的工作方式是读你给的上下文 → 推断意图 → 规划改动 → 执行 → 自检。如果第一步的输入就是模糊的后面每一步都会放大偏差。这篇聚焦三个最典型的任务描述坑任务粒度太粗、上下文缺失、验收标准模糊。每个坑我都会给出反例、正例以及可以直接复制的config.toml骨架和任务模板。目标不是让你换模型而是让你在同一个模型上把修复成功率拉起来。适合谁看已经在用 Codex 或类似编码 Agent 修 Bug但结果不稳定、需要反复回滚的开发者。读完你能拿到一套可复制的任务描述结构以及三步验证动作用来判断到底是任务写错了还是模型确实没能力。2. 坑一任务粒度太粗一个任务塞了三件事2.1 反例长什么样最常见的写法是“帮我修一下订单模块的问题顺便优化下代码。”这句话里其实藏了至少三个任务修订单分页 Bug、优化代码结构、可能还有清理警告。Codex 会自己决定先做哪个、做多少结果往往是它挑了一个它认为“最合理”的方向改了一大片但你要的那个 Bug 没动。粒度粗的另一个表现是把“分析原因”和“修改代码”混在一句话里。比如“看看为什么接口 500然后修好它”。Codex 可能跳过分析直接改改错了你也不知道它当初判断的根因是什么。2.2 拆成可执行的最小单元一个可执行的修复任务应该只包含一个可验证的目标。我习惯把它拆成三段现象描述、复现路径、期望结果。比如现象订单列表点击第 2 页后页码变成 2但列表数据仍是第 1 页的内容。复现进入订单列表 → 点击分页第 2 页 → 观察接口请求参数和页面渲染数据。期望页码切换后接口携带page2列表渲染第 2 页数据。这三段写完Codex 至少知道去哪找、怎么判断对错。至于“优化代码”单独开一个任务不要和修 Bug 混在一起。2.3 config.toml 骨架示例如果你用 Codex CLI 或类似工具可以在项目根目录放一个config.toml把任务边界写进配置减少每次对话重复描述。下面是一个骨架字段按你的工具实际支持调整# config.toml - Codex 任务边界配置骨架 [task] name fix-order-pagination description 修复订单列表分页数据不刷新问题 scope [src/pages/order/list.tsx, src/api/order.ts] forbidden [src/router, package.json, src/utils/request.ts] [context] error_log logs/order-pagination-error.log recent_changes [src/api/order.ts] [verify] command npm run test -- order.list expected 分页请求携带 page 参数列表数据随页码变化scope限定允许改动的文件forbidden明确不能碰的目录。这两个字段是防止 Codex 顺手重构的关键。verify里的命令和期望结果就是后面第三步验证动作的依据。3. 坑二上下文缺失让 Codex 靠猜3.1 只给一句“报错了”等于没给“项目启动报错了”“接口挂了”“页面白屏”——这类描述对 Codex 来说信息量几乎为零。它不知道报错在哪个文件、哪一行、什么错误类型只能从项目里全局搜索猜一个最可能的位置。猜对了是运气猜错了就是一轮无效改动。上下文缺失的典型场景控制台明明打印了orderId is undefined报错位置在src/pages/order/detail.tsx第 86 行但任务描述里只写“详情页有问题”。Codex 可能去改路由、改状态管理就是不看你已经拿到的报错行。3.2 最少要给的上下文清单我整理了一个最小上下文清单每次修 Bug 至少给到前三项上下文类型具体内容是否必须报错信息控制台/终端完整错误行、状态码必须报错位置文件路径 行号 函数名必须复现步骤从哪个入口、点什么、看到什么必须最近改动最近改过的文件或提交建议接口返回请求参数和响应体接口类 Bug 必须能否稳定复现必现 / 偶现 / 特定环境建议报错很长不用全贴但关键错误行、文件路径、函数名、状态码一定要保留。比如这样写“接口返回 500控制台提示orderId is undefined位置在src/pages/order/detail.tsx第 86 行最近改过src/api/order.ts。”这比“报错了”有效得多。3.3 把上下文写进任务模板下面是一个可复制的任务描述模板直接填空即可【任务】修复订单详情页接口 500 问题 【现象】进入订单详情页接口 /api/order/detail 返回 500页面显示空白 【报错】控制台orderId is undefined位置 src/pages/order/detail.tsx:86 【复现】订单列表 → 点击任意订单 → 观察 Network 和 Console 【期望】接口返回 200页面渲染订单详情 【允许修改】src/pages/order/detail.tsx, src/api/order.ts 【禁止修改】src/router, package.json, src/utils/request.ts 【验证】npm run test -- order.detail且手动复现步骤通过 【要求】先分析根因列出检查的文件和判断依据不要直接改代码最后一句“先分析根因”很重要。复杂 Bug 不要让它一步到位直接改先让它输出分析你确认方向对了再让它动手。方向不对就停别继续。4. 坑三验收标准模糊改完不知道对不对4.1 “修好了”不是验收标准很多人给 Codex 的验收标准就是“修好它”。但“好”的定义是什么接口返回 200页面不报错测试通过还是用户能正常下单没有明确标准Codex 会自己定义一个它认为合理的完成条件然后告诉你“已修复”。你一看它把报错 catch 掉了页面不报错了但数据还是错的。验收标准模糊的另一个后果是失败后无限重试。因为没有一个明确的“通过/不通过”判断Codex 每次重试都在换方向猜越改越乱。4.2 三步验证动作我习惯用三步验证每一步都有明确的通过条件第一步静态检查。让它先输出它检查了哪些文件、认为根因是什么、准备改哪里。如果根因判断和你的预期不符直接停不要进入修改。第二步改动审查。改完后先看 Diff不看总结。重点检查有没有改无关文件、有没有删除旧逻辑、有没有新增依赖、有没有大范围格式化。Diff 太大就让它收缩范围。第三步运行验证。跑指定的测试命令或者手动复现步骤。通过条件要具体到可观察的结果比如“接口请求携带 page2 且列表渲染第 2 页数据”而不是“测试通过”。4.3 把验收写进任务描述验收标准要写成可执行的判断比如【验收】 1. npm run test -- order.list 全部通过 2. 手动复现点击第 2 页Network 中 /api/order/list 请求参数包含 page2 3. 页面列表渲染的数据与第 2 页接口返回一致 4. git diff 中不包含 src/router、package.json 的改动这四条写清楚Codex 改完自己就能对照检查你验收也有依据。如果它说“已修复”但第 2 条不满足那就是没修好不用看它的总结。5. 完整可复制模板与排障清单5.1 一份能直接用的任务描述模板把前面三部分拼起来就是一份完整的任务描述模板。每次修 Bug 复制一份填空即可【任务】一句话描述修复目标 【现象】用户看到什么、接口返回什么、控制台报什么 【报错】错误行 文件路径 行号 函数名 【复现】从入口到现象的步骤 【期望】修复后可观察的正确结果 【允许修改】文件或目录列表 【禁止修改】文件或目录列表 【验证】测试命令 手动复现通过条件 【要求】先分析根因列出检查文件和判断依据确认后再修改这份模板的核心是把“任务粒度、上下文、验收标准”三个坑一次性填掉。你不需要每次写得很长但每一项都要有具体内容不能留空。5.2 常见错排查清单如果你已经按模板写了Codex 还是翻车按这个清单逐项排查任务里是不是混了多个目标拆开一次只修一个。报错信息是不是只给了“报错了”补上错误行、文件、行号。允许修改范围是不是太大缩到最小必要文件集。有没有要求先分析再改复杂 Bug 必须加这一句。验收标准是不是“修好了”改成可执行的判断条件。失败后是不是一直在重试连续两次没修好就停让它回答检查了哪些文件、根因是什么、上次为什么失败。改完有没有看 Diff只看总结等于没验收。5.3 接入配置与验证请求如果你还没配好 Codex 的接入环境或者想换一个稳定的 API 入口来跑这些任务可以先把 Key 和接入文档准备好。TaoToken 的 API 地址是https://taotoken.net/api接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdocAPI Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys。配好之后可以用一个最小请求验证接入是否正常curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: 回复 ok}] }返回里能看到choices[0].message.content就说明接入通了。这一步通了再跑 Codex 任务就能排除是接入问题还是任务描述问题。6. 把任务写对比换模型更有效Codex 修 Bug 翻车多数时候不是模型弱而是任务描述里踩了粒度、上下文、验收这三个坑。粒度太粗它不知道先做哪个上下文缺失它只能猜验收模糊它自己定义“修好了”。把这三项补上同一个模型的表现会稳定很多。如果你长期用 Codex 做编码和 Agent 任务可以考虑 Coding Plan把常用的任务模板和配置固化下来减少每次重复描述的成本https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan。想先验证模型对话效果可以从模型对话入口试起https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat。最后留一个我自己的习惯每次让 Codex 改代码前先把任务描述读一遍问自己三个问题——它知道改哪个文件吗它知道怎么判断改对了吗它知道哪些不能碰吗三个都能答上来再让它动手。答不上来就继续补描述。这个习惯比换模型管用。