封面图

11 · 项目说明书 AGENTS.md：把规矩焊进 Codex 的开工流程

说个我刚上手 Codex 时干的蠢事。

那是去年我把一个 Node 项目交给 Codex，开宗明义在根目录写了份 AGENTS.md，第一行赫然写着「本项目用 pnpm，禁用 npm」。结果它转头给我来了一句 npm install。我当场以为它没读到，气得把那条规矩复制了三遍、加粗、还打了感叹号。还是不听。

折腾半天才发现——它读到了，只是那条规矩被我埋在了第 140 行。前面我塞了公司简介、产品路线图、技术选型的来龙去脉，洋洋洒洒一百多行。等 Codex 翻到「禁用 npm」那句，注意力早被前面那堆废话稀释没了。问题从来不是它不听话，是我把唯一有用的那条焊进了一坨没用的里。

AGENTS.md 之于 Codex，就是 CLAUDE.md 之于 Claude Code，同一个概念换了个文件名。但 Codex 这边的发现机制、覆写规则、字节上限自成一套，有几处容易踩的坑。这篇就把它们连同「该写什么、不该写什么」一次讲清。

看完这一篇，你会拿到：

注意： 本篇只聚焦 AGENTS.md 这一个文件怎么写好、怎么被加载。和它容易混的「记忆（Memories）」机制（那是本地自动回忆层、默认关着）在 [02 核心概念] 里已经点过，记住一句话：真正必须每次生效的团队规矩，写进 AGENTS.md，别指望记忆。

01 先搞懂：AGENTS.md 是 Codex 开工前的「交接清单」

先给结论：AGENTS.md 是你写给 Codex 的一份持久指令，它每次启动、动手干活之前都先读一遍，当成这个项目的背景装进脑子。

为什么需要它？因为 Codex 每开一轮（每轮（per run）——官方术语，在 TUI 里通常是每启动一个会话算一轮）都从一张白纸开始。上回你苦口婆心交代的「用 pnpm、别碰 legacy/、测试这么跑」，这回它一概不记得。没有 AGENTS.md，你就得每次重新解释一遍。

类比：交接班的工作清单。 工厂三班倒，上一班下班前会在墙上那块板写清楚——这台机器有点毛病别硬开、这批料要先质检、紧急联系人是谁。下一班接手，照着板上干就行，不用把上一班的人薅回来口述。AGENTS.md 就是 Codex 的那块交接板——而且是它每次接班前都会先扫一眼的那块。

（注意我这里没用「入职手册」——那个比喻 [02] 已经用过了。交接清单更贴切的地方在于：它强调「每一轮开工都重读」，不是「入职那天看一次」。）

什么时候该往里加内容？几个特别实在的信号：

我自己最爱的用法，[02] 里提过、这里再强调一次——把它当反馈回路：Codex 对你代码库做了错误假设，别光在对话里纠正（那是一次性的，下轮它又忘），直接让它把这条修正写进 AGENTS.md。我给一个 Python 项目调了两周，那份 AGENTS.md 从空白长到二十来行，全是它踩过、被我逮住、然后自己记下来的坑，现在新会话基本不犯重复错误了。

02 发现链条：Codex 是怎么找到这些文件的

AGENTS.md 不止一份，它能放在好几个地方，作用范围从大到小。Codex 启动时会把它们串成一条「指令链」。这一节就把这条链拆开——这也是跟 Claude Code 差异最大的一块，看仔细。

按官方文档，Codex 构建指令链分两步走（一轮一构建，TUI 里通常是每启动一个会话构建一次）：

第一步，全局层（Global scope）。 在你的 Codex 主目录（默认 ~/.codex ，除非你设了 CODEX_HOME 环境变量）里，Codex 先看有没有 AGENTS.override.md ，有就用它；没有才读 AGENTS.md 。这一层只取第一个非空文件，不会两个都读。

第二步，项目层（Project scope）。 从项目根目录（通常是 Git 根）开始，一路往下走到你当前所在的目录。沿途每一个目录里，Codex 按这个顺序挑：先看 AGENTS.override.md ，再看 AGENTS.md ，最后看 project_doc_fallback_filenames 里你自定义的备选文件名。每个目录最多只收一个文件。

第三步，合并（Merge order）。 Codex 把找到的这些文件从根到叶依次拼接，中间用空行隔开。越靠近你当前目录的文件，因为排在拼接结果的越后面，优先级越高、能盖过前面的。

光说有点绕，上张图：

AGENTS.md 三层发现链：机器级 ~/.codex/（override 优先）→ 项目层 Git 根逐级累加 → 拼成指令链

这张图把整条链走了一遍：先在全局层二选一，再到项目层逐级各挑一个，最后从根到叶拼起来——离你越近的，说话越晚、越管用。

这里有两个要点，都来自官方，记牢：

第一，是「拼接」不是「覆盖」。 全局那份和项目那份同时生效，不存在「写了项目级，全局级就失效」。它们全都进上下文，后面的不会把前面的整个顶掉，只是冲突的条目以靠后（更近）的为准。

