Codex 的 AGENTS.md 怎么写

这篇适合谁、读完能做到什么

如果你每开一个仓库都要重复交代同一套规矩，比如跑哪些测试、用哪个包管理器、哪些依赖要先征得同意，这篇适合你。读完你能写出全局和项目两层的 AGENTS.md，知道 Codex 按什么顺序读取它们，并能用一条命令确认哪些文件真正生效。^[1]

AGENTS.md 怎么被找到

Codex 每次运行时构建一次指令链；在终端界面里，这通常等于每个会话构建一次。指令链分两层。^[1]

全局层放在 Codex 主目录里，默认是 ~/.codex，设置了 CODEX_HOME 环境变量则以它指定的目录为准。Codex 先找 AGENTS.override.md，没有再找 AGENTS.md，并且只使用第一个非空的文件。^[1]

项目层从项目根目录开始，通常是 Git 仓库的根目录，然后一路向下走到当前工作目录。每个目录依次检查 AGENTS.override.md、AGENTS.md，再检查你配置的备用文件名，同一个目录最多取一个文件。如果找不到项目根目录，就只检查当前目录。^[1]

合并时，Codex 从上到下把文件用空行连起来。离工作目录越近的文件排得越靠后，规则也就覆盖越靠前的文件。空文件会被跳过。合并后的内容一旦达到 project_doc_max_bytes 的上限（默认 32 KiB），后面的文件就不再加入。^[1]

为什么要分层

全局文件适合放你个人的习惯，比如固定使用哪个包管理器；项目文件适合放这个仓库的测试和格式要求。Codex 按从上到下的顺序合并，离工作目录越近的规则越靠后，也就越能覆盖前面的规则。合并结果超过上限后，后面的文件就不会再加入，所以每个文件都应当精炼。^[1]

第一步：写全局指令

在主目录下建一个文件，写上你希望在所有项目里都生效的习惯：

# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

在任意目录运行下面的命令，确认文件已经加载：

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

正常情况下，Codex 会在提出方案之前先复述 ~/.codex/AGENTS.md 里的条目。^[1] 如果只想临时改一下全局规则，又不想动基础文件，就新建 ~/.codex/AGENTS.override.md，用完删掉即可恢复共用的规则。^[1]

第二步：在仓库根目录写项目规则

在仓库根目录新建 AGENTS.md，写上项目的基本约定：

# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

全局文件和项目文件会合并生效，所以项目里只需要写这个项目特有的内容。^[1]

第三步：在子目录里覆盖规则

不同团队的命令往往不一样。比如支付服务要用自己的测试命令，就在 services/payments/ 下新建 AGENTS.override.md：

# services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

同一目录里有覆盖文件时，旁边的 AGENTS.md 会被忽略。^[1] 从支付目录启动 Codex，可以检查加载顺序：

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

预期结果是：全局文件排第一，仓库根目录的 AGENTS.md 排第二，支付服务的覆盖文件排最后。^[1] Codex 走到当前目录就停止向上查找，所以覆盖文件要尽量放在离它管的代码最近的地方。^[1]

用 AGENTS.md 写代码审查规则

Codex 的 GitHub 代码审查同样读取 AGENTS.md。想让它检查某类问题，就在离相关代码最近的那个文件里加一节 ## Code Review Rules：仓库通用的检查放在根目录，某个服务专用的检查放在它自己的子目录。^[1]

每条规则要写短。先说明要标记的行为，再给出安全的写法和例外情况。格式和 lint 检查应当交给 CI，不必放进审查规则。^[1]

官方文档里的示例规则和实验有关：如果在处理组的比较中，按用户曝光之后的行为（比如转化或留存）来过滤，就应当标记出来。安全的做法是按分配或曝光建立分组，把转化当作结果来报告。^[1]

换一个指令文件名

如果仓库已经有 TEAM_GUIDE.md 之类的文件，就把它加进 ~/.codex/config.toml 的 project_doc_fallback_filenames：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

改完后重启 Codex 或新开一个会话。之后每个目录的检查顺序是 AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md，列表之外的文件名在指令发现时会被忽略。^[1] 示例把大小上限调到 65536 字节，让更多内容能在被截断之前放进去。^[1]

用 CODEX_HOME 切换配置

设置 CODEX_HOME 可以让 Codex 指向另一个主目录，适合给自动化专用的账户单独配一套规则：

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

输出的文件路径都相对于这个自定义的 .codex 目录。启动前可以先运行 echo $CODEX_HOME，确认当前用的是哪个主目录；如果它不是默认值，说明 Codex 读的是另一套文件。^[1]

怎么确认哪些文件被读取

用 codex -c log_dir=./.codex-log 启动 Codex，然后查看 ./.codex-log/codex-tui.log，就能看到用了哪些指令文件。开启会话日志后，最新的 session-*.jsonl 文件也记录了同样的信息。^[1]

常见问题

什么都没加载。 确认当前所在的是你想用的仓库，codex status 显示的工作区根目录符合预期，并且指令文件不是空的。^[1]
出现了不该有的规则。 往上找有没有 AGENTS.override.md，包括 Codex 主目录下的那个。改名或删除它，就会回退到普通文件。^[1]
备用文件名不生效。 检查 project_doc_fallback_filenames 里的拼写，然后重启 Codex。^[1]
指令被截断。 调大 project_doc_max_bytes，或者把大文件拆到子目录里。^[1]
指令看起来是旧的。 在目标目录重新启动 Codex。Codex 每次运行都会重建指令链，没有需要手动清除的缓存。^[1]