第 5 课 · PROJECT RULES & MEMORIES

AGENTS.md：
让 Codex 记住项目规矩

每开一个新对话，Codex 都要重新认识你的项目：测试怎么跑、哪些文件别碰，它不会自己记得。把这些写进一份 AGENTS.md，它每次开工前先读一遍，你就不用一遍遍重复。这一课讲清楚它放在哪、怎么被读到、该写什么，再认识一下实验中的 Memories。

约 30 分钟 10 节 · 5 个动手练习章末测验形式参考 luongnv89/claude-howto · 事实依据 OpenAI 官方文档

同一个任务，点上面切换看看

入门先用起来原理弄懂为什么实战动手练深入进阶与避坑

时间紧就先看"入门"和"实战"：知道放哪、用 /init 起个草稿，今天就能用上。"原理"讲几份文件怎么拼在一起，决定你的规矩到底有没有被读到。

01入门

AGENTS.md 是什么

官方的说法：它是一份写给 agent 看的 README。你写一次，Codex 每次开工前都会自动读。

README 写给人看项目是做什么的、怎么装、怎么用。新同事读一遍就能上手。

AGENTS.md 写给 Codex 看测试怎么跑、代码有什么约定、哪些文件别碰。像贴在工位上的"项目须知"：它每次开工前扫一眼，就不用你再交代。

它什么时候读、谁会读

Codex 在动手之前读 AGENTS.md，把内容放进这个对话最开头的指令里。桌面 App、命令行、IDE 扩展、云端任务都认它；在 GitHub 上用 @codex 发起的云端任务，还会从里面找项目的测试和 lint 命令。

它就是仓库里一个普通的 Markdown 文件，用标题和列表写清楚就行。AGENTS.md 是开放格式，介绍在 agents.md，不是 Codex 私有的写法。

一句话记住

提示词管这一次，AGENTS.md 管每一次。官方把"把长期规则塞进每次的提示词"列为新手常见错误：规矩一旦要说第二遍，就该写进 AGENTS.md。

02入门

放在哪：三个位置

同样叫 AGENTS.md，放的位置不同，管的范围就不同。order-admin 这一课会用到全部三种。

个人

~/.codex/AGENTS.md只对你生效，打开哪个项目都读。官方建议用它定"Codex 怎么跟你打交道"：审阅风格、详略、你的默认习惯。order-admin 里：用中文回复

仓库根

order-admin/AGENTS.md提交进 Git，全队共享。写项目怎么跑、测试命令、代码约定、哪些东西别碰。最常用 · 本课主角

子目录

src/api/AGENTS.md只管这一块代码的局部约定。放在离代码最近的地方，离当前目录越近越优先（下一节细讲）。order-admin 里：接口约定

个人那份放在 Codex 的主目录里，默认是 ~/.codex；如果设置了 CODEX_HOME 环境变量，就换成那个目录。

在 App 里改个人那份

打开 Settings > Personalization（个性化），里面可以写自定义指令（custom instructions）。在 Codex 里，这些个人指令就存在你的全局 AGENTS.md 里：改那里，等于改你的全局 AGENTS.md（默认是 ~/.codex/AGENTS.md）。注意：同一层要是有 AGENTS.override.md，这份就不读了。

AGENTS.override.md：临时换一套

同一层里如果还有一份 AGENTS.override.md，Codex 只读它，同层的 AGENTS.md 就不读了。官方给的用法：想临时换一套个人规矩、又不想删原文件，就在 ~/.codex 里放一份 override，用完删掉，原来的规矩自动恢复。子目录里也能放，给某个团队用一套不同的规矩。

03原理

加载规则：从根走到当前目录

对话开始时，Codex 把几份 AGENTS.md 串成一条"指令链"。先看三条规则，再到目录树里点一点。

先读个人那一层在 ~/.codex 里，有 AGENTS.override.md 就用它，否则用 AGENTS.md。这一层只取第一份不是空的。

再从项目根一层层走到当前目录项目根通常就是 Git 仓库的根（有 .git 的那一层）。路上每一层最多取一份，先找 AGENTS.override.md，再找 AGENTS.md，最后找你配置的备用文件名。找不到项目根时，只看当前目录这一层。

按顺序拼起来，越靠后越优先从根往下，用空行连成一段。离当前目录越近的排得越后，说法冲突时以它为准。空文件直接跳过。另外有大小上限，默认 32 KiB，太长会被截断。

"当前目录"是哪？

在 App 里，新对话从项目的主文件夹（primary folder）开始，Codex 也在这里自动发现 AGENTS.md。项目挂了好几个文件夹时，只有主文件夹会自动发现。用命令行时，就是你启动 codex 的那个目录。所以在 App 里给 order-admin 开对话，开场读到的是个人那份和仓库根那份；src/api 在它下面，不在这条路上。

目录树合并模拟器

