一、引子：你的 AI 编程助手，真的“认识”你的项目吗？

用 Codex 写过几天代码的人，多半都有类似体验：刚上手那会儿，惊艳得不行——一句话就能生成一个函数、一个组件，甚至整个文件。这谁顶得住？但用着用着，问题就来了——你让它“按项目的风格写个新接口”，它写出来的东西怎么看怎么不对劲，完全不像你们项目的手笔。

问题出在哪儿？说到底，Codex 默认只知道你当前打开的这一个文件。它完全不清楚你的项目用了什么目录结构、有没有统一的错误处理规范、API 响应格式长什么样、数据库走的是 ORM 还是裸查询。这就像一个新来的工程师，你只给他看了一眼今天要改的那一行代码，然后就指望他把整个服务给重构了——这不是强人所难么。

所以，AGENTS.md 就是来兜底的。

Codex 会自动读取项目根目录下的 AGENTS.md 文件，把它当作“这个项目的全局说明书”。你写在里面的规则、约定、架构信息，会直接影响 Codex 每一次的代码生成和修改行为。

二、AGENTS.md 是什么？和 CLAUDE.md 有什么区别？

不少从 Claude Code 转过来的朋友会问：AGENTS.md 不就是 Claude Code 的那个 CLAUDE.md 吗？

这么说吧——是，也不完全是。

AGENTS.md 最大的杀手锏是层级覆盖。你可以放一个项目级的 AGENTS.md 定义全局规则，然后在 src/ 目录下再放一个 src/AGENTS.md，只覆盖前端的规则；再在 src/api/ 目录下放一个，专门约束 API 层。Codex 在操作某个文件时，会自动合并所有相关的 AGENTS.md，非常灵活。

三、AGENTS.md 怎么写？从零开始

3.1 基础结构

一个最简的 AGENTS.md 长这样：

# 项目名称
## 技术栈
- 前端：React 18 + TypeScript + Vite
- 后端：Node.js + Express + Prisma ORM
- 数据库：PostgreSQL 15
## 代码规范
- 使用函数组件 + Hooks，禁止 Class 组件
- API 响应统一格式：{ code: number, data: T, message: string }
- 错误处理使用 try-catch，禁止在业务代码中直接 throw string
- 数据库查询统一走 Prisma Service 层

就这么简单。把“这个项目是谁、它习惯怎么做事”写清楚，Codex 就能干得漂亮多了。

3.2 进阶：用好代码块和示例

Codex 对代码块的识别能力很强。与其用文字描述“API 响应格式”，不如直接甩一个例子过去：

// ✅ 正确的响应格式
interface ApiResponse {
  code: number;      // 0=成功, 其他=错误码
  data: T;
  message: string;   // 中文描述，前端直接展示
}
// ❌ 禁止的写法
{ success: true, result: null, err: "" }

这里有个关键经验：给正例 + 反例，效果远好于只干巴巴地写规范文字。Codex 本身已经在模型层面理解代码模式，给它对比示例，比写十行约束描述管用得多。

四、实战：从简单到完整

场景 1：小型个人项目（50 行以内）

# my-utils
一个轻量级工具函数库。
## 约束
- 纯函数，无副作用
- 使用 TypeScript 严格模式
- 每个函数必须有 JSDoc 注释
- 单元测试覆盖率 > 90%

场景 2：中型团队项目（10-50 个模块）

这个阶段就需要更详细的架构说明了：

# ecommerce-platform
## 项目结构
src/
├── modules/     # 业务模块（按领域拆分）
│   ├── product/
│   ├── order/
│   └── user/
├── shared/      # 共享工具和类型
└── infrastructure/  # 基础设施（DB、缓存、消息队列）
## 开发规则
1. 新功能先写类型定义，再写实现
2. Controller 层只做参数校验和路由，业务逻辑放在 Service 层
3. 所有配置项从环境变量读取，禁止硬编码
4. Git commit 使用 Conventional Commits 格式
## 数据库规范
- 禁止在循环中执行 SQL 查询（N+1 问题）
- 复杂查询使用 Prisma 的 include/select 做预加载
- 所有表必须有 created_at 和 updated_at 字段

