AGENTS.md 协议：让多个 AI 工具读同一份配置

一句话结论

AGENTS.md 是社区里「一份项目配置，所有 AI 编程工具都读」的共识尝试。它本质上是 CLAUDE.md 的开放超集——目前 Cursor / Claude Code / Cline / Codex CLI 都能识别根目录的 AGENTS.md 并自动加载。写一份放项目根，就能统一所有工具的上下文，避免「Cursor 一份规则、Claude Code 一份规则」的分裂。

提出背景与社区现状

2025 年起，团队同时用 2-3 个 AI 工具成常态：Cursor 写细节、Claude Code 跑长任务、Cline 接国产模型、Codex 在 CI 里跑。但每个工具读自己格式的配置文件：

• Cursor → .cursor/rules/*.mdc
• Claude Code → CLAUDE.md
• Cline → 自己的 memory 文件
• Codex → AGENTS.md / codex.md

结果：同一份「项目约定」要维护 3-4 份，改一处忘三处，AI 行为不一致。

AGENTS.md 的初衷就是「单一事实源」——一个标准文件，谁都能读。它最早在 Codex / 开源社区成型，随后被 Cline、Claude Code（通过 CLAUDE.md 兼容读取）、Cursor（rules 可引用）陆续接纳。

AI 之家 观点：AGENTS.md 目前是「事实标准」而非「官方标准」——没有 RFC，靠工具自发兼容。但因为它向下兼容 CLAUDE.md 的写法，迁移成本几乎为零，值得采用。

标准格式与字段约定

AGENTS.md 没有强制 schema，社区约定俗成的结构：

# 项目名

一句话描述项目是什么、用什么技术栈。

## 技术栈
- 前端：Nuxt 3 + Tailwind
- 后端：Nitro server routes
- 数据库：PostgreSQL（Prisma）

## 目录结构
- pages/        页面
- components/   Vue 组件
- server/       API 路由
- prisma/       schema 与迁移

## 开发命令
- pnpm dev      开发服务器
- pnpm test     测试
- pnpm lint     lint

## 编码约定
- TypeScript strict
- 组件用 <script setup>
- 提交前必须 lint + test 通过

## 禁忌
- 不要改 migrations/ 历史文件
- 不要在前端暴露密钥
- 不要引入未声明的依赖

关键点：用 Markdown 标题分层 + 列表化，不要写大段散文。工具和人类都能读。

桥接方案：让四个工具都读它

2026-09-20 更新（含已过期部分，见下方 2026-10-12 更正）：Claude Code 的 AGENTS.md 支持是**「回退」不是「合并」——只要仓库里存在 CLAUDE.md（哪怕是空文件），AGENTS.md 就不会被加载；且 ~~Bedrock / Vertex / Foundry 上的 Claude Code 暂不支持**该回退~~ 该限制已于 v2.1.281 解除，不再成立。来源：Claude Code Changelog（v2.1.277）、Claude Code Daily Briefing 2026-09-19。

2026-09-28 / 2026-10-12 复核更正（据官方 CHANGELOG 原文，本次已再次回扫确认）：上述「平台暂不支持」已过期。v2.1.281 的条目明确写「Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled」——Bedrock / Vertex / Foundry / LLM 网关 / 关闭遥测的会话现已全部支持该回退。只回退不合并这条边界仍然成立。待核实：「空 CLAUDE.md 会挡住回退」来自社区反馈，非官方表述，建议自测。

最省事的实践（2026-09 版）：维护一份 AGENTS.md 作为单一事实源，然后：

• Claude Code：优先走「仓库里不放 CLAUDE.md」这条路，让 v2.1.277+ 直接回退读 AGENTS.md；若需要 Claude 专属补充，则保留 CLAUDE.md 并在首行写 @AGENTS.md
• Cursor：在 base.mdc 里 @import / 引用 AGENTS.md 内容

这样改约定只改 AGENTS.md，其他文件重新同步即可。

3 套现成模板

模板 1：全栈 Web 项目

# Acme Web

Nuxt 3 全栈博客，前端 Vue + Tailwind，后端 Nitro。

## 技术栈
- Nuxt 3 / Vue 3 / TypeScript strict
- PostgreSQL + Prisma
- pnpm 包管理

## 命令
- pnpm dev / pnpm test / pnpm lint / pnpm build

## 约定
- 组件 <script setup>，禁止 Options API
- API 走 server/，前端不碰 secret
- 提交前 lint + test 必须通过

## 禁忌
- 不禁用 SSR
- 不改 prisma/migrations 历史

模板 2：Python 后端 / 数据

# Data Pipeline

FastAPI 数据处理服务，Python 3.12 + uv。

## 技术栈
- FastAPI / Pydantic v2
- PostgreSQL（asyncpg）
- ruff + black

## 命令
- uv run dev / uv run test / uv run lint

## 约定
- 全类型标注 + docstring
- 用 logging 不用 print
- async/await，不阻塞事件循环

## 禁忌
- 不裸 except
- 不硬编码配置（走 env）

模板 3：多工具协作的 monorepo

# Monorepo

pnpm workspace，含 core / cli / web 三个 package。

## 结构
- packages/core      共享逻辑（TS）
- packages/cli      命令行（Node）
- apps/web          Next.js 前端

## 命令
- pnpm -r test      全量测试
- pnpm --filter web dev

## 约定
- 跨 package 改动需同时更新依赖方类型
- 统一用 changesets 管理版本

## 禁忌
- 不要跨 package 循环依赖
- 不要提交未通过 ci 的代码

常见疑问

Q：AGENTS.md 和 CLAUDE.md 冲突谁优先？ A：Claude Code 在 v2.1.277（2026-09-18）之后的行为是：根目录无 CLAUDE.md 时读 AGENTS.md；有 CLAUDE.md 时只读 CLAUDE.md，不会合并两份。所以「冲突」不存在——二选一。想让 AGENTS.md 兜底 + CLAUDE.md 补充，就在 CLAUDE.md 首行写 @AGENTS.md。

Q：旧的 .cursorrules 要留吗？ A：新版 Cursor 用 .cursor/rules/*.mdc，旧 .cursorrules 仍可兼容但建议迁移。

Q：一个项目能同时有 AGENTS.md 和 CLAUDE.md 吗？ A：能，只要内容保持同步。最省事是 symlink 或 cp。

常见误区

误区一：「写了 AGENTS.md，所有工具都会自动读」。 「能被识别」和「一定被读取」是两件事。读取时机、加载层级、是否允许嵌套目录文件、与工具自有配置文件的优先级，各工具实现并不一致。写完之后，请在每个工具里各跑一次「问它项目里有什么约定」来验证，不要把「文件放在根目录」当成生效保证。

误区二：「把规则写全就是好配置」。 恰恰相反——AGENTS.md 最常见的失败模式是太长。它会被塞进上下文，每一条都在消耗预算、稀释重点。判断标准很简单：一条规则如果模型自己就能从代码里看出来，就删掉它。 留下那些代码里看不出来的：构建与测试命令、不直观的约定、明确的禁区。

误区三：「一份文件能替代所有工具的自有配置」。 AGENTS.md 解决的是共性上下文，不是工具特有行为。涉及工具专有能力的配置（比如某个工具的权限规则或钩子）仍然要写在它自己的配置文件里。把它当「公约数层」，不要当「唯一配置源」。

误区四：「写完就不用维护了」。 它和 README 一样会腐烂。命令改名、目录重构、依赖升级之后，过期的 AGENTS.md 会让模型按错误的约定执行——比没有更糟。 建议把「AGENTS.md 是否仍然准确」放进重构的 checklist。

误区五：「工具读不到就是工具不支持」。 也存在文件位置、命名或被上层配置覆盖等原因。先验证读取路径，再下兼容性结论。

更新说明

• 2026-10-20 复核：本节为结构补充，未改动上文对协议背景、字段约定、桥接方案与模板的结论。
• 待核实：① 各工具当前对 AGENTS.md 的读取层级与优先级（会随版本变化，请以各工具官方文档为准）；② 嵌套目录下同名文件的加载行为在不同工具间的差异（本站未做跨工具实测）。
• 相关：CLAUDE.md 最佳实践 · 上下文工程 · Claude Code · Codex

相关阅读

• 工具卡：Cursor ｜ Claude Code ｜ Cline ｜ Codex CLI
• 方案：CLAUDE.md 最佳实践 ｜ Cursor Rules 最佳实践
• 评测：Claude Code 深度评测

来源说明：本文基于各工具官方文档、GitHub 仓库及 AI 之家 编辑部多工具协作实践归纳。AGENTS.md 为社区事实标准，具体兼容以各工具最新版本为准。