5 AGENTS.md 与 config.toml：把项目规矩交给 Codex
如果你只想学一个能长期提升 Codex 效果的文件，我建议先学 AGENTS.md。
它不是给人看的普通 README，而是给 coding agent 的项目说明书。官方 AGENTS.md 指南里说，Codex 会在开始工作前读取这些文件，并把全局规则、项目规则、子目录规则按顺序合并。越靠近当前目录的规则，越能覆盖前面的规则。
AGENTS.md 应该写什么
一个实用的 AGENTS.md 可以从这几块开始：
# AGENTS.md
## Project
- This is a Next.js site.
- Content lives under content/.
- Public images live under public/images/.
## Commands
- Build: npm run build
- Dev: npm run dev
- Do not add dependencies unless asked.
## Working rules
- Keep changes small and scoped.
- Do not edit .env, certificates, private keys, or generated folders.
- Before final response, summarize changed files and verification results.
## Content rules
- Chinese tutorials should be practical and concrete.
- Avoid generic AI-sounding copy.
- Every tutorial article needs a cover image.
重点是具体。不要写“认真一点”“代码写好看一点”。要写“改了 JS 文件后运行 npm test”“不要改 .env”“新增内容图片放 public/images”。
全局规则和项目规则分开
官方文档里提到，Codex 会先读 Codex home 里的全局 AGENTS.md，默认位置通常是 ~/.codex，然后再读项目里的 AGENTS.md。
我建议这样分：
~/.codex/AGENTS.md：个人偏好，比如回复语言、审查风格、是否优先解释。- 项目根目录
AGENTS.md：项目命令、目录结构、测试要求、部署红线。 - 子目录
AGENTS.md或AGENTS.override.md：更具体的局部规则，比如支付服务、前端页面、内容目录。
团队共享的规则放项目里。个人习惯放自己目录里。
用 /init 起步
官方 best practices 里提到，CLI 的 /init 可以在当前目录生成一个 starter AGENTS.md。它适合起步，但生成后一定要改。
/init
我通常会让 Codex 先生成，再补三件事：真实构建命令、不要碰的文件、完成前必须做的检查。
config.toml 管行为，AGENTS.md 管规矩
AGENTS.md 写项目规则，config.toml 写 Codex 行为配置。比如 model、reasoning effort、sandbox、approval policy、MCP server、feature flags。
官方 best practices 建议：
- 个人默认放
~/.codex/config.toml。 - 项目行为放
.codex/config.toml。 - 一次性变化用 CLI
-c key=value覆盖。
新手不要一开始就复制一大份配置。先用默认权限，等你明确知道某个项目需要什么，再逐步配置。
什么时候更新 AGENTS.md
当 Codex 连续犯同一种错误，就该更新 AGENTS.md。比如它总是用 npm，但项目实际用 pnpm；它总是改生成文件；它总是忘记跑 build。把这些反复出现的问题写成规则，下一次就少踩坑。
参考资料：
Continue