# 36 · 最佳实践：那些「正确的废话」之外，真正能落地的几条

> 📚 **系列导航**：上一篇 [35 命令与配置速查表](35-cheatsheet.md) 把命令、配置键、快捷键摊成一张能贴墙上的速查表。这一篇换个层次——不讲「有哪些功能」，讲「这些功能该怎么组合着用，才能让 Codex 真的省你的事」。下一篇 [37 常见问题排查](37-faq.md) 再讲「出岔子了怎么办」。

说句实话，我刚拿到 Codex 的时候干过一件挺蠢的事：把官方 best-practices 页从头到尾看了一遍，觉得每条都很有道理，然后……合上页面，一条都没改进自己的用法。

问题不在我——在于绝大多数所谓最佳实践是正确的废话：「提示要写清楚」「记得测试」「小步迭代」——听着都对，但它没告诉你**清楚到什么程度、测什么、步小到多小**。你点头如捣蒜，回去该怎么用还是怎么用。这种万金油式的建议，本质是把责任又踢回给你。

所以这一篇我不打算复述那些谁都会说的大道理。我把官方那份 best-practices 啃了一遍，挑出**真正改变了我用法、而且我自己验证过的几条**，每条都给你「为什么要这么做 + 具体怎么做 + 不这么做会踩什么坑」。能落地的才留，听着高大上但落不了地的，一概砍掉。

说句实话，下面这几条里，大半都是我先用错了、吃了亏，才回头补上的。

**看完这一篇，你会拿到：**

- 一套把 Codex 当「队友」而非「一次性工具」来配置的思路
- `AGENTS.md`（项目说明书）到底该写什么、写多长才有用
- 一个「目标 + 上下文 + 约束 + 验收」的提示四件套，照着填就行
- 权限该按场景分几档，新手从哪一档起步
- 复杂活儿为什么要先让它出计划、再动手
- 怎么让 Codex 自己测、自己审，而不是你盯着每一步
- 一张「踩坑 ❌ / 正确做法 ✅」的对照表，直接抄

