AGENTS.md 实战手册 2026：从单仓到 monorepo 的完整层级配置

AGENTS.md 实战手册 2026:从单仓到 monorepo 的完整层级配置

作者:CodeGateway 团队 · 实测于 2026-05-26

TL;DR:AGENTS.md 是 Codex CLI 学会你项目的方式 —— 每次会话开场自带的"系统提示词"。它不是配置文件。Codex 启动时会从全局 ~/.codex/AGENTS.md 一路扫到当前目录,把路径上每一份 AGENTS.md 拼起来,默认上限 32 KiB,越靠近你 cwd 的优先级越高。这篇覆盖完整的加载顺序、大部分团队不知道的 AGENTS.override.md 逃生口、三套单仓模板(Next.js / FastAPI / Rust)、monorepo 实战示例、跟 CLAUDE.md、.cursor/rules 横向对比,以及当 api.openai.com 返回 451 区域不可达时怎么走 CodeGateway 接入。

目录

1. AGENTS.md 为什么不是 .codex/config.toml
2. 加载链 —— 精确的查找顺序
3. AGENTS.override.md —— 多数团队不知道的逃生口
4. 单仓模板:Next.js / FastAPI / Rust
5. Monorepo 实战手册
6. AGENTS.md vs CLAUDE.md vs .cursor/rules
7. 子代理 (Subagents) 跟 AGENTS.md
8. AGENTS.md 跟 MCP server 联动
9. 五个常见错误
10. 验证 Codex 实际加载了哪些文件
11. 区域受限接入:Codex CLI 走 CodeGateway
12. 常见问题 FAQ

AGENTS.md 为什么不是 .codex/config.toml

.codex/config.toml 是工具配置 —— 用哪个模型、什么 reasoning effort、哪些 MCP server、哪些 hook。AGENTS.md 是行为指令 —— 提"完成"前必须跑什么测试、用哪个包管理器、哪些目录不要碰、PR review 检查清单。

两者回答不同问题。config 告诉 Codex 怎么跑,AGENTS.md 告诉 Codex 团队怎么协作。实战里后者贡献了 80% 的 agent 质量差距,因为这是唯一跨模型升级仍有效的旋钮 —— 下个月 GPT-5.5 升级,你的 AGENTS.md 仍然适用;你那些精心调过的 prompt 模式可能就不灵了。

OpenAI 官方文档:"Codex reads AGENTS.md (and related files) and includes a limited amount of project guidance in the first turn of a session." —— AGENTS.md 直接拼进每次会话的第一条消息,在用户 prompt 之前。

加载链 —— 精确的查找顺序

Codex CLI 的指令链每次会话启动时构建一次(不是 lazy 加载,跨会话不缓存)。顺序如下:

1. 全局层(默认 ~/.codex/,或 CODEX_HOME 指向的目录):
   - AGENTS.override.md     ← 存在则只用这个
   - AGENTS.md              ← 仅当 override 不存在时

2. 项目层 —— 从 git root 一路 down 到当前目录,
   路径上每个目录依次检查:
   - AGENTS.override.md
   - AGENTS.md
   - project_doc_fallback_filenames 里列的文件
   - 每个目录最多取一份。

3. 如果找不到 project root,只查当前目录。

选中的文件按 root-first、leaf-last 顺序拼接,中间空行分隔。"靠近当前目录的文件因为出现在合并 prompt 的后面,会覆盖前面的指令。"

两个最常踩的坑:

• 近的赢。 仓库根写"用 pnpm",packages/legacy-yarn/AGENTS.md 写"用 yarn",那么 Codex 在这个子目录里就跟 yarn。要主动用这个机制,不要被它意外咬。
• 32 KiB 上限是真的。 project_doc_max_bytes 默认 32 KiB,Codex 按加载顺序拼,到上限就停。全局文件塞了 28 KiB 风格指南,后面仓库特定的指令就被挤出去了 —— 这是隐性失败,日志不会报错。

默认 project root 是"最近一级含 .git 的祖先目录"。如果你的仓库不用 git,可以在 ~/.codex/config.toml 配 project_root_markers 改这个判定。

AGENTS.override.md —— 多数团队不知道的逃生口

