没有 AGENTS.md 的那个月，我的 Codex 天天翻车

上个月我接手了一个 Node.js 后端项目，第一件事就是打开 Codex，让它加一个小功能。

它看起来很认真——读了文件，写了代码，还跑了命令。结果我一看 diff：

• 项目明明用 pnpm，它跑了 npm install
• 测试命令猜错了
• 顺手改了接口返回格式
• 新增了我不想要的第三方依赖

当时我就有点火大。但冷静下来想想：它刚进项目，没人告诉它规矩。它不知道我们团队为什么用 pnpm，不知道哪些目录不能动，也不知道改完必须跑哪条测试命令。

这不是 Codex 的问题。是我的问题。

AGENTS.md 就是给 Codex 的项目入职手册

你可以把 AGENTS.md 理解成写给 Codex 的项目说明书。它和 README 不一样——README 写给人看，介绍项目背景、功能、安装方式；AGENTS.md 写给 Codex 看，像现场工作须知。

两者最大的区别：

内容	README 更适合	AGENTS.md 更适合
项目是什么	详细介绍	一句话够了
怎么安装运行	完整说明	写 Codex 真要执行的命令
代码风格	描述理念	写可检查规则
禁区	可以提	必须明确写
验收	贡献流程	每次改完要跑什么

自从写了 AGENTS.md，之前那些翻车的事基本消失了。它不会再跑 npm install，因为文件里写着"使用 pnpm，不要使用 npm"。它不会再碰 src/core/，因为文件里写着"不要修改 src/core/，除非任务明确要求"。

第一版千万别写长，先写能救命的 15 行

很多人第一次写 AGENTS.md，会把它写成小论文。项目历史、产品介绍、目录背景、技术选型原因全塞进去。

这反而不好。Codex 每次工作都会把这些说明纳入上下文，越长越容易稀释重点，也越浪费上下文窗口。

我的第一版只有这几样东西：

# 项目说明

这是一个 Node.js 后端服务。

## 常用命令
- 安装依赖：`pnpm install`
- 运行测试：`pnpm test`
- 运行 lint：`pnpm lint`

## 代码规则
- 使用 pnpm，不要使用 npm 或 yarn。
- API 路由放在 `src/routes/`。
- 数据模型放在 `src/models/`。
- 不要修改 `src/core/`，除非任务明确要求。

## 验收
- 改完优先跑相关测试。
- 涉及接口返回时，不要擅自改变字段名和状态码。

就这么多。但这 15 行已经比一大段泛泛而谈有用十倍。

好规则和坏规则的区别，我踩过的坑

好规则要能被执行、能被检查。

"测试命令是 pnpm test"是好规则，因为 Codex 能直接执行。"API 返回结构必须保持向后兼容"也是好规则，因为可以验证。

"代码要优雅"是坏规则。"注意质量"也是坏规则。Codex 根本不知道你说的"优雅"是什么标准。

我之前写过"不要乱改"，觉得挺清楚的。结果 Codex 还是"乱改"了——因为在它的理解里，顺手整理一下不叫"乱改"。后来我把这句话换成了：

- 只修改任务直接相关的文件。
- 如果需要改其他模块，先说明原因并等待确认。

这就可执行多了。

全局规则和项目规则，别混在一起

这是我在第三个项目才想明白的事。AGENTS.md 有不同层级：

全局放你的个人通用偏好，比如"回答尽量简洁"、“修改前先说明计划”、“默认用中文解释”。

项目级放当前项目的具体规则，比如"本项目用 pnpm"、“测试命令是 pnpm test”、“不要改 src/core/”。

别把个人口味塞进项目规则里。"我喜欢提交信息用中文"适合全局；"本仓库提交信息必须符合 Conventional Commits"适合项目级。

大项目可以在子目录放更细的规则

项目大了以后，一个根目录的 AGENTS.md 不够用。我在关键子目录各放了一份：

AGENTS.md
src/api/AGENTS.md
src/frontend/AGENTS.md
tests/AGENTS.md

根目录写全局规则，src/api/AGENTS.md 写接口规则（路由位置、返回格式、错误码），tests/AGENTS.md 写测试规则（框架、命名方式、跑单测的命令）。

这样 Codex 进入不同区域时，能读到更贴近当前位置的规则。

最好的 AGENTS.md 是被项目"养"出来的

我现在最好的那份 AGENTS.md，不是一次写完的，而是在项目使用中慢慢补出来的。

Codex 第一次犯错，我在会话里纠正它。Codex 第二次犯同样的错，我就把规则写进 AGENTS.md：

请把这条规则补进 AGENTS.md：本项目不要使用 npm install，统一使用 pnpm install。

或者：

请在 AGENTS.md 里补充：修改支付模块前必须先说明影响范围，不要直接动手。

这样下一次开新会话，Codex 不需要重新从我的口头提醒里学习。AGENTS.md 本质上就是一份持续维护的协作契约。

别把临时任务写进去

AGENTS.md 放长期规则，不放一次性需求。

"这次只改登录页"不适合写进去——这应该在当前提示词里说。"登录页组件统一放在 src/pages/login/"才适合写进去。

判断方法：下个月还成立的规则，才适合写进 AGENTS.md。

可以让 Codex 帮你生成第一版

如果不知道怎么写，让 Codex 先读项目再生成草稿：

请先只读分析这个项目，不要修改文件。

然后帮我起草一份 AGENTS.md，要求：
1. 控制在 30 行以内。
2. 只写 Codex 干活真正需要的规则。
3. 包含运行、测试、目录约定、禁止事项。
4. 不要写产品愿景和长背景。

但生成后你必须人工检查，尤其是命令。Codex 可能会猜错测试命令、包管理器或目录用途。第一版必须由你确认。

一个项目只能给 Codex 配一份文件的话

那就写 AGENTS.md。它会直接影响后面每一次协作质量。

我现在每个项目第一件事不是让 Codex 改代码，而是先让它帮我起草 AGENTS.md，我改完确认之后，再开始正式干活。这个习惯让我的返工率降了至少一半。