第 11 卷
override机制：临时覆盖不删原文件
每一层都优先找 AGENTS.override.md。用得上它的场景是这样的：你的团队维护了一份 AGENTS.md 并check进
了git，大家共享。但你个人有些不同的偏好，比如你喜欢用 pnpm 而团队规范用 npm。这时候你不需要修改团队文件，只要在同一目录放一个 AGENTS.override.md，它会直接替代同级的 AGENTS.md。
把override文件加到 .gitignore 里，团队的基础规范不受影响，个人偏好也保住了。
同样的逻辑也适用于全局级。 ~/.codex/AGENTS.override.md 会临时替代 ~/.codex/AGENTS.md，删掉 override文件就恢复原来的全局设置。适合做短期实验。
/init：快速生成初始AGENTS.md
不想从零开始写？在Codex里输入 /init 命令，它会分析你的项目结构，自动生成一份初始的AGENTS.md。
生成的内容通常包括：项目使用的语言和框架、检测到的构建和测试命令、目录结构概述。你在此基础上增删修改，比从空白文件开始快得多。桌面App里也能用 /init。
桌面App支持一个项目挂多个文件夹，这时只有你选定的主文件夹会用来找AGENTS.md、skills和 config.toml，其他文件夹里的AGENTS.md不会被读。
一份好的AGENTS.md该写什么
判断标准跟Claude Code的CLAUDE.md完全一致：AI自己能从代码里推断出来的，不要写；AI猜不到的，必须
写。
该写不该写
| 构建、测试、lint命令 | 「这是一个Python项目」（AI看文件就知道） |
|---|---|
| 与默认不同的代码风格偏好 | 语言标准规范（AI已经掌握） |
| 项目架构决策和技术选型 | 详细API文档（给路径，别全文粘贴） |
| 开发环境的坑和特殊配置 | 频繁变化的信息（每次都得改的不适合放这里） |
| PR要求和代码审查标准 | 文件逐一描述（AI会自己看文件树） |
| 什么叫「完成」的定义 | 「写整洁代码」「遵循最佳实践」这种废话 |
| 约束和禁止事项（带替代方案） | 所有人都知道的常识 |
看一个实际的项目AGENTS.md示例：
# MyProject
-# 仓库结构
- src/主代码
- tests/测试文件
- scripts/构建和部署脚本
-# 开发命令
- 安装依赖：pnpm install
- 跑测试：pnpm test（所有测试必须通过再提PR）
- Lint检查：pnpm lint
- 构建：pnpm build
-# 工程规范
- 使用TypeScript strict模式
- 组件用函数式，不用class
- 新增API接口必须写单元测试
- commit message遵循Conventional Commits格式
-# PR要求
- 标题清晰描述改动内容
- 修改了用户可见行为时必须更新文档
- CI通过后才能合并
-# 禁止
- 不要直接修改 generated/ 目录下的文件（它们是自动生成的）
- 不要在代码中硬编码API密钥，用环境变量
- 不要跳过lint检查
不到200字。但每一行都在帮Codex避免犯错。「什么叫完成」写清楚了（CI通过+文档更新），「禁止」项带着原因（generated目录是自动生成的），这些是Codex自己读代码推断不出来的信息。
Fallback文件名
如果你的项目已经有一个叫 TEAM_GUIDE.md 或者 .agents.md 的文件充当开发规范，不想再多一个 AGENTS.md，可以配置fallback文件名：
# ~/.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。不在列表里的文件名会被忽略。
上面的配置还顺便把合并大小上限调到了64KB，适合规则特别多的大型项目。
和Claude Code的CLAUDE.md对比
如果你同时用Claude Code和Codex，这张对比表会有用：
| 对比维度 | AGENTS.md (Codex) | CLAUDE.md (Claude Code) |
|---|---|---|
| 角色 | 项目指令文件 | 项目指令文件 |
| 全局配置 | ~/.codex/AGENTS.md | ~/.claude/CLAUDE.md |
| 项目配置 | 仓库根目录AGENTS.md | 仓库根目录CLAUDE.md |
| 子目录支持 | ✅从根逐级向下查找 | ✅启动时读当前目录及上层；子目录的在读写那个目录的文件时按需 |
加载
override机制✅❌ 无此机制 AGENTS.override.md
Fallback文件✅ 可配置2.1.277起，路径上没有CLAUDE.md时读AGENTS.md 名
| 大小限制 | 默认32KB，可调 | 官方建议200行以内，超过4 MiB的文件会被跳过 |
|---|---|---|
| 引用其他文件 | 不支持@语法 | 支持@语法导入 |
| 快速生成 | /init命令 | /init命令 |
核心思路一样，细节上各有取舍。Codex的override机制对团队协作更友好，Claude Code的@语法在大型项目中组织规则更灵活。两边一起用的话，现在可以只维护一份AGENTS.md，但注意Claude Code那条「路径上只要有CLAUDE.md就不读AGENTS.md」的规则，附录C有具体做法。
更广一点的趋势：SKILL.md已经成了几家agent共用的格式，Codex、Claude Code、Cursor、Gemini CLI都
认。你写一个skill不再绑死某个工具，今天给Codex用、明天复制到Claude Code也能跑。
验证你的配置
写完AGENTS.md后，怎么确认Codex确实读到了？最直接的是会话里输入 /status，有一行 Agents.md:，列
出这次读到的所有AGENTS.md。§03的截图里这一行是 ~/.codex/AGENTS.md, AGENTS.md，全局一份、项目一份。
想看它理解成了什么，直接问：