> ⚠️ 命令、配置键、默认行为以 Codex [官方文档](https://developers.openai.com/codex/learn/best-practices) 为准；模型名、可用范围随版本和套餐变动，一律以你本地 `codex --help`、`/model` 面板和 `~/.codex/config.toml` 的实际为准。

---

## 01 先换个心态：Codex 是你要调教的队友，不是一次性工具

先给结论：**用 Codex 这件事，效果好坏一大半取决于你把它当什么。**

很多人（包括早期的我）把它当成一个「问一句答一句」的搜索框：有问题丢过去，拿到答案就走，下次又从零开始。这么用，它永远只能发挥三成功力。

**类比：Codex 像你新招进来的一个能力很强、但完全不了解你们项目的新同事。** 你不会指望他第一天就什么都懂——你得给他一份入职手册（`AGENTS.md`）、告诉他代码怎么跑怎么测、踩错了纠正他一次让他记住。调教得越久，他越顺手。反过来，你要是每次都换一个不认识你的临时工来干，那永远在重复解释同一件事。

官方那份文档里有句话我很认同，大意是：**与其把 Codex 当成一次性助手，不如把它当成一个你会持续配置、持续打磨的队友。** 这一篇后面所有的实践，本质都在围绕这一句展开——把临时的、重复的东西，沉淀成持久的配置。

我自己的转折点是 2026 年初。在那之前我每开一个新会话，都要把「这项目用 pnpm 不用 npm」「测试跑 `pnpm test`」「提交信息要中文」这几句重新打一遍，一天打七八遍。直到有天我烦了，把这些塞进 `AGENTS.md`，世界瞬间清净——这才意识到我之前是在用最笨的方式使一个很聪明的工具。

> 💡 一句话总结：把 Codex 当持续调教的队友，而不是用完即弃的工具，是所有最佳实践的地基。

---

## 02 把 `AGENTS.md` 写到位：让它自动「带着上下文」干活

**为什么要这么做。** 上一节那个痛点的解药就是它。`AGENTS.md` 是放在项目里的一份说明书，Codex 每次进来会**自动读进上下文**，不用你手动 @。一个项目里反复要交代的事，写一次，永久生效。

**类比：`AGENTS.md` 是给 AI 看的 README。** 普通 README 写给人，告诉人这项目是干嘛的、怎么跑；`AGENTS.md` 写给 Codex，告诉它你们这儿的规矩、雷区和「干完算数的标准」。

**怎么做。** 官方建议一份好的 `AGENTS.md` 覆盖这几块，照着列就行：

- 项目结构和重要目录在哪
- 怎么把项目跑起来
- 构建、测试、lint 各用什么命令
- 工程约定和提 PR 的要求
- 约束和「绝对别做」的红线
- 「干完算数」的标准是什么、怎么验证

最快的起步方式是在 CLI 里敲 `/init`，它会在当前目录脚手架一份初始 `AGENTS.md`。但**别拿来就用**——生成的是模板，你得改成你们项目真实的样子。

`AGENTS.md` 还能分层：放在 `~/.codex/` 里的是你个人默认；放在项目根目录的是团队共享规范；放在子目录里的是局部规则。**离当前目录越近的越优先生效。**

**反例（我真踩过的）。** 我一开始的毛病是反着来：把一大堆「这次别动数据库」「这次只改这个文件」这种**一次性的指令**全写进 `AGENTS.md`，结果文件越滚越长、还净是过时规则，Codex 读进去反而被带偏。后来才学乖——

> 一次性的要求写进提示，持久的规矩才写进 `AGENTS.md`。短而准，胜过长而虚。

官方有个特别实用的小习惯值得抄：**当 Codex 同一个错误犯了第二次，就让它做个复盘、把教训补进 `AGENTS.md`。** 这样你的说明书是被真实摩擦喂大的，而不是你拍脑袋写的。

> 💡 一句话总结：把「持久的规矩」沉淀进 `AGENTS.md`，短、准、真实，比写一长篇空话管用。

---

## 03 提示别靠灵感：目标 + 上下文 + 约束 + 验收，四件套填空

**为什么要这么做。** 上一篇速查表里说过提示的事，这里只补一个能直接抄的结构。Codex 现在很强，你提示写得糙它也能凑合给个结果；但在大项目、高风险的活儿上，提示糊一点，它就得多猜，猜错了你返工。

官方给的「好提示默认配方」是四件套，我把它当填空题用：

| 要素 | 它在回答什么 | 不填会怎样 |
| --- | --- | --- |
| **目标（Goal）** | 你到底要改什么、建什么 | 它抓不住重点，做了一堆你没要的 |
| **上下文（Context）** | 哪些文件、报错、例子相关（可以 @ 提及文件） | 它在错的地方瞎找，绕远路 |
| **约束（Constraints）** | 要守什么规范、架构、安全要求 | 它按自己的习惯来，风格全乱 |
| **验收（Done when）** | 什么条件成立才算干完 | 它觉得「能跑」就交差，bug 留给你 |

**怎么做。** 你不用每句都写得像合同。但凡是稍微复杂、或者你不想返工的活儿，提交前在脑子里（或者就直接打出来）过一遍这四格：我要它干嘛、相关的料在哪、有什么不能碰、怎么算干完了。

**类比：这四件套像给装修队的交底。** 你不会只说一句「把厨房弄好看点」就让人开工——你得说清要什么风格（目标）、户型图水电图在哪（上下文）、承重墙不能动（约束）、验收时灯能亮水能通橱柜不晃（验收）。交底越清，返工越少。

我自己最常漏的是**验收**这一格。早些时候我让 Codex 改一个表单校验，只说了「加个手机号格式校验」，没说「加完原有的邮箱校验不能失效、相关测试得过」。它麻溜地加了手机号校验，顺手把邮箱那段逻辑挤坏了，我直到上线前跑测试才发现。从那以后，「Done when」这一格我必填。

> 💡 一句话总结：提示别靠灵感，照「目标 + 上下文 + 约束 + 验收」四格填空，尤其别漏验收。

---

## 04 复杂活儿先出计划，再动手

**为什么要这么做。** 任务一复杂、一模糊，直接让它写代码，它就得一边猜你的意图一边敲键盘，方向歪了你也很晚才发现。**让它先出个计划，等于在动手前给你一次便宜的「纠偏机会」。**

**类比：这就像盖房先看图纸。** 没人会让施工队不画图直接砌墙——砌歪了拆起来肝疼。计划就是那张图，几行字的事，比返工一整段代码便宜太多。

**怎么做。** 官方给了几种路子，我按好上手程度排：

- **用 Plan 模式（最推荐）**：在 CLI 里用 `/plan`，或者按 <kbd>Shift</kbd>+<kbd>Tab</kbd> 切换。它会先收集上下文、问你澄清问题、给一份更靠谱的计划，你点头了它再动手。
- **让它反过来采访你**：如果你自己都没想清楚，就让它「先别写，先 challenge 我、把这个模糊的想法问成一个具体的方案」。
- **用 `PLANS.md` 模板**：更进阶的玩法，让多步、长跑的任务都按一份执行计划模板走（以官方 execution plans 指南为准）。

**反例。** 官方把「多步复杂任务跳过规划」明确列进了常见错误，我深有体会。去年我让 Codex 帮我把一个模块从回调写法迁到 async/await，图省事没让它出计划，直接「你看着改」。它改是改了，但中途自作主张把我一个全局错误处理的逻辑也「顺便优化」了，整个改动糊成一团，review 时我看着那份 diff 头大，最后干脆 `git reset` 重来——这次先 `/plan`，让它列出「改哪些文件、每个文件改什么、哪些绝对不碰」，确认完再放它走，一遍过。

> 💡 一句话总结：越复杂越模糊的活儿，越要先 `/plan` 出计划、确认方向，再让它动手。

---

## 05 权限分档：默认从严，按场景逐步放宽

**为什么要这么做。** Codex 自带操作系统级沙箱，有两个关键旋钮：**审批模式（approval mode）** 管它执行命令前要不要先问你，**沙箱模式（sandbox mode）** 管它能不能读写目录、能碰哪些文件。一上来就给满权限，等于把方向盘和油门同时交给一个你还没摸清脾气的新司机。

**类比：这像给新来的实习生配权限。** 第一天你只给他读代码、本地跑测试的权限；处熟了、信得过了，再逐步开放他改文件、连数据库。没人第一天就把生产环境的钥匙塞给新人。

**怎么做。** 官方建议很直接：

- 新手就用**默认权限**起步，审批和沙箱都保持收紧。
- 等你摸清了某个工作流、确实需要更顺手了，**再针对可信仓库或特定场景**放宽，而不是一把全开。

| 场景 | 建议档位 | 理由 |
| --- | --- | --- |
| 刚上手 / 不熟的项目 | 默认（动手前问、沙箱收紧） | 看清它要干嘛再放行，安全 |
| 自己的可信仓库、重复跑的活 | 适度放宽审批 | 减少一直点「同意」的烦躁 |
| 跑不熟的脚本 / 第三方代码 | 收到最紧 | 防止它执行你没预期的命令 |

官方把「还没摸清工作流就给 Codex 完整电脑权限」单列为一条常见错误。我自己的教训不算惨但够长记性：有阵子嫌每次确认烦，把审批放得很开，结果它在一次重构里执行了个我没细看的清理命令，删了几个我以为还要用的临时文件——不是什么大灾难，但够我心里咯噔一下。**省那几秒确认，不值。**

> 💡 一句话总结：权限默认从严，看清楚再放行；只对可信场景逐步放宽，别图省事一把全开。

---

## 06 让它自验证：测、查、审，别只让它「写完」

**为什么要这么做。** 这是我认为含金量最高的一条。**别让 Codex 写完代码就停**——让它顺手把测试写了、把相关检查跑了、把改动 review 一遍，再交给你。这一步做到位，你省下的是一轮轮「它写、你测、报错、再让它修」的来回。

但有个前提：**它得知道「好」长什么样。** 这份标准从哪来？要么写在提示里，要么写在 `AGENTS.md` 里（看，又绕回第 02 节了）。

**怎么做。** 官方说的「让它闭环自查」包含这些动作，你可以直接写进要求里：

- 给这次改动写或更新测试
- 跑对应的测试套件
- 跑 lint、格式化、类型检查
- 确认最终行为真的对得上你的需求
- 把 diff review 一遍，找 bug、找回归、找危险写法

CLI 里有个 `/review` 命令特别值这一节：它能按 PR 风格跟基线分支对比着审、审未提交的改动、审某个 commit，或者按你的自定义指令审。如果你们团队有一份 `code_review.md` 并在 `AGENTS.md` 里引用了它，Codex review 时就会照着那份标准走——团队多人协作时，这能让审查口径保持一致。

**反例。** 官方把「不让 agent 看到自己的成果」（也就是没告诉它构建、测试命令怎么跑）列为常见错误。我有过一次反面典型：让它改一个数据处理函数，没让它跑测试，它信誓旦旦说「已完成、逻辑正确」，我也信了。结果那段代码在边界输入下直接抛异常——它压根没机会发现，因为我没让它跑。后来我养成习惯：**凡是改逻辑，提示末尾必带一句「改完跑 `<测试命令>`，全绿了再告诉我」。** 一句话的事，挡掉了一大半返工。

> 💡 一句话总结：让 Codex 把测、查、审一起干了再交付，前提是用提示或 `AGENTS.md` 告诉它「好」的标准。

---

## 07 重活拆给子代理，一条线程只干一件事

**为什么要这么做。** 一个会话（session）不只是聊天记录，它是一条会不断累积上下文的工作线程。线程越长、塞的东西越杂，质量越往下掉。所以**怎么管理线程，直接影响结果好坏**。

**类比：这像管理你的工作台。** 一张桌子上同时摊着三个项目的资料，你找东西、做判断都会变慢、变乱；一张桌子只摆一件正在做的事，效率最高。Codex 的线程就是它的工作台。

**怎么做（两条）。**

**第一，一条线程只干一件连贯的事。** 官方原话的意思是：只要还是同一个问题，就待在同一条线程里——它保留了完整的推理脉络。只有当工作**真的分叉**了，才用 `/fork` 另起一条。换言之，按任务拆线程，而不是按项目拆线程——最该避免的反模式正是「一个项目从头到尾就用一条线程」，那会让上下文越堆越肥、结果越来越差。

**第二，把有边界的杂活甩给子代理（subagent）。** 主线程专注核心问题，那些探索代码、写测试、做 triage 之类「能独立完成、有明确产出」的活儿，丢给子代理去跑，别让它们占用主线程的注意力。

几个管线程的趁手命令（以你本地 `codex --help` 实际为准）：

- `/resume` 接着一段存档的对话往下聊
- `/fork` 在保留原记录的前提下另起一条新线程
- `/compact` 线程太长时，把早先的上下文压缩成摘要（Codex 也会自动压缩）
- `/status` 看一眼当前会话状态

我现在的习惯是「一个任务一条线程」，任务做完那条就归档。这个改动看着小，但自从不再用「一个项目一条万能线程」之后，Codex 给我的回答明显没那么容易「串味」了——以前它经常拿三天前另一个需求的上下文来污染当前判断。

> 💡 一句话总结：一条线程只干一件事，重活、杂活拆给子代理，别让上下文越堆越肥。

---

## 08 上手清单：一张「踩坑 ❌ / 正确做法 ✅」对照表

前面七节的精华，官方在文末用一份「常见错误」清单收了尾。我把它揉成一张对照表，你可以照着自查——左边但凡中了一条，就照右边改。

| ❌ 我见过的踩坑 | ✅ 正确做法 |
| --- | --- |
| 把持久规则一股脑塞进提示里 | 持久的搬进 `AGENTS.md` 或 skill，提示只放一次性需求 |
| 没告诉它构建、测试命令怎么跑 | 在 `AGENTS.md` 里写清运行和测试方式，让它能看到自己的成果 |
| 多步复杂任务跳过规划直接写 | 复杂活先 `/plan` 出计划、确认方向再动手 |
| 还没摸清工作流就给满权限 | 默认从严，按可信场景逐步放宽 |
| 一个项目从头到尾就一条线程 | 一个任务一条线程，分叉了才 `/fork` |
| 多条线程同时改同一批文件，却不用 git worktree | 用 git worktree 给并行的线程各开一份独立工作区，互不踩脚 |
| 把还不靠谱的活急着做成自动化 | 先手动跑稳、再考虑沉淀成 skill 或自动化 |
| 盯着它一步步看，自己干不了别的 | 让它并行跑，你腾出手做自己的事 |

**怎么照做。** 这张表别只看一遍。我的建议是：**下次你用 Codex 觉得「不顺、返工多」的时候，回来对一遍左列，大概率能定位到是哪一条没做好。** 这几条踩坑，我没一条是听来的——全是自己撞过南墙才记住的。

> 💡 一句话总结：照这张对照表自查，左列中招就按右列改，比记任何「最佳实践」口诀都管用。

---

## 09 小结

这一篇没给你正确的废话，给的是七条我自己验证过、能直接改变用法的实践：

- **换心态**：把 Codex 当持续调教的队友，是一切的地基。
- **写 `AGENTS.md`**：把持久的规矩沉淀进去，短、准、真实。
- **提示四件套**：目标 + 上下文 + 约束 + 验收，照着填，别漏验收。
- **先计划后动手**：复杂活先 `/plan`，便宜的纠偏机会别省。
- **权限分档**：默认从严，看清楚再放行。
- **让它自验证**：测、查、审一起干，前提是告诉它「好」的标准。
- **管好线程**：一条线程一件事，重活甩给子代理。

**你现在应该能**：拿到任意一个 Codex 任务时，下意识过一遍——这活儿要不要先出计划、提示四件套填全没、`AGENTS.md` 里的规矩够不够、要不要让它自测、该用哪档权限。把这套变成肌肉记忆，你跟 Codex 的协作就从「碰运气」变成了「有章法」。

---

下一篇〔[37 常见问题排查](37-faq.md) 〕，咱们聊点更接地气的：再守规矩，Codex 也总有给你出岔子的时候——命令报错、改坏了、连不上、行为反常。出问题不可怕，可怕的是不知道从哪儿查起。留个小思考：这一篇讲的「先 `/plan`、勤自测、小步走」，其实大半也是在**预防**问题；那万一问题真发生了，你第一反应该去看哪儿？下一篇给你一套排查的先后顺序。
