AGENTS.md 写法要点

AGENTS.md 是放在仓库里的“给智能体的项目说明书”。Codex 在开始工作前会自动读取它，把其中的约定作为上下文。写得好，能显著减少重复解释；写得太长或太散，反而会挤占上下文。

本文依据当前公开源码整理加载规则与写作建议。

加载顺序

  1. 用户级指令：$CODEX_HOME/AGENTS.md（默认即 ~/.codex/AGENTS.md）。同一目录下若有 AGENTS.override.md，优先使用覆盖文件。
  2. 项目级指令：从项目根目录到当前工作目录，逐层查找。每一层先看 AGENTS.override.md，再看 AGENTS.md，命中一个就停止该层。
  3. 项目根目录：从当前目录向上查找，直到遇到 project_root_markers 指定的标记；未配置时默认使用 .git。不会越过项目根目录继续向上；把该配置设为空数组会禁用向上查找。
  4. 没有标记时：只考虑当前工作目录。
  5. 合并方式：按“从根到当前目录”的顺序拼接，总大小受 project_doc_max_bytes 限制，默认 32768 字节（32 KiB）。

如果项目被标记为不可信，项目级指令不会被加载，只保留用户级指令。这一点在打开陌生仓库时尤其值得注意。

应该写什么

优先写“每次都需要知道、且不容易从代码里一眼看出”的信息：

  • 构建、测试、格式化的确切命令，包括工作目录和常用参数。
  • 目录与模块地图：哪一层负责什么，改动某类需求通常从哪几个文件入手。
  • 项目特有的约定：命名、错误处理、日志、提交信息、分支策略。
  • 边界与禁区：不能改的生成目录、不能提交的文件、需要先确认的迁移操作。
  • 验证方式：改完后跑什么、看到什么才算成功。

不应该写什么

  • 密钥、令牌、内部地址等敏感信息。
  • 大段教程或复制来的外部文档；这些内容会长期占用上下文。
  • 容易过期的细节，例如某个依赖的临时版本号。
  • 互相冲突的规则。模型无法判断哪条优先，最终行为会不稳定。
  • 与代码无关的个人偏好堆砌。把“必须遵守”和“最好这样”分开写，效果更好。

一个可用的骨架

# 项目约定

## 构建与测试
- 安装依赖：`pnpm install`
- 本地开发：`pnpm dev`
- 运行测试：`pnpm test`
- 提交前检查：`pnpm lint && pnpm typecheck`

## 目录地图
- `apps/web`：前端应用，入口在 `apps/web/src/main.tsx`
- `services/api`：HTTP API，路由在 `services/api/src/routes/`
- `packages/shared`：前后端共享类型，修改后需要重新生成客户端

## 代码约定
- 新增接口必须同时补单元测试与 OpenAPI 描述。
- 错误统一使用 `AppError`，不要直接抛字符串。
- 日志使用 `logger`，不要用 `console.log`。

## 边界
- 不要修改 `vendor/` 与任何生成文件。
- 不要提交 `.env*`、证书或本地数据库文件。
- 数据库迁移先说明方案，再执行。

## 验证
- 单测：`pnpm test -- --runInBand`
- 端到端：`pnpm test:e2e`（需要本地数据库）

分层放置

大型仓库不必把所有内容塞进根目录的一个文件。可以按子项目拆分：

repo/
  AGENTS.md                  # 全局约定：构建、测试、目录地图
  services/api/AGENTS.md     # API 子项目约定
  services/api/AGENTS.override.md  # 当前任务的临时覆盖（优先）
  apps/web/AGENTS.md         # 前端子项目约定

在 services/api 下工作时，Codex 会读取根目录与 services/api 两级的指令；层级越深，越接近当前任务。AGENTS.override.md 适合放临时调整，但不要长期保留与主文件冲突的内容。

生成与维护

  • 在 TUI 中输入 /init，可以让 Codex 根据仓库现状生成一个初始 AGENTS.md。
  • 仓库结构或命令变化后，同步更新对应条目；过时的指令比没有指令更危险。
  • 如果团队使用其他文件名，可通过 project_doc_fallback_filenames 配置有序的回退文件名列表。
  • 文件变长后，优先删减“模型已经能从代码里推断”的内容，而不是继续追加。

延伸阅读