AGENTS.md成跨工具标准：Claude/Cursor/Codex统一配置指南

CLAUDE.md vs AGENTS.md vs .cursorrules：该写哪个文件？

写 AGENTS.md，如果使用 Claude Code 就加一行 CLAUDE.md 桥接文件，停止编写 .cursorrules。这是 2026 年大多数团队的答案，原因归结为覆盖范围。AGENTS.md 是 Linux 基金会下 Agentic AI Foundation 托管的开放格式，已有超过 60,000 个开源项目使用。超过 20 款工具也在使用，包括 OpenAI Codex、Cursor、GitHub Copilot 的 coding agent、Gemini CLI、Windsurf 和 Zed。CLAUDE.md 与 AGENTS.md 的问题有一个真正的波折：Claude Code 原生不读取 AGENTS.md，而 Cursor 已宣布其原始规则文件为遗留文件。本指南涵盖文件选择策略；同步、审计和冲突优先级各有专页，在相关处给出链接。

CLAUDE.md、AGENTS.md 和 .cursorrules 是什么？

CLAUDE.md 是 Anthropic 为 Claude Code 提供的记忆文件：纯 Markdown 格式指令，在每个会话开始时加载，作为上下文而非强制配置，参见 Claude Code 记忆文档。它支持四个作用域级别，从组织级托管策略文件到个人级 gitignore 的 CLAUDE.local.md。

AGENTS.md 是跨供应商开放标准，在 agents.md 规范站点上描述为"给 agent 看的 README"。它是标准 Markdown，没有必填字段，agent "自动读取目录树中最近的文件，因此最近的文件优先"。

.cursorrules 是 Cursor 最初的单一文件格式，Cursor 自己的文档直言不讳："项目根目录下的 .cursorrules 文件是遗留文件将被弃用。"其继任者是 .cursor/rules 目录下的 .mdc 文件，所以 2026 年诚实的三方对比是 CLAUDE.md vs AGENTS.md vs .cursor/rules 目录。

AGENTS.md 是跨工具标准：由 Linux 基金会下 Agentic AI Foundation 托管，被超过 60,000 个开源项目使用，原生被 Codex、Cursor、Copilot 的 coding agent、Windsurf、Zed 等十几款工具读取。

Claude Code 读取 CLAUDE.md，不读取 AGENTS.md；文档记载的桥接方式是在 CLAUDE.md 第一行写 @AGENTS.md、一个符号链接，或 v2.1.213 及更高版本的 /import 命令。

.cursorrules 按 Cursor 自己的文档已是遗留状态；新规则应放在 .cursor/rules 目录下的 .mdc 文件中，后者支持 glob 作用域限定和四种规则类型。

这三个文件都是约定的静态快照；选对文件名并不能阻止内容变得过时。

CLAUDE.md vs AGENTS.md vs Cursor Rules：如何对比？

下表从实际影响日常工作的维度对比三种格式：文件放哪里、谁会读取、如何嵌套、以及可以放多少内容。每一格都可追溯至本文引用的供应商文档：Anthropic 的记忆文档、agents.md 规范和 Cursor 的规则文档。

规律：AGENTS.md 在覆盖范围上胜出，Cursor rules 在作用域精度上胜出，CLAUDE.md 在层级深度和导入功能上对以 Claude 为主的团队胜出。三家供应商都公布了数百行的体积上限；如果你超出了，可以参考如何审计臃肿的 CLAUDE.md。

2026 年哪些 Agent 读取哪个文件？

只有一个主流 agent 坚持不用标准文件，那就是 Claude Code。以下是截至 2026 年 8 月的支持矩阵，已对照供应商文档核实。

有三行与大多数现有对比文章相矛盾。首先，Anthropic 的文档明确指出："Claude Code 读取 CLAUDE.md，不读取 AGENTS.md。"文档记载的桥接方式是一个第一行为 @AGENTS.md 的 CLAUDE.md、一个符号链接，或 v2.1.213 及更高版本的 /import 命令。我们在这个仓库中就运行了这个导入，/context 确认文件在 Memory files 下加载。其次，GitHub Copilot 支持五个指令文件名：.github/copilot-instructions.md、带 applyTo glob 的路径作用域 .instructions.md 文件、任意位置有最近优先级的 AGENTS.md，以及仓库根目录的 CLAUDE.md 或 GEMINI.md。第三，Gemini CLI 默认读取 GEMINI.md，但如果你在 settings.json 的 context.fileName 下列出它就会读取 AGENTS.md。Windsurf 行追溯至 Windsurf 自己的文档，现已在 Cognition 的 Devin 文档下：AGENTS.md 文件在工作空间任意目录都会被读取，原生规则主目录已移至 .devin/rules，.windsurf/rules 保留为后备。当这些文件在同一仓库中产生分歧时，参见冲突时哪个文件优先。

层级、导入和作用域有何不同？

这是三种格式在能力上真正产生分歧的地方，而非仅仅是文件名。CLAUDE.md 有最深的机制：四层加载顺序（从托管策略到 CLAUDE.local.md）、按需加载的子目录文件、向上解析四跳的 @path 导入，以及 .claude/rules/ 目录，其中 YAML paths: frontmatter 将规则作用域限定到匹配的 glob。

AGENTS.md 刻意极简：纯 Markdown，最近优先级的嵌套文件，规范中没有其他内容。工具在其上叠加行为；Codex 拼接来自主目录、仓库根目录和工作目录的文件，默认在 32 KiB 预算（project_doc_max_bytes）处停止，并支持 AGENTS.override.md 文件用于本地覆盖，以及一个添加后备文件名的配置选项。

