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 页 → 观察接口请求参数和页面渲染数据。
- 期望：页码切换后，接口携带
page=2，列表渲染第 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 太大就让它收缩范围。
第三步，运行验证。跑指定的测试命令，或者手动复现步骤。通过条件要具体到可观察的结果，比如“接口请求携带 page=2 且列表渲染第 2 页数据”，而不是“测试通过”。
4.3 把验收写进任务描述
验收标准要写成可执行的判断，比如：
【验收】 1. npm run test -- order.list 全部通过 2. 手动复现：点击第 2 页，Network 中 /api/order/list 请求参数包含 page=2 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc，API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan。想先验证模型对话效果，可以从模型对话入口试起：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=chat。
最后留一个我自己的习惯：每次让 Codex 改代码前，先把任务描述读一遍，问自己三个问题——它知道改哪个文件吗？它知道怎么判断改对了吗？它知道哪些不能碰吗？三个都能答上来，再让它动手。答不上来，就继续补描述。这个习惯比换模型管用。