第二，更近的赢。 比如全局 AGENTS.md 说「字符串用单引号」、项目根 AGENTS.md 说「用双引号」——项目根离当前目录更近、排得更靠后，所以双引号胜出。说白了，项目规矩能盖过你的个人偏好，这正是团队协作想要的。

类比：导航地图的三层缩放。 全国地图给你大方向（全局层），城市地图给你城区路线（项目根），小区门口的指示牌告诉你最后那几步怎么走（子目录）。三层同时有效、信息互不删除；可一旦小区门口的牌子和大地图对不上，以现场最近那块牌子为准——它最贴你眼前这一步。AGENTS.md 这条链就是这套「越靠近当前位置越具体、冲突时越优先」的逻辑。

AGENTS.md 三层发现链、就近优先

这张图把三层从上到下叠了出来——全局层（~/.codex/）、仓库根、子目录依次拼接，三层同时生效；右侧那根「优先级」轴在提醒你：越靠近当前目录的那一层，排在拼接结果越靠后、冲突时越管用，这就是「就近覆盖」。

03 AGENTS.override.md：Claude Code 没有的「临时盖章」

上一节反复出现一个名字——AGENTS.override.md 。这玩意儿 Claude Code 那边没有对应物，是 Codex 独有的设计，单独拎出来讲。

先说它解决什么问题。设想你 ~/.codex/AGENTS.md 里写了一套团队共用的全局约定，平时挺好。但今天你接了个临时活，需要整段换掉这套全局指导，又不想把原文件删了（删了回头还得重写）。怎么办？

类比：在文件上盖一张「以此为准」的便签。 原合同还在抽屉里，你没撕；只是临时贴了张便签条「本月按这个新条款执行」。事儿办完，便签一揭，原合同自动生效。AGENTS.override.md 就是这张便签——它在时，同级的 AGENTS.md 被整个跳过；把它删了，原来那份立刻回来。

官方给的两个典型场景：

# services/payments/AGENTS.override.md ## 支付服务规则 - 用 `make test-payments` 替代 `npm test`- 轮换 API Key 前必须先通知安全频道

放了这个 override，这个目录里同级的 AGENTS.md 就被跳过（如果有的话），Codex 在这个目录干活时认 override 这份。

这里要拎清一个新手最容易混的点——override 跟「覆盖整条链」不是一回事：

复制

它存在 → 同级的 AGENTS.md（和备选文件名）被跳过，这一层只认 override

说白了：override 是「这一层用我，别用旁边的 AGENTS.md」，不是「全链路只听我一个」。整条链的拼接、就近优先规则照旧。我第一次用的时候就理解错了，以为在子目录放个 override 能把全局那份屏蔽掉，结果全局约定照样生效——后来翻官方文档才搞明白，它只在自己那一格里二选一。

还有个排查神器级的用法：万一 Codex 蹦出来一条你压根没写的奇怪指令，第一件事就是顺着目录树往上、连同 ~/.codex ，找有没有谁藏了个 AGENTS.override.md。把它改名或删掉，就回退到常规 AGENTS.md 了。官方排查清单里专门列了这条。

04 该写什么 vs 不该写什么

这一节是全篇的命门，也是我开头那个「140 行没人听」的解药。AGENTS.md 写不好，九成栽在「该写的没写清，不该写的塞一堆」。

先说该写的——一句话：写「Codex 在每一轮里都该保持的事实」。翻成清单就是这五类：

其中常用命令是被参考最频繁的——Codex 跑测试、提 PR 前会先来这儿翻命令，省得它瞎猜或者用错。官方那份示例 AGENTS.md 里头第一条就是命令：「提 PR 前运行 npm run lint 」。禁止清单则是防它「聪明但闯祸」的护栏：哪些目录是遗留代码只读不改、哪个操作改之前必须先问你。

再说不该写的，这才是新手翻车重灾区，也是我亲身踩过的坑：

官方对「别写太大」给了硬性约束，但它的红线跟 Claude Code 不太一样——Claude Code 是「按行数」（建议 200 行内），Codex 是「按字节」：

Codex 跳过空文件，一旦拼接后的总大小达到 project_doc_max_bytes 限制（默认 32 KiB），就停止继续加文件。

注意这话有两层意思：一是默认 32 KiB 封顶，超了就截断（甚至整个文件被拦在外面）；二是这个上限算的是合并后的总和，全局 项目 子目录加一块儿。所以你一份文件写太肥，可能把后面更重要的那份顶出窗口。官方建议：撞上限了，要么调高 project_doc_max_bytes ，要么把指令拆到多级子目录分散放（这正好呼应 [04 计费] 里讲的「AGENTS.md 瘦身 按子目录分层」省 token）。

有个好用的土办法，我现在写每一条之前都先自问一句：「这条 Codex 看代码能不能自己推出来？能，就删。」 就靠这一刀，能把一份接手项目的 AGENTS.md 从一百多行砍到几十行，留下的全是它推不出来的硬约束——砍完之后，它用错包管理器的次数肉眼可见地降下去。

05 两个旋钮：改文件名、调字节上限