每一层(全局 / 仓库 / 子目录)Codex 都会先查 AGENTS.override.md,再查 AGENTS.md。同一层两个都在,override 赢,`AGENTS.md` 被忽略。

这是个团队级配置的好工具,让你不用 fork 一份 commit 进仓库的文件就能本地调:

• 提交到仓库:AGENTS.md。所有人 clone 都拿到。
• 每个 dev(或每个分支)在 .gitignore 里加 .codex/AGENTS.override.md,本地放个人偏好,不会扰动提交的版本。
• 临时工作 —— 安全演练、性能 benchmark —— 在工作目录扔个 AGENTS.override.md,跑完 Codex 删掉。不 commit、不会污染主文件。

推荐工作流:

• 提交:AGENTS.md 放仓库根,每个有意义的子包再放一份。
• 不提交:任何 AGENTS.override.md。.gitignore 加 AGENTS.override.md 和 **/AGENTS.override.md。

单仓模板:Next.js / FastAPI / Rust

一份有用的 AGENTS.md 写意图和约束,不写 Codex 自己能发现的命令。每段控制在 5-15 行,整文件目标 1-3 KiB。

Next.js + TypeScript + Vitest

# 仓库说明

这是 Next.js 15 App Router 项目,TypeScript + Tailwind + Vitest。

## 约定
- 组件 PascalCase,在 `components/` 下;hook `useFoo`,在 `hooks/` 下。
- Server Action 放 `app/actions/`,绝不在 useEffect 里调。
- 任何边界校验(表单、API 入参、env 解析)走 Zod。

## 测试纪律
- 提"完成"前必须:`pnpm typecheck && pnpm test --run`。
- 新工具函数要伴生 `*.test.ts`。带逻辑的 UI 改动要 Vitest 测试,
  不接受单纯 snapshot。

## 不要做的事
- 不要引新的 state-management 库;Zustand 是仅有的一个。
- ESLint disable 必须带说明为什么的注释。
- `src/generated/` 不能改 —— 每次 build 从 OpenAPI 自动生成。

FastAPI + SQLAlchemy + pytest

# 仓库说明

FastAPI 服务,Postgres 通过 SQLAlchemy 2.0 async,Python 3.12。

## 约定
- 路由在 `app/api/v1/`,业务逻辑在 `app/services/`,DB model 在
  `app/db/models.py`。路由要瘦:解析、调 service、返回。
- 所有公开端点必须有 Pydantic response_model。
- Schema 改动走 Alembic。dev 环境也不许手改库。

## 测试纪律
- 提"完成"前跑 `uv run pytest -q`。
- 新端点至少要一个 TestClient 写的集成测试。
- 测试里要 mock 模型 provider,绝不在测试中真调 LLM。

## 性能预算
- 单请求 p95 < 300 ms(开发机)。
- 任何动 `orders` 表的新查询,PR 描述里附 SQLAlchemy explain() 结果。

Rust + cargo workspace

# 仓库说明

Rust workspace,edition 2024。crate:`core`、`cli`、`server`。

## 约定
- 公开 API 返回 `Result<_, ServiceError>` —— `main.rs` 外不许用
  `anyhow::Result`。
- 用 `tracing`(不用 `log`),传 structured field,不用拼字符串。
- 所有 `unsafe` 块必须有 `// SAFETY:` 注释。

## 测试纪律
- 任何 commit 前 `cargo nextest run --workspace` 必须过。
- 公开 API 改动要附 doctest 演示新形状。
- 解析代码用 property test,其它用单元测试。

## 不要做的事
- 加新依赖时 PR 描述要标注体积影响。
- `crates/legacy/` 除非明确要求,不要碰 —— 计划删的。

这些模板故意写得短。再加一份全局 ~/.codex/AGENTS.md 和三份嵌套子包文件,32 KiB 上限很快就到。

Monorepo 实战手册

monorepo 里,加载链会组合 —— 这正是它的设计意图。共性规则放根,特定规则放专属位置。

