Codex 的 AGENTS.md 该写什么、写多长、放在哪一层

2026-08-09

写 AGENTS.md 这件事，大部分人卡住的地方不是「写什么内容」，而是写完之后不确定它到底有没有被读进去、被读进去多少、在 monorepo 里算哪个目录的。这篇只讲能查到硬依据的那部分：Codex（OpenAI Codex）在配置层面给了哪几个键来控制项目文档的读取，怎么组合，怎么验收，以及哪些活儿别指望它。

先把边界说在前面。官方有一整页专门讲这件事，页名是《Custom instructions with AGENTS.md》。这次我只核对了《Configuration Reference》里与项目文档相关的配置键，没有取这一页的正文，所以关于「多层 AGENTS.md 如何合并、谁覆盖谁」这类问题，我不替官方下结论，请以那一页为准。下面写的每一条，都能在配置参考或本机只读命令的输出里找到出处。

一、「放在哪一层」：先搞清两层文件的位置

在 codex-cli 0.147.0（Windows 11）上查看 CODEX_HOME 目录（默认 ~/.codex/）时，里面除了 config.toml、auth.json、log/、sessions/ 这些，确实存在一个 AGENTS.md 文件——这就是全局层的自定义指令，跟着你这台机器走，与具体仓库无关。

另一层是项目层，也就是放在代码仓库里的那份。项目层的关键不在于你把文件放哪，而在于 Codex 认为「项目根」是哪个目录。配置参考里给了这个键：

键	作用
`project_root_markers`	用来判定项目根的标记文件
`project_doc_max_bytes`	读取 `AGENTS.md` 的最大字节数
`project_doc_fallback_filenames`	`AGENTS.md` 不存在时的备选文件名

这三个键就是「放在哪一层、写多长、叫什么名」的全部配置面。注意 project_doc_max_bytes 官方没有给默认值，所以别照着某个你以为的数字去规划篇幅——真要控制，就显式写进配置里。

还有一个很容易被忽略的因素：CLI 的 -C, --cd <DIR> 决定 agent 的工作根目录。monorepo 里在仓库最外层起会话，和 cd 到某个子包里起会话，项目根的判定起点就不一样。官方排查条目里也有一条同源的坑：同事的本地环境配置识别不到，原因是配置不在 .codex 文件夹里，官方给的做法是确保 .codex 文件夹在项目根，monorepo 要打开正确的目录。这一条原文面向桌面应用（不是 CLI，我们也没实测桌面端），但「monorepo 要认对目录」这个判断依据对命令行同样适用。

二、配置怎么写

下面这段是把上面几个键组合起来的示例，可以直接贴进 ~/.codex/config.toml 再按自己仓库改：

# ~/.codex/config.toml

# 项目根怎么认定：命中这些标记文件的目录就是项目根
project_root_markers = [".git"]

# 读取 AGENTS.md 的最大字节数。官方没给默认值，这里的数字是占位，不是默认值
project_doc_max_bytes = 32768

# 与项目文档并行的另一条指令通道：把长指令单独放一个文件
model_instructions_file = "~/.codex/my-instructions.md"

以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。取值部分（标记文件列表、字节数）是占位写法，官方文档没有给出这几个键的默认值。

几个键为什么在这里，逐条说：

project_root_markers 放第一位，因为它决定后面两个键从哪个目录开始生效。你如果不确定 Codex 认的是哪个根，先动这个键比先改文件内容有用得多。
project_doc_max_bytes 是字节不是字符。中文在 UTF-8 下一个字通常占 3 个字节，一份两千汉字的 AGENTS.md 光正文就是六千字节起步。用字节做上限意味着中文写作者的「可写长度」比英文写作者短不少，这是规划篇幅时必须先算的一笔账。
project_doc_fallback_filenames 没有出现在上面的配置块里，是故意的：官方文档只写了它的用途——仓库里没有 AGENTS.md 时用哪些文件名兜底——没有给示例取值，我不替它编一个。真要用，值里填的是你仓库既有那份约定文档的实际文件名（从别的工具迁过来、已经有一份别的名字的约定文档时，配这个键比重命名文件安全），格式与上面几个数组键一致。
model_instructions_file 在配置参考里与 instructions、developer_instructions 并列。其中 instructions 官方标注是保留供将来使用，并明确写了优先用 model_instructions_file——所以别往 instructions 里塞东西。

临时试一次、不想改文件，用 -c 顶层选项覆盖即可。-c 用点号路径表示嵌套，value 按 TOML 解析，解析失败会按字面字符串处理：

codex -c project_doc_max_bytes=16384 \
      -c 'project_root_markers=[".git"]' \
      exec "读一下项目约定，然后只列出你打算遵守的几条"

配置参考里还有一个 projects.<path>.trust_level，作用是把某个项目标为受信或不受信。这次核对没拿到它的取值枚举，所以我不写具体值，用之前请查官方《Configuration Reference》。

三、AGENTS.md 里该写什么

这一节是经验，不是官方规则，按你自己的仓库调整。

有字节上限这个客观约束在，AGENTS.md 就不该当成项目 wiki 写。真正值钱的是那些模型光看代码看不出来、猜错了代价还很大的信息：这个仓库用哪个包管理器、跑测试的确切命令是什么、哪些目录是生成物不许手改、提交信息有没有格式要求、哪一类改动必须先问人。这些东西每条一两行，加起来往往不到两千字节。

