AGENTS.md 是什么，为什么能让 Codex 更稳定

如果你已经能让 Codex 完成页面优化、修 Bug、排查构建失败这些常见任务，下一步就不是继续堆更长的提示词，而是把反复出现的项目经验沉淀下来。

AGENTS.md 就是做这件事的。

前置教程：常见任务实战：让 Codex 修改一段接口逻辑
如果你还没有跑通过一个完整任务，先回到前置教程。否则你会不知道哪些规则真的值得沉淀。

这一篇你会学到什么

AGENTS.md 是什么。
它适合解决哪些重复问题。
它和一次性提示词有什么区别。
它和 config.toml 有什么区别。
新手第一次写 AGENTS.md 应该遵守哪些原则。
什么时候不应该写 AGENTS.md。

核心结论

AGENTS.md 是给 Codex 看的项目说明书，用来记录长期有效的项目规则。

它不是一篇普通教程，也不是项目介绍文章，更不是让你把所有想法都塞进去的万能笔记。

它的价值在于：以后每次 Codex 进入这个项目时，都能先看到这些长期规则。

一个最常见的场景

假设你每次让 Codex 改项目，都会重复提醒它：

这个项目用 npm run build 检查构建。
不要修改 package-lock.json，除非确实安装依赖。
UI 文案必须用中文。
修改接口逻辑时要同步更新前端调用。
提交前要说明改了哪些文件。

如果这些话每次都靠你手动复制，就很容易漏。

更好的做法是把它们写进项目根目录的 AGENTS.md。

以后只需要正常提任务：

帮我修复登录页手机号输入框的校验问题。

Codex 会在任务开始前读取项目里的 AGENTS.md，再结合你的当前任务一起工作。

AGENTS.md 适合写什么

适合写进 AGENTS.md 的内容有一个共同点：

只要 Codex 以后还会在这个项目里工作，它就应该一直知道这些信息。

典型内容包括：

内容类型	可以写什么
项目启动方式	本地开发、构建、测试、类型检查命令
技术栈约定	Astro、Nuxt、Spring Boot、Tailwind、Maven 等
目录边界	哪些目录是前端、后端、脚本、文档、生成物
代码风格	命名方式、组件组织方式、接口返回格式
验收要求	改完后优先让 Codex 自己跑哪些检查
禁止事项	不要改哪些文件，不要重构哪些模块，不要提交密钥
常见坑	某个构建命令慢、某个测试需要环境变量、某个目录是生成代码
审查要求	最后汇报 diff、风险、未验证项

AGENTS.md 不适合写什么

不要把下面这些东西写进去：

不适合写入	原因
API Key、Token、密码	这是敏感信息，不能进项目说明
临时任务需求	一次性任务应该写在当前对话里
太长的业务背景故事	Codex 会抓不住重点
“尽量写好代码”这种空话	太泛，不能指导实际行为
你还没验证过的命令	Codex 可能按错误命令反复失败
已经过时的旧流程	比没有规则更糟糕

一个好的 AGENTS.md 应该短、准、可执行。

它和一次性提示词有什么区别

一次性提示词适合当前任务。

比如：

只修改 src/pages/login.vue，不要改接口，不要改样式变量。

这种限制只对这一次任务有效，不应该写进 AGENTS.md。

AGENTS.md 适合长期规则。

比如：

所有页面文案默认使用简体中文。
改动完成后，优先让 Codex 运行项目已有的构建或测试命令，并汇报结果。

只要未来还会用，就可以沉淀进去。

它和 config.toml 有什么区别

这两个很容易混。

你可以这样理解：

文件	负责什么	例子
`AGENTS.md`	告诉 Codex 这个项目怎么做事	构建命令、代码规范、目录约定、验收方式
`config.toml`	告诉 Codex 自身怎么运行	模型、provider、审批策略、沙箱、MCP、功能开关

不要把代码规范写进 config.toml。

也不要把模型配置写进 AGENTS.md。

AGENTS.md 可以放在哪里

常见有三层：

位置	作用
`~/.codex/AGENTS.md`	你个人所有项目的通用偏好
项目根目录 `AGENTS.md`	当前项目的共享规则
子目录里的 `AGENTS.md` 或 `AGENTS.override.md`	某个模块的更具体规则

新手建议先只用项目根目录的 AGENTS.md。

不要一开始就搞很多层。层级多了以后，排查“为什么 Codex 遵守了这条规则”会变复杂。

一个新手可用的 AGENTS.md 示例

下面只是示例，不要直接照搬。你应该让 Codex 先读你的项目，再根据真实项目生成。

## 项目概况

这是一个 Astro 静态教程站，主要内容在 src/content/docs 目录中。

## 常用检查

- 修改页面、组件或样式后，优先运行 npm run build。
- 如果没有运行检查，最后必须说明原因。

## 写作规则

- 面向中文用户，默认使用简体中文。
- 教程内容要写成喂饭级步骤，不能跳过关键操作。

## 修改边界

- 不要随意重命名已有路由。
- 不要把真实 API Key、Token、密码写入仓库。
- 不要为了小改动做大范围重构。

## 汇报要求

任务结束时说明：

- 改了哪些文件。
- 做了哪些检查。
- 是否有未验证项。

第一次写 AGENTS.md 的原则

原则 1：先少写

第一次不要追求完整。

先写最确定的 5 到 10 条：

项目是什么。
常用检查命令是什么。
哪些目录最重要。
哪些文件不要乱改。
最后怎么汇报。

后面每次发现 Codex 重复犯同一个错误，再补规则。

原则 2：写真实命令

不要凭感觉写：

npm test

除非项目里真的有这个脚本。

更稳的做法是让 Codex 先读 package.json、pom.xml、README，再整理真实命令。

原则 3：写可判断的规则

不要写：

代码要优雅。

这句话没法判断。

改成：

除非任务明确要求，否则不要把一个小 Bug 修复扩展成跨模块重构。

这样 Codex 更容易执行，你也更容易验收。

原则 4：不要代替验收

AGENTS.md 可以提醒 Codex 跑检查，但不能代替你看结果。

正确流程是：

你提出任务。
Codex 根据任务和 AGENTS.md 工作。
Codex 运行它认为必要的检查。
你看 Codex 汇报的 diff、检查结果和未验证项。
你决定是否继续追问或接受。

判断你是否理解了

看下面 5 个说法。

说法	是否正确
API Key 可以写进 AGENTS.md，方便 Codex 使用	错
每次都重复提醒 Codex 的项目规则，可以考虑写进 AGENTS.md	对
当前这一次任务的临时限制，应该优先写在对话里	对
模型 provider 和 Base URL 应该写进 AGENTS.md	错
AGENTS.md 越长越好	错

这一篇的验收标准

你读完后应该能回答：

AGENTS.md 是给谁看的。
什么内容适合写进去。
什么内容不能写进去。
它和一次性提示词有什么区别。
它和 config.toml 有什么区别。

如果这些你都能说清楚，再进入下一篇。

下一篇看：第一次给项目添加 AGENTS.md。