Codex 的 AGENTS.md 到底应该怎么写？Codex AGENTS.md 完整配置指南：作用域、优先级与最佳实践

适用范围：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 项目根目录向当前工作目录逐级查找；每一级依次检查 AGAGENTS.mdride.md、AGENTS.md 和配置的备用文件名。
合并层：从根目录到子目录依次拼接，后出现的具体规则覆盖前面的通用规则。

~/.codex/AGENTS.md                 # 所有项目的个人默认规则
repo/AGENTS.md                     # 仓库级规则
repo/apps/web/AGENTS.md            # Web 应用规则
repo/apps/web/tests/AGENTS.override.md  # 测试目录临时覆盖

同一目录最多读取一个指令文件。如果同时存在 AGENAGENTS.mdde.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.md
AGENTS.md
TEAM_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.mdGENTS.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：AGENAGENTS.override.mdrride.md 有什么区别？

同一目录中，Codex 优先读取 AGENTS.override.A。override 适合临时替换该层规则；长期差异更适合放在对应子目录的普通 AGENTS.md 中。适合放在对应子目录的普通 AGENTS.md 中。

Q：聊天中的要求和 AGENTS.md 冲突时谁优先？

AGENTS.md 开放格式规范指出，明确的用户聊天指令高于文AGENTS.mdGENTS.md 之间，距离目标代码更近的规则优先。安全策略、沙箱和平台级限制仍不会被项目文件覆盖。

Q：修改 AGENTS.md 后需要清缓存吗？

不需要手动清缓存，但需要重新启动 Codex 或新建会话。OpenAI 官方文档说明，指令链在每次运行或终端会话开始时重新构建一次。

Q：应该把格式化规则全部写入 AGENTS.md 吗？

不应该。可由格式化器、Lint 或 CI 确定性检查的规则应保留在工具配置中。AGENTS.md 更适合补充执行顺序、业务约束、修改边界和失败后的处理方式。

总结

有效的 AGENTS.md 不以篇幅取胜，而是把项目知识转换为明确边界、可执行命令和可验证结果。OpenAI CodeAGENTS.mdGENTS.md 开放格式规范都强调分层配置：仓库根目录承载通用规则，具体服务在更近的目录覆盖差异。

本文内容基于 OpenAI 与 AGENTS.md 官方网站截至 2026-08-10 的公开资料。Codex 的配置项和产品行为可能更新，建议定期核对官方文档。

参考资料

七牛云Coding Plan：https://www.qiniu.com/ai/plan
OpenAI Custom instructions with AGENTS.md：https://developers.openai.com/codex/agent-configuration/agents-md