Codex中文官网

每新开一个对话窗口，Codex 面前就是一张白纸。它不知道这个项目用什么命令，哪些目录是边界，哪些文件不能改。团队平时怎么验证结果，它同样不清楚。上一轮刚解释过的东西，它一条都不记得。 稳定的做法是把要反复说明的项目信息写成文件，让它每次开工前自己读一遍。 这份记忆存在一个 Markdown 文件里 项目级 AGENTS.md 就是写给 Codex 看的项目规则说明书。它和另外两份常见文件的分工是这样的。 文件主要读者作用README.md人说明项目是什么，怎么安装，怎么使用AGENTS.mdCodex 这类 AI Agent说明在项目里应该怎么工作.gitignoreGit哪些文件不要上传 它本身只是一份普通的 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 适合放团队共同认可的项目规则。个人路径，本机工具习惯，私有的工作流偏好，这些留在本地更合适。团队规则保持稳定，个人习惯也不会被提交进仓库。 文件作用是否提交 GitAGENTS.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 /sWindows 下的批量删除Remove-Item -RecursePowerShell 的递归删除rm -rf命令行递归删除 需要删文件时只能一次删一个明确路径的文件。确实要批量删，就停下来问用户，让用户手动处理。 写法这里只留一句 AGENTS.md 的详细写法有专门一篇，这里只记一条原则，写「运行测试：pnpm test」比写「记得自己检查一遍代码有没有问题」有用得多。