AGENTS.md

什么是 AGENTS.md

AGENTS.md 是一个放在仓库根目录的 Markdown 文件，给 AI 编码 agent 提供项目专属的操作指引——怎么装依赖、怎么跑测试、代码规范是什么、有哪些坑别踩。可以理解为「给 agent 看的 README」：README 是给人看的，AGENTS.md 是给 agent 看的。

它由 OpenAI 发起，2025 年 12 月连同 MCP 一起捐给 Linux 基金会的 Agentic AI Foundation（AAIF）。截至捐赠时已被 6 万+ 开源项目采用，Devin、GitHub Copilot、Cursor、Codex 等主流工具原生读取，是当前跨工具的事实标准。

解决什么问题

在 AGENTS.md 之前，每家 agent 工具有自己的配置文件：

• Cursor 用 .cursorrules
• Claude Code 用 CLAUDE.md
• 其它工具各有各的约定

结果是：换个工具就得重写一份项目说明，团队里用不同工具的人各维护各的。AGENTS.md 想做的是「一次编写，所有 agent 都读」——类似 .editorconfig 统一了编辑器配置那样，统一 agent 的项目上下文。

怎么写

放在仓库根目录，文件名就叫 AGENTS.md。没有强制 schema，但社区约定俗成会包含这些部分：

# AGENTS.md

## 项目结构
- `src/` 业务代码
- `tests/` 测试，用 pytest
- `scripts/` 运维脚本

## 构建与测试
- 安装依赖：`pnpm install`
- 跑测试：`pnpm test`
- 单测单文件：`pnpm test path/to/file.test.ts`
- 类型检查：`pnpm typecheck`

## 代码规范
- 用 TypeScript strict 模式
- 不要引入新的运行时依赖，先问
- 提交前必须过 lint：`pnpm lint`

## 注意事项
- 不要改 `legacy/` 目录，那是冻结代码
- 数据库迁移必须可回滚

Monorepo 的层级作用域

AGENTS.md 支持目录层级：根目录放全局约定，子包目录可以放自己的 AGENTS.md 覆盖/补充。agent 会就近读取——改 packages/api/ 下的代码时，优先读 packages/api/AGENTS.md。

2026-09 更新：Claude Code 终于读 AGENTS.md 了（但只是「回退」）

AGENTS.md 长期有个尴尬：除 Claude Code 外，主流编码 agent 都已原生读取，而 Claude Code 坚持只用自家的 CLAUDE.md。

2026-09-18 的 Claude Code v2.1.277 改变了这一点：项目根不存在 CLAUDE.md 时，Claude Code 会改为读取根目录的 AGENTS.md 作为项目指令，可在 /config → Project instructions 中关闭（来源：Claude Code Daily Briefing 2026-09-19、官方 CHANGELOG）。

三条必须知道的边界：

待核实：社区有反馈称只要仓库里存在任何 CLAUDE.md（包括空文件），AGENTS.md 就不会被读。该说法来自 bug 反馈与二手转述，未见于官方 changelog，请在你自己的仓库里实测后再调整团队规范。

对实践的影响：已经在用 AGENTS.md 的团队，现在可以少维护一份 CLAUDE.md——但别急着删，先确认回退行为符合预期。

为什么重要

• 跨工具复用：写一次，Claude Code（见上方 2026-09 更新）/ Cursor / Codex / Devin 都能读，团队成员用什么工具都行
• 降低 agent 出错率：明确告诉 agent 测试怎么跑、哪些目录别碰，比让它瞎猜强得多
• 进入中立治理：捐给 Linux 基金会后不再被单一厂商控制，长期稳定性有保障

关于「为什么给 agent 喂对上下文这么关键」，见 Context Engineering 和 Context Rot。

常见踩坑

• 写成第二份 README：AGENTS.md 是给 agent 的操作手册，重点是可执行的命令和硬性约束，不是项目介绍。别把 README 复制过来。
• 命令写得不精确：写 跑测试 没用，要写确切命令 pnpm test。agent 会照着敲，含糊的指令等于没写。
• 约束写成建议：想让 agent 别动某目录，要写「不要修改 legacy/」，而不是「尽量避免」。agent 对强约束更敏感。
• 过长：塞进几千行规范反而稀释重点（这本身就是一种 Context Rot）。挑最高频、最容易出错的点写，控制在一两屏内。
• 不更新：构建命令变了但 AGENTS.md 没改，agent 照着老命令跑就报错。把它当代码维护，跟着项目变更走。

