Appearance
09 · AGENTS.md 指南
📚 系列导航：上一篇 08 会话经营 管的是上下文窗口。这一篇解决一个最高频的问题：每次开新会话它都不记得上次的事，怎么让项目规矩「一次写入，长期生效」？
01 问题：Codex 的「失忆」
每个 Codex 会话都从全新的上下文窗口开始。你上次交代的「用 pnpm 不用 npm」「测试跑 pnpm test」「提交信息要中文」，这次它一概不记得。
AGENTS.md 就是解决这个问题的——它是 Codex 每次开工必读的「入职手册」，把项目的规矩一次性写进去，之后每次会话都自动遵守。
02 三层级
| 层级 | 放哪 | 管多大范围 | 进不进 git |
|---|---|---|---|
| 个人级 | ~/.codex/AGENTS.md | 你这台机器上所有项目 | ❌ 不进 |
| 项目级 | ./AGENTS.md | 当前项目 | ✅ 进 |
| 子目录级 | 任意子目录 | 局部规则 | ✅ 进 |
加载顺序： 从最广到最具体依次加载，拼接不覆盖。越靠近工作目录的指令越晚读，冲突时越占优。
03 该写什么 vs 不该写什么
✅ 该写
| 类别 | 例子 |
|---|---|
| 项目概述 | 「基于 FastAPI 的订单管理后端」 |
| 技术栈 | 「Python 3.11 / PostgreSQL / pytest」 |
| 常用命令 | uv run pytest、uv run ruff check . |
| 代码约定 | 「函数必须有类型注解」 |
| 明确的「不要做」 | 「禁改 migrations/ 已有文件」 |
❌ 不该写
- 长篇背景（公司介绍、产品愿景）
- 过时信息
- Codex 看代码能自己推出来的东西
- 一次性的需求（放提示里，别放 AGENTS.md）
NOTE
判断标准：每行自问「删了它 Codex 会犯错吗？」不会就删。目标 200 行以内。
04 维护
会话里想补一条规矩：
text
把「数据库操作必须走 Service 层」这条加进 AGENTS.md触发精简的时机： 换了构建工具、加了重要依赖、发现 AGENTS.md 又悄悄涨过 200 行。
05 动手：最小项目跑通
bash
mkdir init-demo && cd init-demo
echo 'console.log("hello");' > index.js
codextext
帮我在项目根目录建一个 AGENTS.md，写清：
1. 这是 Node.js 项目
2. 测试用 `node --test`
3. 代码风格用 StandardJS退出后 cat AGENTS.md 确认内容。再进 codex 问「这个项目的测试命令是什么？」——它应该直接回答。
06 小结
| 知识点 | 关键结论 |
|---|---|
| 解决什么 | Codex 每次会话「失忆」，AGENTS.md 是跨会话记忆载体 |
| 三层级 | 个人级 → 项目级 → 子目录级，拼接加载 |
| 该写什么 | 概述/技术栈/命令/约定/禁区 |
| 不该写什么 | Codex 自己能推出来的、长篇背景、一次性需求 |
| 维护 | 会话里直接让 Codex 加，定期精简到 ≤ 200 行 |
NOTE
下一篇：10 MCP 与外部工具：把 Codex 接上外部世界。