order-admin 的目录树（示例）。点一个文件夹，把它当成当前目录，看哪些文件被读、按什么顺序拼。再打开开关，试试 override、空文件和"没有 .git"的情况。

在 ~/.codex 里加一份 AGENTS.override.md 在 src/api 里加一份 AGENTS.override.md 把 src/components/AGENTS.md 清空假设 order-admin 没有 .git

按官方文档写的发现规则计算；文件内容是示例节选。

04实战

练一练：这次会读哪几份

还是 order-admin。6 个情况，每个选一个答案，选完看解析。拿不准就回到模拟器里试一下。

05原理

写什么、写多短

官方的建议很简单：只写真正要紧的，写短、写准；它犯了错，再补一条。

官方建议写这 6 样

仓库结构和重要目录页面、组件、接口、数据库各在哪。

怎么把项目跑起来装依赖、本地启动的命令。

构建、测试、lint 命令它知道怎么验证，才能自己检查改对没有。

工程约定和 PR 要求代码风格、文件放哪、提交前要做什么。

约束和"不要做"的事比如别改 .env、加依赖先问。

怎样算做完、怎么验证和第 1 课任务四要素里的"完成标准"是一回事，只是写成了长期规矩。

order-admin 的三份（示例）

写短，别写空话

短而准，胜过长而空。官方原话的大意是：一份短而准确的 AGENTS.md，比一长串空泛的规则有用。"代码要写得优雅"这种话，Codex 没法照着做。
先写基本的，犯了错再加。同一个错误它犯了两次，就让它做个复盘，再把结论更新进 AGENTS.md。这样每一条都来自真实的坑。
太长就拆。主文件保持精简，把规划、代码审查、架构这类长内容放进单独的 Markdown 文件，在 AGENTS.md 里写一句"做代码审查时先读 docs/code_review.md"。
越长越费额度。它每个对话都会被读进去。官方省额度的建议里就有一条"缩小 AGENTS.md"，大项目把内容分散到子目录里。额度说明见专题 A。

什么时候改它

同一个错反复犯加一条规则。

找对了文件，但读了太多文档加几句"指路"：先看哪些目录、哪些文件。

审 PR 时，同一个意见说了不止一次写进去，下次它自己就注意了。

在 GitHub 上顺手改在 PR 评论里写 @codex add this to AGENTS.md，交给云端对话去改（第 13 课）。

想定期查漏用定时任务每天检查一遍，找出该补进 AGENTS.md 的规矩（第 13 课）。

纠正它的时候，顺手让它记下来

它猜错了你们的做法，先纠正，再加一句"把这条更新进 AGENTS.md"。官方把这叫作反馈循环：这次纠正过的事，以后的对话都会带着。

它是约定，不是锁

AGENTS.md 是写给 Codex 看的指令，不是会自动拦截的机关。真正不能破的规矩，官方建议再配上会自动检查的东西：pre-commit 钩子、linter、类型检查。Codex 自己的 Hooks 在第 10 课讲。

06实战

演练：起草、改好、再验证

在 order-admin 里用 /init 生成草稿，你改一遍、提交，再开一个新对话，看它是不是真的守规矩。中途会请你批准一次提交，允许和拒绝都可以试。

画面为教学示意：草稿内容、提交号和 Codex 说的话都是虚构的；/init、只在对话开始时读、.git 受保护要批准，这些规则与官方文档一致。

07实战

练一练：这条写到哪

8 句话，每句选一个去处。有的该进仓库，有的只属于你，有的根本不该写。

08原理

Memories：它自己记的笔记实验

AGENTS.md 是你写给它的规矩；Memories 是 Codex 从以前的对话里自己整理出来的背景。有用，但不保证每次都在。

它是什么打开以后，Codex 会从以前符合条件的对话里，把有用的背景整理成本地的记忆文件，以后的对话可以用上。

默认关着实验功能，可能会改。在 Settings > Personalization 里打开 Enable memories。设置里找不到这一项，可能是你的账号或地区还没开放（官方写的是 where available）。

按对话控制：/memories决定这个对话能不能用已有的记忆、能不能拿去生成以后的记忆。只管这个对话，不改全局设置。

存在你电脑上在 ~/.codex/memories/ 里。这些是自动生成的文件，排查问题时可以打开看，但别把手改它们当成主要的控制方式。

在后台慢慢更新不是每个对话一结束就更新：正在进行的、很短的对话会跳过，要等对话闲置一阵才整理；额度快用完时也会跳过这一轮，省额度。

全局开关和对话开关（示意）

拨一拨，看 Codex 在对话开始时和结束之后会怎么做。

AGENTS.md 和 Memories 怎么分工

	AGENTS.md	Memories
