协议AGENTS.md协议标准AgentOpenAI

AGENTS.md

给 AI 编码 agent 看的项目说明文件：用一个放在仓库根目录的 Markdown 文件，告诉 agent 怎么装依赖、怎么跑测试、有哪些约定。被 6 万+ 项目采用，已成跨工具事实标准。

什么是 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。

为什么重要

跨工具复用：写一次，Claude Code / 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 照着老命令跑就报错。把它当代码维护，跟着项目变更走。

与其它标准的关系

文件	给谁看	作用
README.md	人	项目介绍、快速上手
AGENTS.md	AI agent	操作指引、构建/测试/约束
MCP	agent ↔ 工具	连接外部工具和数据
A2A	agent ↔ agent	agent 之间协作

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