Cursor 介于两者之间。每个 .mdc 规则声明四种类型之一：始终应用、通过 glob 匹配应用到特定文件、根据规则描述智能应用，或手动应用。规则嵌套在子目录中；Team 和 Enterprise 计划添加的仪表板 Team Rules 优先级高于项目规则。生态正在向相同的概念（层级、glob 作用域、导入）收敛，但以不兼容的方式实现。

2026 年你应该写哪个文件？

开头所述的 CLAUDE.md vs AGENTS.md vs .cursorrules 结论，按场景重述如下：

多工具团队，2026 年默认方案：将 AGENTS.md 作为规范文件，再加一个一行式的 CLAUDE.md 桥接文件。已在运行全部三个？同步机制详见如何保持 CLAUDE.md、AGENTS.md 和 .cursorrules 同步。

仅 Claude Code 团队：原生编写 CLAUDE.md。你将获得导入、.claude/rules/ 中的路径作用域规则，以及其他格式都无法匹配的组织级托管策略分发。

重度使用 Cursor 且需要 glob 作用域规则的团队：将作用域规则放入 .cursor/rules，将共享基准放入 AGENTS.md；Cursor 两者都读取。

仍在使用 .cursorrules 的任何人：立即迁移。供应商明确表示该格式已是遗留状态，迁移方法是将内容复制粘贴到一个设为始终应用的 .cursor/rules .mdc 文件中，然后删除 .cursorrules。

无论你最终选择哪一行，记住你只是选择了一个约定的容器，内容本身仍需要有人维护使其保持真实。选择考虑今天的覆盖范围；Linux 基金会托管也使 AGENTS.md 成为两年后你仍会维护的文件的最安全选择。没有任何选择能解决的是维护本身，这是本文最后部分要讨论的。

常见问题

我应该用 CLAUDE.md 还是 AGENTS.md？

在 CLAUDE.md 与 AGENTS.md 的决策中，覆盖范围决定一切：如果有多个工具访问该仓库就用 AGENTS.md，如果 Claude Code 是你唯一的 agent 或你需要它的导入、路径作用域规则或托管策略分发就用 CLAUDE.md。两者可以干净共存：一个包含单行 @AGENTS.md 的 CLAUDE.md 可以让两个受众获得相同的指令。

Claude Code 会读取 AGENTS.md 吗？

不会。Anthropic 的记忆文档指出 Claude Code 读取 CLAUDE.md，不读取 AGENTS.md，这与几篇流行的对比文章相矛盾。文档记载的桥接方式是一行 @AGENTS.md 导入、一个从 CLAUDE.md 到 AGENTS.md 的符号链接，或自 v2.1.213 起可用的 /import 命令。

.cursorrules 已被弃用了吗？

实际上是的。Cursor 的文档说该文件"是遗留文件将被弃用"。它目前仍被读取以保持向后兼容性，但官方迁移路径是：将内容移入 .cursor/rules .mdc 文件并设为始终应用，然后删除 .cursorrules。

一个规则文件能适用于所有 agent 吗？

几乎可以。AGENTS.md 加一行式 CLAUDE.md 桥接加一条 Gemini CLI 配置行，可以覆盖 2026 年主流技术栈：Codex、Cursor、Copilot、Windsurf、Claude Code 和 Gemini CLI。一个文件做不到的是自行保持最新，这才是这类工具的真正局限。

规则文件方法在哪里失效？

以上所有内容回答的是该写哪个文件。这些文件本质上都是一个快照，由某人手动编辑，一旦保存就开始过时。2026 年的证据是双刃的。一项针对 10 个仓库 124 个 pull request 的研究发现，AGENTS.md 的存在与运行时中位数降低 28.64% 和输出 token 消耗降低 16.58% 相关。但第二项 2026 年评估发现，仓库上下文文件平均使推理成本增加超过 20%，而任务成功率没有改善。还有一项针对 2,853 个 GitHub 仓库的研究发现，上下文文件往往是一个仓库使用的唯一上下文机制。格式之争是关于文件名；失败模式是文件的新鲜度，没有文件名能解决这个问题。内容为什么会衰减参见规则文件为什么会过时，是否继续在文件上投入参见规则文件与上下文引擎。规则文件告诉 agent 你记得写下来的东西；而像 Unblocked 这样的上下文引擎则挖掘你没有写下来的东西，通过 MCP 为每个 agent 提供当前答案，而不是每个工具的快照。

选择一个文件，然后停止编写规则

对大多数团队：AGENTS.md 为规范文件，CLAUDE.md 作为一行式桥接，删除 .cursorrules。具体步骤：

在仓库根目录创建 AGENTS.md，控制在 200 行以内，包含稳定的、不可推断的事实：构建命令、约定、agent 无法从代码中推断的东西。

用第一行为 @AGENTS.md 的 CLAUDE.md 桥接 Claude Code。

将 .cursorrules 迁移到 .cursor/rules，或如果 AGENTS.md 已覆盖则删除它。

不要将每周都会变化的内容移入这些文件。所有三种格式回答的都是同一个问题，即上次某人编辑它们时什么是真的；而上下文引擎回答的是现在什么是真的。

最后一类知识——当前的且未记录在案的——是 Unblocked 从你的代码、PR、文档和对话中综合合成的，并为你的每个 agent 提供服务。如果你的规则文件不断偏离现实，可以在你选择的文件旁边试用它。

如需进一步操作，你可以考虑屏蔽此人或举报滥用。