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 更新：Claude Code 的 AGENTS.md 支持是**「回退」不是「合并」**——只要仓库里存在 CLAUDE.md（哪怕是空文件），AGENTS.md 就不会被加载；且 Bedrock / Vertex / Foundry 上的 Claude Code 暂不支持该回退。来源：Claude Code Changelog（v2.1.277）、Claude Code Daily Briefing 2026-09-19。

2026-09-28 更正（据官方 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。

相关阅读

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

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