AGENTS.md 是 Codex 每次工作前都会自动读取的项目指令文件，类似写给 AI 的 README。最常见的写法是：全局个人习惯放 ~/.codex/AGENTS.md，项目规则放仓库根目录 AGENTS.md，子目录规则按目录层级追加。本文先回答 AGENTS.md 应该写什么、放哪里、会不会每次加载，再说明发现机制、配置示例、fallback 文件名和常见排错。

Codex AGENTS.md 完整指南 #

Codex 在每次启动时（TUI 每次启动一次会话）读取 AGENTS.md 文件，构建一个指令链，在开始任何工作之前先加载这些指导。

如果你从搜索结果进来，先看这张表：

最小可用模板 #

# AGENTS.md

## 项目约定

- 使用 bun 安装依赖，不要改用 npm 或 pnpm
- 修改文档后运行 `bun run docs:build`
- 不要读取或提交 `.env`、凭证文件、生成目录

## 工作方式

- 开始前先确认需求边界
- 每次只改和当前任务直接相关的文件
- 完成前说明验证命令和结果

这个模板只写 Codex 每次开工前必须知道的约定。更多背景、设计文档、长篇 API 说明，应放在普通文档里，需要时再让 Codex 读取。

Codex 如何发现 AGENTS.md #

Codex 按以下优先级顺序构建指令链：

1. 全局级：读取 ~/.codex/（除非设置了 CODEX_HOME 环境变量）目录下的 AGENTS.override.md，如果不存在则读取 AGENTS.md。同一层级只用第一个非空文件。

2. 项目级：从项目根目录（通常是 Git 根目录）开始，逐层向下走到当前工作目录。每个目录里依次检查 AGENTS.override.md、AGENTS.md，以及 project_doc_fallback_filenames 里配置的 fallback 文件名。每个目录最多包含一个文件。

3. 合并顺序：从根目录向下拼接文件，用空行分隔。靠近当前工作目录的文件出现在后面，优先级更高（因为它们在组合 Prompt 里位置靠后）。

大小限制：Codex 跳过空文件，组合大小达到 project_doc_max_bytes（默认 32 KiB）后停止加载。超过限制时可以提高阈值或把指令分散到子目录里。

AGENTS.md 应该写什么 #

AGENTS.md 不是越长越好。它应该写 Codex 做事前必须知道的规则，而不是把所有项目文档复制进去。

适合写进去的内容：

• 项目使用的包管理器、测试命令、构建命令。
• 修改代码后必须执行的验证步骤。
• 不能触碰的目录、密钥、生成文件或外部系统。
• 团队约定的代码风格和提交前检查。
• 特定子目录的例外规则，例如后端、前端、脚本目录各自的验证命令。

不适合写进去的内容：

• 大段产品背景、历史会议纪要、完整 API 文档。
• 会频繁变化的临时任务列表。
• 密钥、账号、Token 或只能给人看的内部凭证。
• 可以通过命令自动发现的信息，例如完整文件树。

一个实用模板：

# AGENTS.md

## 项目约定

- 使用 pnpm 安装依赖，不要改用 npm 或 yarn
- 修改 TypeScript 后运行 pnpm test 和 pnpm lint
- 不要提交 .env、dist/、coverage/ 目录

## 验证方式

- 单元测试：pnpm test
- 构建验证：pnpm build

创建全局指导 #

在 ~/.codex/AGENTS.md 里写个人默认值，让所有仓库都继承你的工作习惯：

mkdir -p ~/.codex

# ~/.codex/AGENTS.md

## 工作约定

- 修改 JavaScript 文件后必须运行 `npm test`
- 安装依赖时优先用 `pnpm`
- 添加新的生产依赖前先询问确认

验证是否生效：

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

Codex 会在提出建议之前先引用 ~/.codex/AGENTS.md 里的内容。

如果需要临时覆盖全局配置而不删除原文件，可以创建 ~/.codex/AGENTS.override.md。删除这个 override 文件就恢复原有全局指导。

分层管理项目规则 #

仓库级文件负责项目规范，在继承全局默认值的同时覆盖特定规则：

1. 仓库根目录创建基础 AGENTS.md：

# AGENTS.md

## 仓库规范

- 提 PR 前运行 `npm run lint`
- 改动行为时在 `docs/` 里更新对应公共函数的文档

2. 在需要特殊规则的子目录创建 AGENTS.override.md，比如 services/payments/：

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 而不是 `npm test`
- 轮换 API key 前必须通知安全频道

3. 从子目录启动 Codex，确认加载顺序：

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

预期结果：Codex 先报告全局文件，再是仓库根目录 AGENTS.md，最后是 payments 目录的 override。

目录结构示例 #

AGENTS.md                    # 仓库规范（高亮）
services/
  payments/
    AGENTS.md                # 被忽略（因为 override 存在）
    AGENTS.override.md       # 支付服务规则（高亮）
    README.md
  search/
    AGENTS.md

.codex/AGENTS.md 应该写什么 #

搜索里经常出现“项目文件下的 .codex/AGENTS.md 应该写什么”。可以这样理解：

• ~/.codex/AGENTS.md：你的个人默认工作习惯。
• 仓库根目录 AGENTS.md：这个项目希望所有协作者都遵守的规则。
• 子目录 AGENTS.md 或 AGENTS.override.md：只对某个模块生效的局部规则。
• .codex/ 目录更适合放 Codex 自己的配置、脚本或全局配置目录，不建议把“项目共享规则”藏在普通协作者不容易发现的位置。

