发布日期:2026-08-10|适用范围:Codex CLI、Codex 桌面端与 Codex Code Review
Codex AGENTS.md 是 OpenAI Codex 在执行任务前读取的项目指令文件,用于声明构建命令、测试要求、代码规范、安全边界和审查规则。Codex 会在每次运行开始时,从全局目录、项目根目录一路读取到当前工作目录,并让距离当前目录更近的规则覆盖上层规则。本文依据 OpenAI 2026 年官方文档,给出可直接使用的模板、Monorepo 分层方法、Code Review 配置和故障排查流程。

AGENTS.md 是什么?
AGENTS.md 是写给编码 Agent 的项目说明书,作用类似面向 AI 的 README。 它使用普通 Markdown,没有强制字段,可记录安装、构建、测试、代码风格、目录边界和 Pull Request 要求。
AGENTS.md 开放格式官网显示,截至 2026 年已有超过 60,000 个非 Fork、非归档的开源项目使用该文件。该格式由 OpenAI Codex、Google Jules、Cursor、Amp 和 Factory 等工具生态共同采用,并由 Linux Foundation 旗下 Agentic AI Foundation 管理。
与 README.md 相比,两者适合承载的内容不同:
| 文件 | 主要读者 | 适合内容 |
|---|---|---|
README.md | 开发者和用户 | 项目介绍、快速开始、公开接口 |
CONTRIBUTING.md | 代码贡献者 | 人工协作流程、提交规范 |
AGENTS.md | 编码 Agent | 精确命令、修改边界、测试要求、审查规则 |
Codex 按什么顺序读取 AGENTS.md?
Codex 按“全局规则 → 项目根目录 → 当前工作目录”的顺序合并指令,越靠近目标代码的文件优先级越高。 指令链在每次运行开始时构建一次;在终端界面中,通常意味着每次启动会话读取一次。
读取规则可以概括为三层:
- 全局层:默认检查
~/.codex/AGENTS.override.md,不存在时再读取~/.codex/AGENTS.md,只采用第一个非空文件。 - 项目层:从 Git 项目根目录向当前工作目录逐级查找;每一级依次检查
AGENTS.override.md、AGENTS.md和配置的备用文件名。 - 合并层:从根目录到子目录依次拼接,后出现的具体规则覆盖前面的通用规则。
~/.codex/AGENTS.md # 所有项目的个人默认规则
repo/AGENTS.md # 仓库级规则
repo/apps/web/AGENTS.md # Web 应用规则
repo/apps/web/tests/AGENTS.override.md # 测试目录临时覆盖
同一目录最多读取一个指令文件。如果同时存在 AGENTS.override.md 和 AGENTS.md,前者生效,后者在该目录被忽略。

