写好 AGENTS.md，比选对 AI 编程工具重要 10 倍

先给结论

你花了三天对比 Codex CLI、Cursor、Claude Code、Gemini CLI，最后选了"最强"的那个。结果同一个需求，你同事用"最弱"的工具，产出质量甩你一条街。

区别不在工具。区别在他项目根目录有个 AGENTS.md，你没有。

我自己的项目，加了 AGENTS.md 之后，代码风格一致性问题基本消失，重构时的"误删"从每周两三次降到几乎为零。不是因为工具变强了，是因为工具终于知道我的项目长什么样。

工具只是载体，上下文才是底层逻辑

2023 年大家研究 Prompt Engineering——怎么把一句话写好。2025 年中 Shopify CEO Tobi Lütke 把概念推进到 Context Engineering——不是写好一句话，而是给工具建好一整个信息环境。到 2026 年，又有人提出 Harness Engineering，把上下文、架构约束、垃圾回收三层打包。

不管叫什么，核心逻辑没变：AI 编程工具的产出质量，70% 取决于你给了它什么上下文，20% 取决于工具本身的能力，10% 是运气。

很多人在 70% 的地方偷懒，却在 20% 的地方疯狂内卷——天天比哪个工具更强，却不肯花 30 分钟写个项目说明文件。

Karpathy 2025 年 2 月提出 Vibe Coding，意思是在氛围里沉浸编码，不仔细看生成的代码。到了 2026 年 4 月他自己承认"从没觉得自己这么落后过"。Vibe Coding 的前提是你对项目足够了解，能一眼看出问题。但如果你连项目规范都没写下来，你看不出问题，工具也猜不到规范。

AGENTS.md 是什么

一句话：项目根目录下的一个 Markdown 文件，告诉 AI 编程工具"这个项目怎么干活"。

它由 OpenAI Codex CLI 推动成为开放标准。Codex CLI 在 GitHub 上 9.5 万 Star，Gemini CLI 10.5 万——这两个最火的终端编程工具，都认这个文件。

各工具的上下文文件格式对比：

工具	配置文件	绑定工具	AGENTS.md 兼容
Codex CLI	AGENTS.md	否（标准本身）	原生支持
Cursor	.cursorrules / .cursor/rules	是	部分
Claude Code	CLAUDE.md	是	部分
Copilot	.github/copilot-instructions.md	是	部分
Gemini CLI	GEMINI.md	是	部分

问题很明显：如果你用 Cursor 写了 .cursorrules，切到 Claude Code 就得重写一遍。但如果用 AGENTS.md，一个文件适配所有——因为它是跨工具标准，其他工具要么原生支持，要么通过简单适配兼容。

怎么写：7 个核心 Section

OpenAI Codex 自己仓库的 AGENTS.md 是最好的范本（Codex CLI GitHub 9.5 万 Star）。我拆解了它的结构，提炼出 7 个核心 section：

1. 项目架构

告诉工具：这是什么项目、用了什么技术栈、核心模块在哪。不需要长篇大论，三五行足够。

1
2
3
4
5
## 项目结构
- 后端：Go + Gin，代码在 cmd/server/
- 前端：Next.js，代码在 web/
- 数据库：PostgreSQL，迁移文件在 migrations/
- 单体仓库，不要把前后端拆成独立项目

2. 编码规范

代码风格、命名约定、格式化工具。这一条直接决定生成代码的一致性。

1
2
3
4
5
## 编码规范
- Go 代码必须经过 gofmt 格式化
- 变量命名用驼峰，不用下划线
- 错误处理必须显式检查，不要忽略 err
- 提交前运行 golangci-lint

3. 测试要求

什么场景必须写测试、测试怎么跑、覆盖率要求。这是防止工具"自信地写出没有测试的代码"的关键。

1
2
3
4
5
## 测试
- 新增 API 必须有集成测试
- 运行测试：make test
- 不要用 --all-features，会增加构建时间
- 修改数据库逻辑后必须跑 migration 测试

4. 禁止操作

明确红线。不说工具就会"好心办坏事"——删文件、改配置、动数据库 schema。

1
2
3
4
5
## 禁止操作
- 不要修改 migrations/ 下已有文件，只新增
- 不要动 .env.example，它是模板
- 不要自动删除"看起来没用"的代码
- 不要升级 go.mod 里的依赖版本