谁来写	你（可以用 `/init` 起草，也可以让 Codex 改）	Codex 在后台从以前的对话里整理
放在哪	仓库里（提交后全队共享）和 `~/.codex`	`~/.codex/memories/`，只在你电脑上
什么时候用上	每个对话开始时都读	打开后，对话可以带上已有的记忆
靠不靠得住	在指令链上就读（每个对话开始时）	官方说是"有帮助的回忆"，不能当唯一的规则来源
成熟度	正式功能	实验默认关
适合放	必须遵守的规矩、命令、约定	顺手记住的背景、偏好、常做的事

必须遵守的，写进 AGENTS.md

官方说得很明确：团队必须遵守的规矩，放在 AGENTS.md 或提交进仓库的文档里。Memories 只当"顺手想起来"的补充，别让它成为某条规则唯一的出处。

别往记忆里放密钥

Codex 生成记忆时会把密钥打码，但你还是别在记忆里存密钥。要把 Codex 的主目录分享给别人之前，先看一眼 ~/.codex/memories/ 里的文件。

09深入

进阶与避坑

规矩没生效、读错了、太长了、仓库里已经有别的说明文件……常见问题都在这里。

旧教程对照

"/init 只有命令行才有"：2026 年 6 月起，桌面 App 的输入框里也能用 /init。
"Codex 没有记忆，每次都从零开始"：现在有 Memories（实验，默认关，第 8 节）。不过必须遵守的规矩，官方仍然要你写进 AGENTS.md。
"在 config.toml 里写 instructions 给它定规矩"：这个键现在是保留字段，官方建议改用 AGENTS.md。

改了 AGENTS.md，它还是按老规矩来

AGENTS.md 在对话开始时读一次，对话进行中改了文件，这个对话不会重新读。开一个新对话再试。如果新对话里还是旧规矩，完全退出 App 重开（官方排障写的是 restart Codex）。命令行里要重新启动 codex，只用 /new 不一定会重新读。

读到的规矩不对，像是别处来的

先找 AGENTS.override.md：可能在更上层的目录里，也可能在 ~/.codex 里。它会让同层的 AGENTS.md 整份不读。改名或删掉 override，就回到普通的 AGENTS.md。另外确认 CODEX_HOME 有没有被设成别的目录，个人那份要放在它指向的地方。

子目录里的 AGENTS.md 什么时候才会被读到？

只有当前目录走到那一层（或更深）时，开场的指令链里才有它。在 App 里对 order-admin 开对话，当前目录是仓库根，src/api/AGENTS.md 不在开场的指令链里。按文档的规则推算，想让它进来，当前目录得在 src/api：比如 codex --cd src/api（命令行），或者单独建一个主文件夹是 src/api 的项目。Codex 会往上找到仓库根，所以根目录那份照样读。另外，GitHub 上的代码审查会按"离代码最近的 AGENTS.md"找审查规则（第 13 课）。

怎么确认它到底读了哪几份？

开一个新对话，直接问它："列出你读到的指令文件，按顺序说说分别来自哪里。"官方核对时也是这么做的：它应该先报个人那份，再报仓库根，最后是离当前目录最近的那份。（命令行）启动时加 -c log_dir=./.codex-log，再看 ./.codex-log/codex-tui.log，里面有它加载了哪些指令文件。

太长被截断了

默认上限 32 KiB，超出的部分会被截断。先精简主文件，把长内容拆到子目录的 AGENTS.md 或单独的 Markdown 文件里；实在需要，也可以调大配置项 project_doc_max_bytes。

仓库里已经有 TEAM_GUIDE.md，或者从别的工具带来的说明文件

Codex 默认只认 AGENTS.override.md 和 AGENTS.md，别的文件名要加进"备用文件名"列表（见下面的代码块）。从 Claude Code 搬过来的，可以用 App 的导入功能（Settings > Import），它会把说明文件转成 AGENTS.md，专题 D 细讲。

AGENTS.md 能硬性拦住它吗？

不能保证。它是给 Codex 看的指令，Codex 会照着做，但它不是自动拦截的机关。像"绝对不能改 .env"这种事，再配上 pre-commit 钩子、linter，或者第 10 课的 Hooks。

打开了 Memories，怎么还没记住上个对话的事？

记忆在后台更新：要等对话闲置一阵，太短的对话会跳过，额度快用完时也会跳过。另外看看那个对话有没有用 /memories 关掉"拿去生成记忆"。

ChatGPT 网页版的记忆，和这里是一回事吗？

不是。网页版的 ChatGPT 用的是 ChatGPT 自己的记忆；桌面 App、命令行、IDE 扩展里的本地 Codex，用的是另一个存在你电脑上的记忆库和开关。

加备用文件名、调上限

这两项写在 ~/.codex/config.toml 里（配置文件怎么改，第 7 课讲）。下面是官方的示例：

~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

这样每一层的查找顺序变成 AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md，还是每层最多取一份；不在列表里的文件名一律不当指令文件。改完配置，官方写的是“重启 Codex 或者运行一条新命令”才会读到新配置；在 App 里，稳妥的做法是重启 App 再开新对话。

10检验

小测验

8 道题，每题选完会立刻看到解析。