如何编写一份可执行的 AGENTS.md?
高质量 AGENTS.md 应告诉 Codex“改哪里、怎么验证、哪些事情不能做”,而不是重复通用编程常识。 每条规则最好对应一个可观察的行为或可执行命令。
下面是一份适合 TypeScript 项目的完整模板:
# AGENTS.md
## Project scope
- Application code lives in `src/`; tests live in `tests/`.
- Do not edit generated files under `dist/` or `coverage/`.
- Keep changes limited to the requested feature or bug.
## Setup
- Install dependencies with `pnpm install --frozen-lockfile`.
- Copy `.env.example` to `.env.local`; never commit secrets.
## Development commands
- Run the app: `pnpm dev`.
- Run type checks: `pnpm typecheck`.
- Run lint: `pnpm lint`.
- Run tests: `pnpm test`.
## Code conventions
- Use TypeScript strict mode.
- Reuse existing components and utilities before adding abstractions.
- Keep public API changes backward compatible unless the task says otherwise.
## Testing requirements
- Add or update focused tests for changed behavior.
- Run the narrowest relevant test first, then the full test suite.
- Do not delete failing tests to make CI pass.
## Security boundaries
- Never print or commit credentials, tokens, or customer data.
- Ask before adding a production dependency or changing database schemas.
- Do not run destructive database or Git commands.
## Pull requests
- Summarize behavior changes and verification performed.
- Call out migrations, compatibility risks, and tests not run.
## Code Review Rules
- Flag authentication paths that allow access without an explicit permission check.
Safe path: enforce authorization before loading protected resources.
- Flag database migrations that cannot be rolled back safely.
Safe path: use backward-compatible expand-and-contract migrations.
编写时应优先加入以下五类信息:
- 项目边界和不可修改目录;
- 可复制执行的安装、测试、Lint 和构建命令;
- 仓库特有的架构约束;
- 密钥、数据库和依赖变更等高风险边界;
- 完成任务前必须满足的验收条件。
Monorepo 如何分层配置?
Monorepo 应在根目录保留通用规则,并在包或服务目录放置更具体的 AGENTS.md。 这种结构既减少重复,又能避免前端、后端和基础设施项目互相套用错误命令。
repo/
├── AGENTS.md
├── apps/
│ ├── web/
│ │ └── AGENTS.md
│ └── api/
│ └── AGENTS.md
└── services/
└── payments/
└── AGENTS.override.md
根文件只写全仓通用规则,例如包管理器、禁止提交密钥和统一 PR 要求。apps/web/AGENTS.md 可以指定前端测试命令;services/payments/AGENTS.override.md 则适合声明支付服务的安全审计和专用测试要求。
不要把所有规则塞进根文件。OpenAI 官方文档指出,Codex 默认读取的项目指令总量上限为 32 KiB(2026 年);达到 project_doc_max_bytes 后,后续内容会被截断。
如何配置备用文件名和容量上限?
已有团队规范文件可以通过 project_doc_fallback_filenames 接入,无需立即复制成多份文档。 相关配置写入 ~/.codex/config.toml:
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
保存后应重新启动 Codex。此时每个目录的检查顺序为:
AGENTS.override.mdAGENTS.mdTEAM_GUIDE.md.agents.md
将上限从默认的 32 KiB 调整为 65,536 字节可以容纳更多规则,但更稳妥的做法仍是缩短根规则,并把特定要求下沉到对应目录。
对于需要为不同自动化账号隔离配置的团队,可以设置独立的 CODEX_HOME。例如:
CODEX_HOME="$(pwd)/.codex" codex exec "列出当前生效的指令来源"
AGENTS.md 如何控制 Codex Code Review?
在适用目录的 AGENTS.md 中添加 ## Code Review Rules,Codex 即可按仓库业务约束审查 Pull Request。 OpenAI 2026 年文档说明,GitHub 中的常规 Codex Code Review 默认聚焦 P0 和 P1 高优先级问题。
审查规则应该描述业务后果和安全路径,而不是复制 Lint:
## Code Review Rules
### API compatibility
- Flag removal or renaming of public response fields.
Safe path: keep the old field during a documented deprecation period.
### Data access
- Flag queries that omit tenant isolation.
Safe path: scope every customer query by the authenticated tenant ID.
格式化、导入排序和固定语法检查应交给 CI。AGENTS.md 更适合记录“只有熟悉本仓库的人才知道”的兼容性、权限和数据边界。
团队若需要为 AI 编程实验保存生成的测试附件或评测数据,可以把结果放入对象存储,并在 AGENTS.md 中写明目录、保留周期和脱敏要求。例如七牛云对象存储 Kodo 可作为一种通用制品存储选择,但 AGENTS.md 不应包含任何访问密钥。
如何验证配置是否生效?
验证 AGENTS.md 的可靠方法是让 Codex 列出当前指令来源,并检查它复述的规则顺序。 修改文件后应启动新会话,因为运行中的指令链不会持续重新扫描。
codex --ask-for-approval never "概括当前生效的项目指令"
验证子目录覆盖关系:
codex --cd services/payments \
--ask-for-approval never \
"列出已加载的指令来源,并说明测试命令"
排查时按以下顺序检查:
| 问题 | 常见原因 | 处理方式 |
|---|---|---|
| 完全没有加载 | 文件为空或工作目录错误 | 检查项目根目录和文件内容 |
| 加载了错误规则 | 上层存在 AGENTS.override.md | 从全局目录向下逐级查找 override |
| 备用文件无效 | 文件名未加入配置或有拼写错误 | 修正配置并重启 Codex |
| 后半段规则缺失 | 指令总量达到容量限制 | 精简或拆分嵌套文件 |
| 修改后仍是旧规则 | 当前会话已构建指令链 | 在目标目录启动新会话 |
| 不同账号结果不同 | CODEX_HOME 指向其他目录 | 启动前检查环境变量 |
常见问题
Q:AGENTS.md 必须使用固定字段吗?
不需要。AGENTS.md 是普通 Markdown,没有强制 Schema。建议使用稳定、可扫描的标题组织项目范围、命令、测试、安全边界和 Code Review Rules,避免写成冗长的项目介绍。
Q:AGENTS.md 和 AGENTS.override.md 有什么区别?
同一目录中,Codex 优先读取 AGENTS.override.md,只有它不存在或为空时才读取 AGENTS.md。override 适合临时替换该层规则;长期差异更适合放在对应子目录的普通 AGENTS.md 中。
Q:聊天中的要求和 AGENTS.md 冲突时谁优先?
AGENTS.md 开放格式规范指出,明确的用户聊天指令高于文件规则;在多个 AGENTS.md 之间,距离目标代码更近的规则优先。安全策略、沙箱和平台级限制仍不会被项目文件覆盖。
Q:修改 AGENTS.md 后需要清缓存吗?
不需要手动清缓存,但需要重新启动 Codex 或新建会话。OpenAI 官方文档说明,指令链在每次运行或终端会话开始时重新构建一次。
Q:应该把格式化规则全部写入 AGENTS.md 吗?
不应该。可由格式化器、Lint 或 CI 确定性检查的规则应保留在工具配置中。AGENTS.md 更适合补充执行顺序、业务约束、修改边界和失败后的处理方式。
总结
有效的 AGENTS.md 不以篇幅取胜,而是把项目知识转换为明确边界、可执行命令和可验证结果。OpenAI Codex 官方文档与 AGENTS.md 开放格式规范都强调分层配置:仓库根目录承载通用规则,具体服务在更近的目录覆盖差异。
本文内容基于 OpenAI 与 AGENTS.md 官方网站截至 2026-08-10 的公开资料。Codex 的配置项和产品行为可能更新,建议定期核对官方文档。
参考资料
- OpenAI Custom instructions with AGENTS.md:https://developers.openai.com/codex/agent-configuration/agents-md
- 七牛云Coding Plan:qiniu.com/ai/plan
916



被折叠的 条评论
为什么被折叠?