如果规则是给整个仓库看的，优先放项目根目录 AGENTS.md。如果规则只给你自己的 Codex profile 使用，才考虑放到 CODEX_HOME 指向的 .codex/ 目录。

配置 fallback 文件名 #

如果你的仓库已经用了其他文件名（比如 TEAM_GUIDE.md），可以把它加入 fallback 列表，Codex 会把它当作指令文件处理：

# ~/.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。不在这个列表里的文件名会被忽略。

使用自定义 CODEX_HOME #

如果需要不同的配置 Profile（比如自动化用户），可以设置 CODEX_HOME 环境变量：

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

多任务协作规则 #

如果你会让多个 Codex 会话同时处理同一个项目，AGENTS.md 里要写清楚“边界”，而不是只写风格偏好。

适合加入这些规则：

• 每个任务必须在独立 branch 或 worktree 中进行。
• 开始前先运行 git status，发现已有未提交改动时不要覆盖。
• 只修改任务指定目录；跨目录修改前先说明原因。
• 不要重命名共享配置、生成文件或锁文件，除非任务明确要求。
• 完成后报告实际改过的文件和验证命令。

不建议写“所有问题都自动修好”这类宽泛要求。多代理协作最怕互相踩文件，AGENTS.md 应该先约束文件边界和验证边界。

相关配置入口 #

AGENTS.md 负责“告诉 Codex 怎么做事”，但不是所有配置都应该写在 AGENTS.md 里。

验证配置 #

# 从仓库根目录确认全局和项目文件都正确加载
codex --ask-for-approval never "Summarize the current instructions."

# 确认子目录 override 覆盖了上层规则
codex --cd subdir --ask-for-approval never "Show which instruction files are active."

如果需要审计 Codex 加载了哪些指令文件，查看 ~/.codex/log/codex-tui.log 或最近的 session-*.jsonl 文件。

指令看起来没更新？重启 Codex 在目标目录里即可——Codex 每次运行都会重新构建指令链，没有缓存需要清理。

AGENTS.md / CLAUDE.md / GEMINI.md 对比 #

如果你的团队同时使用多个 AI 编程工具，可以保留一份短的共享原则，再分别写到这些工具各自识别的文件里。不要用一个工具的文件名假设另一个工具会自动读取。

继续阅读：

• Claude Code 的 CLAUDE.md 指南
• Gemini CLI 的 GEMINI.md 指南

常见问题排查 #

常见问题 #

Q: AGENTS.md 和 AGENTS.override.md 的区别是什么？

A: 两个文件名在语义上是一样的——都会被加载为指令文件。唯一的区别是：当同一目录下两个文件都存在时，Codex 只读 AGENTS.override.md，忽略 AGENTS.md。这让你可以创建临时 override 而不用修改原文件，删除 override 就自动回退。

Q: 多个 AGENTS.md 的优先级是怎么计算的？

A: 靠近当前工作目录的文件优先级更高（出现在组合 Prompt 的后面）。所以子目录里的规则会覆盖仓库根目录的规则，仓库规则又覆盖全局规则。

Q: AGENTS.md 写多长合适，会影响 token 用量吗？

A: 会。AGENTS.md 的内容会出现在每次对话的上下文里，内容越长 token 消耗越多。建议只写关键规则，把大量文档放到 references 目录里按需引用，而不是全部塞进 AGENTS.md。

Q: Codex 在项目文件下的 .codex/AGENTS.md 应该写什么？

A: 如果这是团队共享的项目规则，优先写在仓库根目录 AGENTS.md，不要藏在 .codex/ 里。如果 .codex/ 是你通过 CODEX_HOME 指定的个人配置目录，可以写你的个人 Codex 默认规则，例如默认测试命令、审批习惯、常用工具偏好。

Q: AGENTS.md 能配置 Codex 权限吗？

A: 不建议把权限当成自然语言规则写进 AGENTS.md。AGENTS.md 可以提醒“修改依赖前先询问”，但真正的模型、sandbox、approval 和权限控制应该放到 Codex 配置中，继续看配置参考。

Q: 我已经有 CLAUDE.md，还需要 AGENTS.md 吗？

A: 如果团队同时使用 Codex 和 Claude Code，建议两份都保留。可以复用同一套工程原则，但要分别写成 Codex 能读取的 AGENTS.md 和 Claude Code 能读取的 CLAUDE.md。

Q: Codex 会每次都加载 AGENTS.md 吗？对话长了感觉没遵守规则怎么办？

A: 新会话会重新构建指令链。长对话里“感觉没遵守”通常不是文件没加载，而是上下文太长、任务边界太散或 AGENTS.md 写得太长。更稳的做法是缩短规则、重开聚焦会话，并把模块专属规则放到对应子目录。

Q: Codex 如何同时处理一个项目的多个编程任务？

A: 用独立 branch 或 worktree 隔离任务，并在 AGENTS.md 里明确“不要覆盖已有未提交改动”“只改任务指定目录”“完成前报告验证命令”。任务之间共享的接口或配置，需要先人工确认边界。

Q: Codex 安装 Superpowers 后，AGENTS.md 还重要吗？

A: 重要。Superpowers 负责通用工作流程，AGENTS.md 负责当前项目的具体约定。两者互补：一个管“怎么工作”，一个管“这个仓库有什么规矩”。安装方式见 Superpowers 安装指南。