5. 目录结构

比"项目架构"更细——哪些目录放什么，入口在哪。

1
2
3
4
5
## 目录约定
- cmd/ 放可执行入口，一个目录一个命令
- internal/ 放不对外暴露的业务逻辑
- pkg/ 放可被外部引用的库代码
- 测试文件和源文件放一起，不单独建 tests/ 目录

6. 部署流程

工具如果知道怎么部署，就能帮你验证改动是否打破构建。不知道就只能盲写。

1
2
3
4
5
## 部署
- 构建：docker build -t app .
- 测试：make test && make lint
- 部署前必须确认构建通过
- Dockerfile 不要用 latest 标签

7. 角色分工（多 Agent 场景）

这是进阶用法。当多个工具/角色协作时，不同角色读不同 section，减少上下文噪音。

1
2
3
4
5
## 角色
- 后端开发：读 internal/ 相关 section，关注 API 设计
- 前端开发：读 web/ 相关 section，关注组件和样式
- 测试工程师：读测试 section，关注覆盖率和集成测试
- 运维：读部署 section，关注 Dockerfile 和 CI 配置

有 vs 没有的差距

这不是玄学。同一个需求，有没有 AGENTS.md，产出质量差距肉眼可见：

维度	没有 AGENTS.md	有 AGENTS.md
代码风格	随机风格，每次生成不一样	符合项目既有规范
错误处理	忽略错误返回值，或用过度防御	遵循项目约定
重构安全性	经常误删"看起来没用"的代码	知道哪些不能碰
测试覆盖	写完功能不写测试，或写无意义测试	按项目要求补测试
上下文一致	每次对话重新解释项目背景	一劳永逸

我自己踩过最大的坑：工具"好心"帮我删了一段它认为没用的兼容代码，结果线上老接口全挂了。加了一条"不要自动删除任何看起来没用的代码"到 AGENTS.md 后，再没发生过。

常见错误

错误 1：写得像产品文档

AGENTS.md 不是给人看的 README，是给工具看的操作手册。别写"我们是一个创新驱动的敏捷团队"——写"后端用 Go，测试用 make test"。

错误 2：什么都往里塞

文件太长，工具反而抓不住重点。控制在 100 行以内，只放"不写就会出事"的规则。

错误 3：写完不更新

项目演进后规范变了，AGENTS.md 还停留在三个月前。规则：每次工具产出不符合预期时，第一反应不是换工具，而是检查 AGENTS.md 有没有覆盖这个场景。

错误 4：只放规范不放禁止操作

人记住"不能做什么"比记住"要做什么"更有效，工具也一样。禁止操作的优先级高于编码规范。

进阶：多角色协作

当项目复杂到一个 AGENTS.md 不够用时，可以利用工具的层级读取机制：

1
2
3
4
5
6
7
8
项目根目录/
├── AGENTS.md           # 全局规范
├── backend/
│   └── AGENTS.md       # 后端特定规范
├── frontend/
│   └── AGENTS.md       # 前端特定规范
└── ops/
    └── AGENTS.md       # 运维特定规范

这样不同角色进入不同目录时，只读到和自己相关的上下文。后端开发不会被前端配置干扰，运维不会被业务逻辑干扰。

这也是 Harness Engineering 的核心思想：上下文不仅要注入，还要清理。让工具在每个时刻只看到它需要的信息，而不是把整个项目扔给它。

结论

选工具是在选载体，写 AGENTS.md 是在设计信息环境。

载体可以换，环境设计的思路是通用的。今天最强的工具，半年后可能被超越；但你花时间搞清楚的 Context Engineering 方法论——怎么拆解项目规范、怎么定义禁止边界、怎么让工具理解你的上下文——这些不会过时。

先写好 AGENTS.md，再纠结用哪个工具。

如果还没有，这里有个最小可用模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# AGENTS.md

## 项目
（一句话描述项目）

## 目录结构
（核心目录及含义）

## 编码规范
（3-5 条最重要的规则）

## 测试
（怎么跑测试，什么时候必须写）

## 禁止操作
（3-5 条红线）

## 部署
（构建和验证命令）

30 分钟写完，受益远超你换三次工具。