Skip to content
FunCoding

Search

Search docs, agents, posts, Skills and MCP servers

AGENTS.md：自定义指令

Codex 在开始工作前读取 AGENTS.md：全局与项目指令的发现顺序、覆盖文件、回退文件名、大小限制与排查。

Codex 在开始任何工作之前读取 AGENTS.md 文件。把全局指引与项目特定的覆盖分层叠加，就能让每个任务都以一致的预期开始，无论你打开哪个仓库。

Codex 如何发现指引

Codex 在启动时构建一条指令链（每次运行一次；在 TUI 里通常指每个启动的会话一次），发现遵循这个优先顺序：

  1. 全局范围：在 Codex 主目录（默认 ~/.codex，除非设置了 CODEX_HOME），如果存在 AGENTS.override.md 就读它，否则读 AGENTS.md；这一层只使用第一个非空文件
  2. 项目范围：从项目根（通常是 Git 根）开始一路向下走到当前工作目录；找不到项目根时只检查当前目录。沿路径的每个目录里依次检查 AGENTS.override.md、AGENTS.md，然后是 project_doc_fallback_filenames 里的回退文件名；每个目录最多包含一个文件
  3. 合并顺序：Codex 从根向下把文件拼接起来，用空行连接；离当前目录越近的文件越靠后出现在合并后的提示里，因此覆盖更早的指引

Codex 跳过空文件，并在合并后的大小达到 project_doc_max_bytes（默认 32 KiB）时停止添加文件。碰到上限时，提高上限，或把指令拆到嵌套目录里。

创建全局指引

在 Codex 主目录里创建持久默认值，让每个仓库都继承你的工作约定：

mkdir -p ~/.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.

在任何地方运行 Codex 确认它加载了该文件（预期 Codex 在提出工作之前引述 ~/.codex/AGENTS.md 里的条目）：

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

需要临时的全局覆盖而不删除基础文件时，用 ~/.codex/AGENTS.override.md，移除覆盖文件即可恢复共享的指引。

分层的项目指令

仓库级文件让 Codex 了解项目规范，同时继承你的全局默认值。在仓库根添加涵盖基本设置的 AGENTS.md；特定团队需要不同规则时，在嵌套目录里加覆盖，例如在 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.

从 payments 目录启动 Codex：

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

预期 Codex 先报告全局文件，其次是仓库根的 AGENTS.md，最后是 payments 覆盖。Codex 在到达当前目录后就停止搜索，所以把覆盖放在尽量靠近专门工作的地方。同一目录里存在覆盖文件时，该目录的 AGENTS.md 会被忽略。

添加代码评审规则

对 GitHub 里的 Codex 代码评审，在最靠近相关代码的 AGENTS.md 里添加 ## Code Review Rules 一节；仓库范围的检查放在根目录，服务特定的检查放在嵌套文件里。保持规则简洁，说明要标记的行为以及任何安全做法或例外，格式化和 lint 检查留给 CI。

自定义回退文件名

如果你的仓库已经用了别的文件名（如 TEAM_GUIDE.md），把它加进回退列表，Codex 就会把它当作指令文件：

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

重启 Codex 或运行新命令使更新的配置加载。之后 Codex 在每个目录里按这个顺序检查：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md；不在列表里的文件名在指令发现时被忽略。想用不同的配置档案（如项目专用的自动化用户），设置 CODEX_HOME 环境变量：

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

验证

  • 从仓库根运行 codex --ask-for-approval never "Summarize the current instructions."，Codex 应按优先顺序复述全局和项目文件里的指引
  • 用 codex --cd subdir --ask-for-approval never "Show which instruction files are active." 确认嵌套覆盖替换了更宽的规则
  • 想审计 Codex 加载了哪些指令文件，用 codex -c log_dir=./.codex-log 打开可选的纯文本 TUI 日志并查看 ./.codex-log/codex-tui.log，或在启用了会话日志时检查最新的 session-*.jsonl
  • 指令看起来过时：在目标目录里重启 Codex。Codex 每次运行（以及每个 TUI 会话开始时）都会重建指令链，没有缓存要手动清除

排查发现问题

  • 什么都没加载：确认你在预期的仓库里，且 codex status 报告你预期的工作区根；指令文件要有内容，Codex 忽略空文件
  • 出现了错误的指引：在目录树更高处或 Codex 主目录下找 AGENTS.override.md，重命名或移除覆盖文件以回退到常规文件
  • Codex 忽略回退名：确认你在 project_doc_fallback_filenames 里无拼写错误地列出了名字，然后重启 Codex
  • 指令被截断：提高 project_doc_max_bytes，或把大文件拆到嵌套目录里
  • 配置档案混淆：启动 Codex 前运行 echo $CODEX_HOME，非默认值会让 Codex 指向与你编辑的不同的主目录