大多数人用默认的 AGENTS.md 就够了。但有两种情况你得动配置——这一节讲两个写在 ~/.codex/config.toml（Codex 的用户级配置文件）里的旋钮。

旋钮一：让 Codex 认你已有的文件名

设想你仓库里早就有一份 TEAM_GUIDE.md ，全队一直拿它当规范文档。你不想再造一个 AGENTS.md 重复一遍，想让 Codex 直接把 TEAM_GUIDE.md 当指令文件读。这时候就用 project_doc_fallback_filenames（备选文件名）：

# ~/.codex/config.tomlproject_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

加了这条之后，Codex 在每个目录里的挑选顺序变成：AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md ，取第一个存在（且非空）的。

旋钮二：合并内容被截断了，调高上限

上一节说过默认 32 KiB 封顶。如果你的指令确实超了、又暂时不想拆文件，可以把 project_doc_max_bytes 调大：

# ~/.codex/config.tomlproject_doc_max_bytes = 65536

这就把上限抬到了 64 KiB，能塞下更多合并指导才触顶。不过我得劝一句——这是治标。内容真有用，调上限；但更多时候，撞上 32 KiB 是个信号，提醒你「该精简了」或「该按子目录拆了」，而不是「该把上限往上拱」。我自己的偏好是优先拆、其次删，实在拆不动才抬上限。

两个旋钮的适用场景对照一下：

复制

project_doc_fallback_filenames 加上它的名字

06 动手：给玩具项目配一份合格的 AGENTS.md 并验证加载

光说不练没用。下面用一个最小项目，走一遍「建文件 → 写规矩 → 验证 Codex 真读到了」的完整流程。跟着敲，几分钟搞定。

第一步：建个玩具项目并初始化 git

mkdir agents-md-democd agents-md-demogit init

预期：agents-md-demo 目录里出现一个 .git 目录。git 初始化是为了让 Codex 能把这里识别成「项目根」（它通常以 Git 根为起点往下扫），也为了这份 AGENTS.md 能进版本控制、团队共享。

第二步：手写一份精简的项目级 AGENTS.md

用你顺手的编辑器，在项目根目录新建 AGENTS.md ，贴入下面这份（注意它一共没几行——这就是好 AGENTS.md 该有的样子）：

# agents-md-demo — 一个演示用的最小项目 只有用来演示 AGENTS.md 怎么写，没有真实业务逻辑。 ## 常用命令 - `npm test` —— 运行测试 ## 编程约定 - 所有函数必须有类型注解- 字符串一律用双引号 ## 注意事项 - 不要新增任何生产依赖，需要时先问我

预期：项目根目录下出现 AGENTS.md ，内容就是上面这几节。全文十几行——记住这个篇幅感，真实项目也别失控膨胀。

第三步：让 Codex 复述它读到的指令

官方给了一个特别直接的验证法——让 Codex 把当前生效的指令总结一遍。在项目目录里跑：

codex --ask-for-approval never "Summarize the current instructions."

预期：Codex 在动手提方案之前，会回显你刚写的那几条（命令、类型注解、双引号、别加依赖）。只要它复述出来了，就说明这份 AGENTS.md 这一轮确实被装进了它的上下文。

第四步（进阶）：验证子目录覆写真的「就近优先」

想亲眼看到「越近越管用」，再做一步。在项目里建个子目录，放一份只覆盖一条命令的 override：

mkdir -p services/payments

在 services/payments/AGENTS.override.md 里写：

# services/payments/AGENTS.override.md ## 支付服务规则 - 用 `make test-payments` 替代 `npm test`

然后从这个子目录的视角启动 Codex，让它报告加载了哪些指令来源：

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

预期：按官方描述，Codex 会依次列出——先全局文件（如果你 ~/.codex 下有的话）、再仓库根的 AGENTS.md 、最后是支付服务这份 override；而且这一层的测试命令会以 override 的 make test-payments 为准，根目录那条 npm test 在这个子目录里被盖掉了。这就是「就近优先」的活样本。

07 小结

这一篇你把 AGENTS.md 这个「Codex 的项目说明书」从发现机制到落地写法摸清了：

复制

每轮开工必读的交接清单，就是 CLAUDE.md 换了个名

你现在应该能： 判断一条信息该不该进 AGENTS.md 、该放哪一层；看懂多层文件冲突时谁赢；用 AGENTS.override.md 临时换指导、又不删原文件；撞上字节上限知道是拆还是抬；用「Summarize the current instructions」一句话验证 Codex 到底读没读到。一句话——你能写出一份 Codex 真愿意听、而不是像我当年那样写了 140 行没人理的 AGENTS.md 了。

下一篇 12「斜杠命令与快捷键」——这篇里你已经在命令行里敲了好几次 codex ... ，那进了会话之后呢？/ 开头的斜杠命令能让你当场切模式、清上下文、看状态，再配上几个顺手的快捷键，操作效率能翻倍。下一篇就把会话里这套「快捷操作面板」一次摊开。留个小思考：这一篇让 Codex「记住规矩」靠的是写文件，那要是想在会话当场改它的行为、又不想动 AGENTS.md ，你猜该用什么？