别再重复告诉 Codex“项目怎么跑”：用 AGENTS.md 固化仓库规则

每次新建对话，Codex 都会进入一个新的上下文。

它不会天然知道：

项目用什么命令安装、测试和构建；
哪些目录是生成物，不能手动修改；
数据库迁移需要什么审批；
团队使用什么代码风格；
完成任务后应该怎样汇报。

如果这些信息只存在于某个人的经验里，Codex 每次都只能重新探索。AGENTS.md 就是为了解决这个问题而存在的。

AGENTS.md 是写给 Agent 的 README

README 主要告诉人类项目是什么、怎样开始；AGENTS.md 则告诉 Codex 和其他 coding agent，在这个项目里工作时应该遵守什么规则。

它本质上只是一份 Markdown 文件，最常见的位置是仓库根目录：

my-project/
├── AGENTS.md
├── package.json
├── src/
└── tests/

适合写入其中的内容包括：

项目结构和关键入口；
安装、开发、测试、构建命令；
代码风格和目录边界；
禁止事项与安全红线；
交付与验证要求。

全局规则、项目规则和子目录规则

规则可以分层组织：

~/.codex/AGENTS.md            # 个人全局规则
project/AGENTS.md             # 当前仓库规则
project/apps/web/AGENTS.md    # 前端子目录规则
project/packages/db/AGENTS.md # 数据库子目录规则

Codex 通常先读取全局规则，再从 Git 根目录一路读取到当前工作目录。越靠近当前目录的规则越具体。

同一目录里，AGENTS.override.md 可以覆盖 AGENTS.md，适合临时调整。但覆盖文件如果只对个人有效，通常不应该提交到团队仓库。

这种分层方式尤其适合 monorepo：

团队规则和个人偏好要分开

团队共享内容适合进入版本控制：

项目命令；
目录说明；
测试要求；
安全边界；
PR 交付标准。

个人本机路径、编辑器习惯、私有工具和临时限制，不适合污染团队规则。

如果使用 AGENTS.local.md 保存个人偏好，需要注意它不是默认标准文件名，必须通过配置或其他机制让 Codex 读取，同时应加入 .gitignore。

无论采用什么本地规则，都不要把 token、密钥、密码和私有凭据写进去。

一份可直接修改的模板

# AGENTS.md

## 项目概览

- 项目类型：
- 主要语言：
- 关键目录：
- 不要修改的目录：

## 常用命令

- 安装依赖：`...`
- 本地开发：`...`
- 运行测试：`...`
- 类型检查：`...`
- 格式化：`...`

## 代码规范

- 遵循现有代码风格。
- 不做与当前任务无关的重构。
- 新增功能必须补充或更新测试。

## 安全边界

- 不读取或提交 `.env`、密钥和私有凭据。
- 不执行删除生产数据的命令。
- 修改数据库迁移前先说明影响和回滚方式。

## 交付要求

- 说明修改了哪些文件。
- 说明验证命令和结果。
- 标注未验证内容和剩余风险。

写 AGENTS.md 最容易犯的四个错误

1. 写成项目百科

规则文件过长会占用上下文，也可能超过客户端读取预算。详细架构和业务文档应该放在独立文件里，再由 AGENTS.md 指明阅读入口。

2. 只有口号，没有命令

“保证代码质量”不如“修改后运行 pnpm test 和 pnpm typecheck”。

规则必须尽量具体、可执行、可验证。

3. 和其他文档互相冲突

如果 README、贡献指南和 AGENTS.md 给出不同测试命令，Codex 很难判断哪一份才是当前事实。

4. 写完后从不更新

项目命令、目录和发布流程都会变化。失效规则比没有规则更危险，因为它会稳定地产生错误行为。

如何验证规则是否有效

创建或修改后，可以新开一个对话，要求：

请先不要修改文件。
根据当前项目规则，说明项目结构、常用测试命令、禁止修改的内容和任务完成标准。

如果回答与团队预期一致，说明规则已经被正确读取；如果不一致，应先修正规则，再开始真实任务。

写在最后

好的 AGENTS.md 不是一份面面俱到的说明书，而是一张工作地图。

它应该让 Codex 快速知道：

项目在哪里
→ 应该先读什么
→ 可以改什么
→ 不能碰什么
→ 怎样验证
→ 最后怎样交付

当这些信息进入仓库后，项目经验就不再只存在于某个人的脑子里。