Codex AGENTS.md：放在哪里、按什么顺序加载、该写什么

Codex 在哪里查找 AGENTS.md，按加载顺序

Codex 在启动时构建一次指令链（在终端界面里，每个会话一次）。文件按这张表从上到下拼接，所以离工作目录越近的指令越靠后，优先级越高。

如何为 Codex 设置 AGENTS.md

1. 创建全局默认设置

   运行 mkdir -p ~/.codex，在 ~/.codex/AGENTS.md 里写下你希望在每个仓库都生效的偏好。让 Codex 总结一下它的指令，确认已经加载。

   # ~/.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.

2. 添加项目文件，团队规则不同的地方用覆盖文件

   在仓库根目录放一个 AGENTS.md，写共用的设置。在规则不同的文件夹里添加 AGENTS.override.md：它会取代该文件夹的 AGENTS.md，Codex 随后就不再读那个文件。

   # AGENTS.md (repository root)
   
   ## Repository expectations
   
   - Run `npm run lint` before opening a pull request.
   - Document public utilities in `docs/` when you change behavior.
   
   # 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.

3. 确认加载了哪些文件

   在你关心的文件夹里启动 Codex，比如 codex --cd services/payments，让它列出已加载的指令来源。它应该依次列出全局文件、根目录文件和该文件夹的文件。

4. 沿用现有文件名，或者提高上限

   如果仓库已经把指令写在别的文件里，把它加到 ~/.codex/config.toml 的 project_doc_fallback_filenames 中。合并后的大小达到 project_doc_max_bytes（默认 32 KiB）时，Codex 就不再添加文件。

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

5. 为 Codex 代码审查添加规则

   要让 GitHub 上的 @codex review 用上规则，就在离相关代码最近的 AGENTS.md 里加一个 ## Code Review Rules 部分。写明要指出什么问题以及安全的替代做法；格式和 lint 交给 CI。

   ## Code Review Rules
   
   ### Experiment cohorts
   
   - Do not filter treatment comparisons on post-exposure behavior.
     Safe path: build cohorts from assignment or exposure.

来源：Codex 文档，Custom instructions with AGENTS.md

AGENTS.md 最佳实践

• 只写 Codex 自己弄不清楚的：准确的构建、测试和 lint 命令（包括如何只跑一个测试）、代码库里的坑，以及没有写在任何地方的决定。
• 把最具体的规则放在离代码最近的地方：services/payments/ 里的嵌套 AGENTS.md，胜过根目录长文件里的一节支付说明。
• 注意 32 KiB 的预算：文件从根目录往下依次加入，超出的部分会被截掉，所以把长文件拆成嵌套文件，或者提高 project_doc_max_bytes。
• 临时调整用 AGENTS.override.md，全局或单个文件夹都可以，删掉它就恢复原样。
• 空的 AGENTS.md 会被跳过，该目录会继续查找下一个文件名。
• 给自动化用户单独设置 CODEX_HOME，这样他们的全局指令不会和你的混在一起。

Codex 与 Claude Code 等工具中的 AGENTS.md 对比

AGENTS.md 是很多 agent 都会读取的开放格式，所以最适合放你想共用的指令。Claude Code 有自己的文件 CLAUDE.md，详见 CLAUDE.md 指南。

AGENTS.md 告诉 Codex 怎么做，Crewmark 告诉它下一步做什么。

好的 AGENTS.md 能让每个 Codex 会话一开始就了解情况，但会话仍然要等你的提示。Crewmark 把 Codex、Claude Code、DeepSeek Harness 或 OpenCode 会话变成有岗位、目标和工作时间的 AI 员工，并按心跳唤醒它，从看板上接手下一个 issue。

1. 把 AGENTS.md 留在仓库里

   员工的 Codex 会话会像你的会话一样读取它，约定和测试命令都会一并带上。

2. 让心跳启动工作

   在工作时间内，员工每 15、30 或 60 分钟在同一个对话里醒来一次；参见如何让 Codex 主动工作。

3. 在一个看板上混用 agent

   一份 AGENTS.md 可以同时服务 Codex 和 Claude Code 员工；两者的比较见 Claude Code 与 Codex 对比。

Codex AGENTS.md 常见问题