AGENTS.md 是什么、和 CLAUDE.md 什么关系，在AGENTS.md：一份能给八种工具看的说明书里讲过。这一节讲具体怎么放、怎么写、怎么确认它生效了。
加载顺序
Codex 启动时会拼出一条「说明书链」，顺序是：
① 全局那一层
在你的 Codex 主目录（默认 ~/.codex，可以用环境变量 CODEX_HOME 改）：
- 先找
AGENTS.override.md - 没有再找
AGENTS.md - 这一层只取第一个非空的文件
② 项目那一层
从项目根目录（通常是 Git 根）一路走到你当前所在的目录，每一级都查一遍：
AGENTS.override.mdAGENTS.md- 配置里指定的备用文件名（默认还会认
TEAM_GUIDE.md、.agents.md）
每一级最多取一个文件。
合并规则：越近的越有话语权
所有找到的文件按从上到下的顺序拼接，离你当前目录越近的排在越后面。
后面的压前面的。 所以子目录里的规矩能覆盖项目根的规矩。
这条规则在一个仓库里放几个子项目时特别有用：根目录写共同的，各子目录写各自的。
32 KiB 上限，而且是安静失败
Codex 累计读到 32 KiB 就停止，后面的文件一律不读。
⚠️ 它不会报错，也不会提醒你。 你写了，它没看见，而你不会知道。
默认值叫 project_doc_max_bytes，可以调，但更该做的是把说明书写短。三万多字节的说明书，本身就说明里面装了不该装的东西。
空文件会被跳过。
里面该写什么
判据只有一条：不写下来就会做错的东西。
值得写的：
- 这个项目是干什么的，一句话
- 常用命令、文件在哪
- 这个项目独有的规矩——而且每条都要能被检验对错
- 明确不做的事，各写清楚为什么
不值得写的：
- 通用编程建议（它本来就会）
- 「注意代码质量」这种检验不了的话
- 今天做了什么（那是日志）
关于最后一条，一句实在话：说明书一旦开始记流水账，几个月后会长成一份没人愿意读的东西，然后所有人都不看它了——包括 AI，因为它已经超过 32 KiB 被截断了。
「明确不做的事」为什么最值钱
一份说明书里最省事的部分，往往是那几条「不要做 X，因为 Y」。
原因是：AI 会自己想出该做什么，但想不出你为什么曾经决定不做某件事。 那个决定背后的代价、教训、踩过的坑，只有你知道。不写下来，它每次都会热心地把你删掉的东西加回来。
怎么验证它真被读到了
别猜，问它：
codex --ask-for-approval never "把你当前读到的全部说明来源列一遍"
它会把加载链列出来。这一步值得做一次——尤其是在你刚改完目录结构、或者刚发现「它怎么老是不听话」的时候。
九成的「说明书不生效」是这三种：放错了目录层级、文件名拼错、超过 32 KiB 被截断了。这三种问的时候都能一眼看出来。
本节事实查证日期：2026-09-10。 依据：OpenAI 官方文档 Custom instructions with AGENTS.md。