5 AGENTS.md 与 config.toml：把项目规矩交给 Codex

查看大图

如果你只想学一个能长期提升 Codex 效果的文件，我建议先学 AGENTS.md。

它不是给人看的普通 README，而是给 coding agent 的项目说明书。官方 AGENTS.md 指南里说，Codex 会在开始工作前读取这些文件，并把全局规则、项目规则、子目录规则按顺序合并。越靠近当前目录的规则，越能覆盖前面的规则。

项目规则不要只放在聊天里。真正有效的是写进 AGENTS.md、配置文件或仓库文档，让 Codex 每次进项目都能读到同一套边界。

查看大图

我会把高风险目录、测试命令、部署方式、提交格式写清楚。这样后面换线程、换模型、换任务时，项目规矩仍然在仓库里，而不是靠人临时回忆。

AGENTS.md 应该写什么

一个实用的 AGENTS.md 可以从这几块开始：

查看大图

维护 AGENTS.md 和配置文件时，重点写清项目边界、命令、代码风格、安全规则和部署方式。

# AGENTS.md

## Project
- This is a Next.js site.
- Content lives under content/.
- Public images live under public/images/.

![Codex实践复盘卡](/images/codex-zero/lesson-05-practice-review-card.svg)

看完《AGENTS.md 与 config.toml：把项目规矩交给 Co...》后，建议用一分钟复盘：关键概念是否分清、练习步骤是否可复现、结论能不能换成自己的话。

## 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。把这些反复出现的问题写成规则，下一次就少踩坑。

查看大图

练习《AGENTS.md 与 config.toml：把项目规矩交给 Codex》时，建议把输入条件、处理动作和可见结果写在一起，方便下次复查。

查看大图

复习《AGENTS.md 与 config.toml：把项目规矩交给 Codex》时，建议把关键概念、操作步骤和可见结果放在同一页里回看。

参考资料：

• Custom instructions with AGENTS.md
• Codex config basics
• Codex customization