每新开一个对话窗口，Codex 面前就是一张白纸。它不知道这个项目用什么命令，哪些目录是边界，哪些文件不能改。团队平时怎么验证结果，它同样不清楚。上一轮刚解释过的东西，它一条都不记得。

稳定的做法是把要反复说明的项目信息写成文件，让它每次开工前自己读一遍。

这份记忆存在一个 Markdown 文件里

项目级 AGENTS.md 就是写给 Codex 看的项目规则说明书。它和另外两份常见文件的分工是这样的。

文件	主要读者	作用
README.md	人	说明项目是什么，怎么安装，怎么使用
AGENTS.md	Codex 这类 AI Agent	说明在项目里应该怎么工作
.gitignore	Git	哪些文件不要上传

它本身只是一份普通的 Markdown。Codex 处理任务前会自动读取，把内容作为工作上下文带进新的对话。写完之后，你就不用每次都重新交代一遍。

三个位置管三种范围

放置位置	作用范围	简单来说
项目根目录的 AGENTS.md	整个项目	当前项目的总规则
子目录里的 AGENTS.md	当前子目录及相关任务	某个模块的专属规则
用户级的 ~/.codex/AGENTS.md	你所有项目	个人通用规则

项目级和用户级会叠加生效，等于个人习惯加上当前项目的规则。全局规则还有一个省事的入口。桌面端打开设置找到个性化，这里输入的自定义指令会作为个人通用偏好影响后续会话，本质也是写进 Codex_Home 的 AGENTS.md。

读取顺序和覆盖规则

Codex 先读全局规则，默认是 ~/.codex/AGENTS.md。同一个位置如果还有 AGENTS.override.md，就优先读它，临时覆盖全局规则时用得上。接着读项目规则，它从 Git 根目录出发一路走到你当前的工作目录，沿途每一层都尝试读取。

同一个目录里两个文件都在时，AGENTS.override.md 覆盖 AGENTS.md。读到的内容从上往下合并，根目录的规则排在前面，子目录的排在后面。越靠近当前目录的规则越具体，局部要求写在这一层最合适。

文件名要始终是 AGENTS.md，大小写也得对，写错它不会自动识别。

规则写太多也会溢出

合并后的项目指令有大小上限，官方默认 project_doc_max_bytes 是 32768，也就是 32KiB。文件太大，后面的内容可能进不了上下文。

更好的做法是让它承担导航，告诉它项目文档的目录清单，而不是把文档整篇抄进去。项目里已经有别的规则文件时，可以在配置里用 project_doc_fallback_filenames 添加备用文件名，找不到 AGENTS.md 或者 AGENTS.override.md 时再试这些。

团队规则和个人规则分开放

多人协作时，AGENTS.md 适合放团队共同认可的项目规则。个人路径，本机工具习惯，私有的工作流偏好，这些留在本地更合适。团队规则保持稳定，个人习惯也不会被提交进仓库。

文件	作用	是否提交 Git
AGENTS.md	团队共享的项目规则，命令，边界和交付要求	可以提交
AGENTS.override.md	官方识别的覆盖文件，适合临时覆盖同目录规则	通常不提交
AGENTS.local.md	个人本地偏好，私有路径和临时规则	应加入 ignore

AGENTS.local.md 不是 Codex 默认识别的标准文件名，想让它被读到，得借助 hooks 或者社区工具，也可以在配置里把它加进 fallback 名单。不管用不用本地规则，token 和密钥这类东西都不能写进 AGENTS.local.md。同时把 AGENTS.local.md 和 AGENTS.override.md 加进 gitignore。本地规则也不该绕开团队的测试，审批和安全要求。

全局偏好里先加这一条

用 AI 编程最怕它乱删东西。在个性化指令里可以加上一条，禁止批量删除文件或目录。

禁止写法	说明
del /s、rd /s、rmdir /s	Windows 下的批量删除
Remove-Item -Recurse	PowerShell 的递归删除
rm -rf	命令行递归删除

需要删文件时只能一次删一个明确路径的文件。确实要批量删，就停下来问用户，让用户手动处理。

写法这里只留一句

AGENTS.md 的详细写法有专门一篇，这里只记一条原则，写「运行测试：pnpm test」比写「记得自己检查一遍代码有没有问题」有用得多。