repo-root/
├── AGENTS.md                  # 通用:PR 规范、安全规则
├── apps/
│   ├── web/
│   │   └── AGENTS.md          # Next.js 约定
│   └── api/
│       └── AGENTS.md          # FastAPI 约定
├── packages/
│   ├── ui/
│   │   └── AGENTS.md          # 设计系统规则
│   └── shared-types/
│       └── AGENTS.md          # type-gen 流程
└── infra/
    └── AGENTS.md              # Terraform 风格、密钥处理

你 cd apps/web/components 时,Codex 拼出来的合并 prompt 是:

~/.codex/AGENTS.md
   ↓ (拼接,空行分隔)
repo-root/AGENTS.md
   ↓
apps/web/AGENTS.md

apps/api/AGENTS.md 和 packages/ui/AGENTS.md 不会加载 —— 它们不在你 cwd 的路径上。这是设计目的:只有相关上下文进来,token 预算就够用。

根里放什么:

• PR 标题规范、commit message 格式、签名规则
• 安全规则:代码里不准有密钥、日志脱敏清单、依赖政策
• "main 分支严禁直接 push" / 分支策略
• 跨包契约:共享 type、RPC schema、错误码

每个子包放什么:

• 该子树的语言/框架约定
• 该 stack 的测试纪律
• 本地"别碰"清单(vendor 代码、生成文件)

AGENTS.md vs CLAUDE.md vs .cursor/rules

三家 coding agent 用不同的文件名表达同一个概念。实操不能互换 —— 各家只读自己那个文件名 —— 但 内容纪律完全可迁移。

