36 · 最佳实践：那些「正确的废话」之外，真正能落地的几条
📚 系列导航：上一篇 35 命令与配置速查表 把命令、配置键、快捷键摊成一张能贴墙上的速查表。这一篇换个层次——不讲「有哪些功能」，讲「这些功能该怎么组合着用，才能让 Codex 真的省你的事」。下一篇 37 常见问题排查 再讲「出岔子了怎么办」。
说句实话，我刚拿到 Codex 的时候干过一件挺蠢的事：把官方 best-practices 页从头到尾看了一遍，觉得每条都很有道理，然后……合上页面，一条都没改进自己的用法。
问题不在我——在于绝大多数所谓最佳实践是正确的废话：「提示要写清楚」「记得测试」「小步迭代」——听着都对，但它没告诉你清楚到什么程度、测什么、步小到多小。你点头如捣蒜，回去该怎么用还是怎么用。这种万金油式的建议，本质是把责任又踢回给你。
所以这一篇我不打算复述那些谁都会说的大道理。我把官方那份 best-practices 啃了一遍，挑出真正改变了我用法、而且我自己验证过的几条，每条都给你「为什么要这么做 + 具体怎么做 + 不这么做会踩什么坑」。能落地的才留，听着高大上但落不了地的，一概砍掉。
说句实话，下面这几条里，大半都是我先用错了、吃了亏，才回头补上的。
看完这一篇，你会拿到：
- 一套把 Codex 当「队友」而非「一次性工具」来配置的思路
AGENTS.md（项目说明书）到底该写什么、写多长才有用- 一个「目标 + 上下文 + 约束 + 验收」的提示四件套，照着填就行
- 权限该按场景分几档，新手从哪一档起步
- 复杂活儿为什么要先让它出计划、再动手
- 怎么让 Codex 自己测、自己审，而不是你盯着每一步
- 一张「踩坑 ❌ / 正确做法 ✅」的对照表，直接抄
⚠️ 命令、配置键、默认行为以 Codex 官方文档 为准；模型名、可用范围随版本和套餐变动，一律以你本地
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，或者按 Shift+Tab 切换。它会先收集上下文、问你澄清问题、给一份更靠谱的计划，你点头了它再动手。 - 让它反过来采访你：如果你自己都没想清楚，就让它「先别写，先 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 常见问题排查 〕，咱们聊点更接地气的：再守规矩，Codex 也总有给你出岔子的时候——命令报错、改坏了、连不上、行为反常。出问题不可怕，可怕的是不知道从哪儿查起。留个小思考：这一篇讲的「先 /plan、勤自测、小步走」，其实大半也是在预防问题；那万一问题真发生了，你第一反应该去看哪儿？下一篇给你一套排查的先后顺序。