场景 3：大型多模块项目（50+ 模块）

这时候就该用 import 拆分了：

# main-app
## 引入子规则
> 以下文件会被自动合并
- [Frontend 规则](./frontend/AGENTS.md)
- [API 规范](./api/AGENTS.md)
- [测试要求](./tests/AGENTS.md)

然后每个子目录各自维护自己的 AGENTS.md。这样不同层级的开发者只需要关注自己那一层的规则，管理起来清爽很多。

五、5 个让 AGENTS.md 更好用的技巧

5.1 用“禁止”取代“避免”

5.2 给出具体例子

Codex 是代码模型，它理解例子比理解规则好得多。每条规范如果能配上代码示例，效果能提升三倍以上。

5.3 定期更新 AGENTS.md

项目在演进，AGENTS.md 也得跟着动。建议每次做架构决策或引入新工具时，顺手更新一下 AGENTS.md。过时的规则比没有规则更糟糕——Codex 会照着过期规则生成错误的代码。

5.4 不要太长，但要够用

2000 行的 AGENTS.md 确实存在，但大多数项目 50-200 行就够用了。太长反而会让 Codex 在推理时注意力分散。浓缩出项目真正的关键约束，这才是核心能力。

5.5 测试你的 AGENTS.md

写完之后怎么知道它有没有效？很简单——开一个新对话，让它“用中文描述这个项目的架构和开发规范”。如果 AGENTS.md 写得好，它应该能准确说出你的技术栈、目录结构和关键约束。

六、常见陷阱

1. 只写技术栈不写约束：列一堆技术名但没说明怎么用，等于没写。
2. 规则过于抽象：“高质量代码”“最佳实践”这种词，对 Codex 来说毫无意义。
3. 忽略反例：只告诉它要怎么做，没告诉它不要怎么做。
4. 文件放在错误位置：AGENTS.md 必须放在项目根目录或子目录根，不能随便乱放。
5. 和 CLAUDE.md 冲突：如果同时使用 Claude Code 和 Codex，务必确保两个文件的规则一致。

七、总结

AGENTS.md 的本质不是什么神秘技术——它就是用 Codex 能理解的方式，告诉它你的项目长什么样。写好了，Codex 就不再是“一个什么都不知道的随机代码生成器”，而是一个“熟悉你项目的结对编程伙伴”。

如果你还没写过 AGENTS.md，今天就可以在项目根目录创建一个，先写 10 行技术栈和核心约束，你就会发现 Codex 的输出质量有明显的提升。

八、实际对比：有 AGENTS.md 和没有的区别

为了让你更直观地感受 AGENTS.md 的作用，看一个真实场景的对比：

场景：让 Codex 在 Express 项目中新增一个用户查询接口。

没有 AGENTS.md 时

Codex 可能会写出这样的代码：

router.get('/user', async (req, res) => {
  const user = await db.query('SELECT * FROM users WHERE id = ?', [req.query.id]);
  res.json(user);
});

看起来没问题？但在这个项目里，它踩了 3 个坑：用了 SQL 裸查询（应该走 Prisma Service）、没有错误处理、响应格式也不对。

有 AGENTS.md 时

如果 AGENTS.md 写清楚了规则，Codex 会生成这样的代码：

import { userService } from '@/services/user.service';
import { success, fail } from '@/utils/response';

router.get('/user', async (req: Request, res: Response) => {
  try {
    const user = await userService.findById(req.query.id as string);
    res.json(success(user));
  } catch (err) {
    res.json(fail(1001, (err as Error).message));
  }
});

这就是 AGENTS.md 真正价值所在——不是让 Codex 写更多代码，而是让它写对的代码。

附：一张 AGENTS.md 自检清单，写完后逐一确认：

把这 7 项写进 AGENTS.md，你的 Codex 体验会有质的提升。