反过来，几类内容占字节但基本不产生收益：把 README 抄一遍、把目录结构列成树、写一堆「请保持代码整洁」这种模型本来就会说的空话、以及把项目历史当故事讲。真的删不动，就把长内容挪到 model_instructions_file 指向的独立文件里，别和项目文档抢同一个字节额度。

另外一条硬规矩：AGENTS.md 会跟着仓库走，所以里面一个密钥、token 都不许出现。要传密钥用环境变量，写成 <YOUR_API_KEY> 这类占位符，别图省事贴真值。

四、产出物长什么样，怎么验收

产出物就是两个 Markdown 文件：~/.codex/AGENTS.md（全局层，本机实测存在）和仓库里那份项目层文件。没有生成物、没有缓存文件需要清，改完存盘就是全部。

要验收的话，人需要检查这几处，按最容易出错的顺序排：

第一处：配置到底加载成功了没有。 这一步排在最前面，因为在 codex-cli 0.147.0（Windows 11）上有一个反直觉的实测结论：故意用 codex -c 'features=[unclosed' doctor --summary 传一段语法不合法的 TOML，命令没有崩溃退出，doctor 照常跑完，只是在结果里出现一行

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

也就是说，配置写坏了 Codex 不会当面拦你，它会安静地按没有这份配置在跑。所以「我改了 project_doc_max_bytes 但感觉没变化」，第一步永远是 codex doctor --summary 看这一行是 ✓ 还是 ✗。

第二处：别指望 doctor 替你确认 AGENTS.md 被读了。 在 codex-cli 0.147.0（Windows 11）上，codex doctor --summary 的 Configuration 分组观测到的检查项是 config、auth、mcp、sandbox 四项，没有针对项目文档的检查项。doctor 能告诉你配置文件本身健康，不能告诉你那份 AGENTS.md 的内容进没进上下文。这个预期要先摆正，否则会在 doctor 上白折腾半天。顺带一提，codex doctor --json 的官方说明是「Emit a redacted machine-readable report」，是脱敏的，可以贴到 issue 里给别人看。

第三处：拼写错误不一定会报错。 --strict-config 的说明是：config.toml 里出现本版本不认识的字段时直接报错退出。但在 codex-cli 0.147.0（Windows 11）上实测 codex -c model_reasoning_effortt=high --strict-config exec --help，结果是正常打印 help，没有报未知字段错误——说明这个校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径不触发。所以拿 --help 去验证键名有没有拼错是无效的，得走会进入会话的路径。

第四处：worktree 场景要单独看一眼。 官方排查条目里有一条：代码在 worktree 上跑不起来，原因是 worktree 是另一个目录、继承的是 Git 文件、缺依赖；官方给的做法是通过本地环境跑初始化脚本，或者用 .worktreeinclude 把被忽略的文件纳入进来。把这条套到本文的场景上就是：只要某个文件没被 Git 跟踪，它不会自动出现在 worktree 目录里。如果你的约定文档因为某种原因被 gitignore 了，在 worktree 里它就是不存在的。

五、什么情况不适用

AGENTS.md 不是权限控制，别拿它当围栏。 「不许改 .env」写进项目文档，是一句请求，不是一道锁。真正的硬边界在别的地方：sandbox_mode 三档（read-only / workspace-write / danger-full-access）、approval_policy（untrusted / on-request / never，也可以写成表来做细粒度开关），以及权限档 permissions.<name>.* 那一套。文档层和沙箱层是两件事，混为一谈是很危险的想法。

团队级强约束也不该只靠它。 配置参考里 guardian_policy_config 的说明是受管 Markdown 评审策略、覆盖本地策略，auto_review.policy 则是本地 Markdown 评审策略且受管配置优先。要在团队里落实必须遵守的规则，有硬依据的方向是受管配置这一层——它明确写了会覆盖本地策略，而项目文档没有这种效力，指望每个人自觉在自己仓库里写一份文档是靠不住的。官方另有一页叫《Rules》，我们这次没有取它的正文，不替它下结论，需要的话请自行查阅。

跨会话的经验沉淀是另一套机制。 Memories 有独立的配置组，且 features.memories 官方默认是 false；在 codex-cli 0.147.0（Windows 11）上 codex features list 观测到 memories 阶段为 stable、当前生效值为 false。别把「希望它记住上次的教训」这种诉求写进 AGENTS.md 硬凑。

桌面应用、IDE 扩展、Codex cloud 上项目文档怎么生效，本文没有依据。 这三面我们完全没有实测，只知道官方分别有《ChatGPT desktop app》《Codex IDE extension》《Codex cloud》等页面。另外，官方排查条目里还有一条值得记住：功能在 CLI 有、桌面应用没有，原因往往是两个面的 Codex 版本不同，官方给的做法是分别查版本——CLI 用 codex --version。这台机器上还遇到过同一天前后两次 codex --version 得到不同版本号（0.131.0 与 0.147.0）的情况，所以排查任何版本相关问题，都以当次命令的实时输出为准，别用记忆里的版本号。