AGENTS.md 被 6 万多个项目采用：五家 AI 编程工具的「项目说明书」对照

先说结论

1. AGENTS.md 已经不是某一家的事了。它的官方站点写着「A simple, open format for guiding coding agents, used by over 60k open-source projects」，并且明确说明它由 OpenAI Codex、Amp、Google 的 Jules、Cursor、Factory 等共同推动。
2. 五家主流工具的现状不一样：Copilot 和 Cursor 已经原生支持 AGENTS.md，Claude Code 在 2026-09-18 的 v2.1.277 里刚加上支持（但有前提：项目里没有 CLAUDE.md 时才会读它），而 Gemini CLI 走的是自己的 GEMINI.md。
3. 最该记住的一条是优先级规则：Copilot 的文档明说「目录树里最近的那个 AGENTS.md 生效」；agents.md 官方也建议 monorepo 里每个子包放一份。这意味着你放在哪，比写什么更影响结果。

值得先知道的三个差异

在讲各家细节之前，先把这三条说清楚，因为它们直接决定你文件放哪、写什么。背景一句话：README 是给人看的（快速开始、贡献指南），而 AI 编程助手要的是另一套东西——构建和测试命令、代码风格、哪些目录别碰。在 AGENTS.md 之前每家都有自己的做法，同一份项目说明要维护四五份。

一、优先级不是「根目录赢」，而是「最近者赢」。 Copilot 文档的原文是「You can create one or more AGENTS.md files, stored anywhere within the repository. When Copilot is working, the nearest AGENTS.md file in the directory tree will take precedence」；agents.md 官方也建议 monorepo 里每个子包放一份。所以在 packages/api/ 单独放一份，比在根目录堆长文有效得多。

顺带一个容易踩空的坑：Claude Code 的顺序是 CLAUDE.md 优先、AGENTS.md 兜底。你把内容迁到 AGENTS.md 之后，只要旧的 CLAUDE.md 还留着，新文件压根不会被读——要么删掉它，要么用软链把 CLAUDE.md 指过去。

二、结构化规则和纯 Markdown 是两种东西，别盲目统一。 Cursor 的 .mdc 支持 description、globs、alwaysApply 这类元数据，能按路径自动挂载；AGENTS.md 是纯 Markdown，没有这些能力。要按路径精准生效就别迁，要跨工具复用就迁。

三、「支持 AGENTS.md」和「默认读 AGENTS.md」是两回事。 Gemini CLI 就属于前者：它默认读 GEMINI.md，要用 AGENTS.md 得自己去 .gemini/settings.json 里改配置。看到「支持」两个字，先确认默认行为。

五家工具的对照

下表以 2026-09 各家官方文档为准，其中 Claude Code 的 AGENTS.md 支持是 v2.1.277（2026-09-18） 刚加的；官方文档随时会改，转发引用前请复核。

除了上面五家，agents.md 官网列出的采用方还包括 Amp、Jules（Google）、Factory、RooCode 等——它的定位本来就是「一个谁都能用的名字和格式」，而不是某家的私有约定。

一份可以直接抄的 AGENTS.md

官方站点给的示例结构不长，重点是「写你会告诉新同事的东西」。我按这个思路整理了一版——下面的命令和目录名都是占位示例，抄之前换成你自己项目的：

# AGENTS.md

## 项目概览
- 这是什么、跑在什么运行时上、主要入口在哪个目录

## 环境与构建
- 安装：`pnpm install`
- 开发：`pnpm dev`（端口 3000）
- 构建：`pnpm build`（CI 用的是同一套命令）

## 测试
- 单测：`pnpm test`；改完必须跑，不通过不要提交
- 端到端：`pnpm e2e`（需要本地起数据库，见 docs/local-db.md）

## 代码约定
- TypeScript strict；不要用 `any`
- 组件放在 `src/components`，工具函数放在 `src/utils`
- 提交信息用中文，一行说清做了什么

## 不要动的地方
- `legacy/` 下的代码只读，改动要单独开 issue
- 不要升级 `package.json` 里锁定版本的依赖

## 提交前自检
- 跑一遍 `pnpm lint && pnpm test`
- 不要提交 `.env`、密钥、生成的产物

几个写法上的经验：命令写成可复制的一行（不要写「按常规方式构建」）；把「不要做什么」写清楚；把每次都要重复交代的事写进去——那才是这个文件存在的意义。

迁移建议（按你的工具组合选）

• 多工具混用：以 AGENTS.md 为主，.cursor/rules 留给需要路径级生效的规则。
• 只用 Claude Code：先确认没有 CLAUDE.md（或把它软链到 AGENTS.md），否则新文件永远读不到；也可以在 /config 里直接指定。
• 用 Gemini CLI：默认只能维持 GEMINI.md；愿意改配置的话，在 .gemini/settings.json 里把 context.fileName 指成 AGENTS.md 就能共用一份。
• 企业环境：如果你的 Claude Code 走 Bedrock / Vertex / Foundry，v2.1.277 这版还没有 AGENTS.md 支持，别急着迁。

这次没核实的

• OpenAI Codex 读取 AGENTS.md 的细节：本次只核到它的配置文件优先级（.codex/config.toml）与文档导航里出现 AGENTS.md，扫描范围与优先级没有找到明确文档，所以表里那格写得比别家保守。
• JetBrains / Windsurf / Cline 等这次没有逐个核，不做判断。
• 「60k+ 项目」这个数字来自 agents.md 官网自述，且它指向的是一次 GitHub 代码搜索——同一个项目的多份文件会被重复计入，所以这个数字当作「采用量」看是偏乐观的。
• 五家的行为全部取自官方文档，我没有逐家实测；文档随时会改，尤其是刚发布三天的 v2.1.277。

参考来源

• AGENTS.md 官方站点——「used by over 60k open-source projects」、共同推动方名单、Gemini CLI 的配置片段
• GitHub Copilot：Add repository custom instructions——AGENTS.md「最近者优先」的原文
• Cursor Docs：Rules——AGENTS.md 与 .cursor/rules 的关系、.mdc 扩展名要求
• Claude Code Changelog v2.1.277——AGENTS.md 支持与不支持的环境说明
• google-gemini/gemini-cli——「Context Files (GEMINI.md)」
• OpenAI Codex：Config basics——config.toml 的优先级规则