同一仓库要同时跑多个 agent,务实的做法是单 source of truth(比如 .agent-rules.md),在 .git/hooks/post-checkout 里跑个小脚本,symlink 到 AGENTS.md、CLAUDE.md 和 .cursor/rules/*.mdc。分叉的副本第一周就开始烂。

子代理 (Subagents) 跟 AGENTS.md

Codex 子代理需要明确触发("Codex doesn't spawn subagents automatically")。子代理跑在独立线程里,用 /agent 切换/查看。官方 Subagents 文档目前没明确说子代理是否看跟父代理同一份 AGENTS.md 链 —— 最安全的假设是继承父级 context,但安全相关的约束依赖这个之前要验证。

明确文档过的:

• 子代理行为通过父级 prompt 指引("A good subagent prompt should explain how to divide the work…"),也可以在 agent 文件里配 model、model_reasoning_effort。
• 子代理返回摘要而非原始工作输出,保持主线程聚焦。

实战建议:子代理必须遵守的约束(日志里不能有 PII、不许 git push --force 等),写在父级 AGENTS.md 里 + 写在子代理任务 prompt 里。两条腿走路 —— 官方文档对继承模型的表述还有变化空间。

AGENTS.md 跟 MCP server 联动

AGENTS.md 是教 Codex 该用哪个 MCP tool 的地方。MCP server 在 .codex/config.toml 里配,AGENTS.md 告诉 Codex 什么时候用。

一个挂了 Postgres 只读 MCP 和 GitHub MCP 的仓库,AGENTS.md 可以这样写:

## 你有的工具

有个 MCP server `postgres-readonly`,提供 `query(sql)` 工具访问 dev 数据库。
查 schema 用它,不要猜。绝对不要用它跑写操作。

有个 MCP server `github` 做 PR 和 issue 操作。读 PR 评论、看 check 状态
都通过它,不要让用户复制粘贴。

## 工具使用规则
- 问 schema 的事,先通过 postgres MCP 查 `information_schema`。
- 处理 PR 三连(triage),先用 github MCP 拉取 PR,总结 check 失败,再提方案。
- 不许通过 postgres MCP 跑写 SQL。把语句拷给用户让他自己跑。

两个 MCP server + 四行指令,agent 在 schema 类问题上就从"找用户问"变成"自己查"。这是生产 AGENTS.md 里杠杆最高的一段。

五个常见错误

1. 写命令而非意图。 "跑 pnpm test" 改 script 就烂;"提交前跑测试套件"不会烂。

1. 全局文件塞太满。 全局 ~/.codex/AGENTS.md 写 28 KiB 风格指南,后面仓库特定的指令在 32 KiB 上限下被挤掉。全局控制在 ≤ 5 KiB。

1. 忘了把 override 加 `.gitignore`。 AGENTS.override.md 是个人/分支局部用的。commit 进去意味着所有 contributor 都跟着你的私货,惊喜了所有人。

1. 嵌套 AGENTS.md 没控好 scope。 packages/ui/AGENTS.md 写后端规则,Codex 在 packages/ui/ 里帮你时会加载 —— 然后被这些不相关的规则带偏。每个文件只写它所在目录的事。

1. 不验证。 跑几个月后,几乎每个团队都至少有一份 AGENTS.md 因为优先级问题或 fallback 配错没被加载。每季度验证一次(见下一节)。

验证 Codex 实际加载了哪些文件

最简单:直接问 Codex 自己。

列出当前会话激活的指令文件,按加载顺序排。

模型会读自己第一回合的 context 列出来。跟日志交叉验证:

tail -F ~/.codex/log/codex-tui.log
# 或
ls -t ~/.codex/log/session-*.jsonl | head -1 | xargs head -200

如果你把 project_doc_max_bytes 调高过 32 KiB,下次启动后看日志 —— 官方说 Codex 到上限就停,你那些嵌套覆盖可能被静默丢掉。

区域受限接入:Codex CLI 走 CodeGateway

如果你在公司代理后面、或者所在区域 api.openai.com 返回 451 "unsupported region",Codex CLI 可以指向 CodeGateway —— OpenAI 兼容的接入层。两行 shell 配置:

export OPENAI_BASE_URL=https://api.codegateway.dev/v1
export OPENAI_API_KEY=cg-...   # 从 CodeGateway dashboard 拿
codex login --skip  # 跳过 OAuth,直接用 key
codex

你的 AGENTS.md 完全不需要改 —— 同样的指令、同样的链、同样的 32 KiB 上限。CodeGateway 转发 Responses API 调用到 OpenAI;模型选择器、子代理、MCP、hooks 行为完全一样。计费跟直连 OpenAI 一样按 token,加一层透明阶梯倍率;价格参考 codegateway.dev/pricing。

团队场景:每个开发者用自己的 key 登录,网关聚合账单,你一个 dashboard 看全队用量,不用自己搭代理。

常见问题 FAQ

Q：会话中途改了 AGENTS.md，Codex 会重新读吗？不会。Codex 在会话启动时构建一次指令链，中途不会重读。新的一次运行（或新会话）会重建整条链，所以重启 Codex 才能加载你的改动。没有需要手动清的缓存。

Q:不在 git 仓库里时 AGENTS.md 怎么处理? "If no project root is found, Codex only checks the current directory." 还能拿到全局文件 + cwd 的 AGENTS.md,但没有完整链。

Q:能不能把 `AGENTS.md` 改成团队已经用的别的名字(如 `AGENT_RULES.md`)? 可以 —— 在 ~/.codex/config.toml 加 project_doc_fallback_filenames。Codex 在每个目录先查 AGENTS.override.md、再查 AGENTS.md、再查 fallback 列表。

Q:指令集超过 50 KiB,怎么拆才不撞上限? 官方建议"提高上限或者拆到嵌套目录"。把 project_doc_max_bytes 调到 65536(64 KiB)是省事的方案;按目录拆是更可持续的 —— 嵌套文件只在你工作在该子树时加载,不撑总链。

Q:AGENTS.md 是不是自动可信? Advanced Configuration 那篇文档没说 AGENTS.md 是不是被项目 trust 机制门控(.codex/config.toml 是有的)。假设它不是,但你不写的 AGENTS.md 都当不信任代码看,让 Codex 跟着跑之前先自己读一遍。

Q:该用 AGENTS.md 还是在对话里给系统指令? 两个都用,目的不同。AGENTS.md 是长期约束,对话指令是本次任务的覆盖。后者本回合压制前者,但不持久化。

资源

• Codex 模型参考
• AGENTS.md 官方指南
• Codex CLI 功能官方文档
• Codex 子代理官方文档
• CodeGateway 文档

• Codex 配置参考（project_doc_max_bytes）

相关阅读：CodeGateway 指南

• OpenAI Codex CLI 2026 完整教程

• Claude Code 全自动模式：权限模式与 CI/CD 实战

• 多模型按量计费 API 价格

• Claude Code 连接超时排查（5 分钟稳定接入）