真实案例

场景一：TypeScript + pnpm monorepo

前后端分离的 monorepo，根目录放全局约定，子包补充自己的细节。

根目录 AGENTS.md：

## 项目结构
- `apps/web/` Next.js 前端
- `apps/api/` Hono 后端
- `packages/shared/` 共享类型和工具
- `packages/db/` Drizzle ORM 及迁移

## 常用命令
- 安装依赖：`pnpm install`
- 跑全部测试：`pnpm test`
- 跑单包测试：`pnpm --filter @repo/api test`
- 类型检查：`pnpm typecheck`
- Lint：`pnpm lint`

## 代码规范
- TypeScript strict，禁止 `any`
- 跨包 import 用 `@repo/*` 别名，不要相对路径
- 新增依赖走 changeset 流程

## 注意事项
- 不要改 `packages/db/migrations/` 里已发布的迁移，新建文件
- `apps/web/public/` 下大文件走 CDN，别提交进仓库

packages/db/AGENTS.md（子包补充）：

## 数据库迁移
- 生成迁移：`pnpm db:generate`
- 每个迁移必须可回滚，配 down 文件
- 不要手写 SQL，用 Drizzle Kit 生成后再微调

agent 改 packages/db/ 时会先读子包的 AGENTS.md，不会误删已发布迁移。层级作用域的机制见上文「Monorepo 的层级作用域」一节。

场景二：从 .cursorrules 迁移到 AGENTS.md

团队原先只有 .cursorrules，用 Cursor 的人维护得勤，但用 Claude Code 和 Codex 的同事各搞各的 CLAUDE.md、codex.md，三份内容重复且不同步——.cursorrules 写了用 vitest，CLAUDE.md 还写着 jest，agent 跑错命令报错。

迁移步骤：

1. 把 .cursorrules 整理成 AGENTS.md，保留可执行命令和硬性约束，删掉冗长介绍
2. .cursorrules 改为一行 See AGENTS.md，作 Cursor 兼容期过渡
3. 删掉 CLAUDE.md 和 codex.md，让工具直接读 AGENTS.md（2026-09-18 起：Claude Code v2.1.277 已在「无 CLAUDE.md」时回退读取 AGENTS.md，这一步才真正成立；删除前请实测，避免残留空 CLAUDE.md 挡住回退）
4. CI 加一条检查：AGENTS.md 里的命令必须存在于 package.json 的 scripts，写错就报错

收益：一份文件三个工具共用，命令变更只改一处；新人不用再问「这项目用啥跑测试」。

场景三：没有 AGENTS.md 时 agent 常犯的错

• 跑错测试命令：项目用 vitest，agent 默认 npm test，而 package.json 的 test 脚本指向 jest，跑出一堆报错。AGENTS.md 写明 pnpm test 即可避免。
• 改了不该改的目录：agent 把 generated/ 下的自动生成代码当普通代码改，下次代码生成又被覆盖。一句「不要修改 generated/」就能堵住。
• import 风格不一致：项目统一用 @/ 别名，agent 写了 ../../components/Button，lint 不过。写清 import 规范后产出风格一致。
• 用错包管理器：monorepo 用 pnpm workspace，agent 跑了 npm install，生成 package-lock.json 污染仓库。写明「用 pnpm，不要用 npm/yarn」即可。

这些都是小错，但每次都得花一轮对话纠正。AGENTS.md 的价值就是把这些高频错误提前堵住——本质上是给 agent 喂对上下文，省下反复试错的 token。

与其它标准的关系

AGENTS.md 解决「agent ↔ 项目」的约定，MCP 解决「agent ↔ 工具」的连接，二者互补——一个告诉 agent 项目怎么跑，一个让 agent 能调用外部能力。

延伸阅读

• 概念：MCP / A2A / AI Agent / 多 Agent 编排
• 上下文：Context Engineering / Context Rot
• 工具：Claude Code / Cursor / Codex