AGENTS.md vs CLAUDE.md：Agent上下文文件的真正差异

如果这个月你打开了三个不同的仓库，发现每个仓库里都有不同的上下文文件（一个用 AGENTS.md，另一个用 CLAUDE.md，第三个两个都有但内容不同步），这不是你的错觉。AGENTS.md 现在已经是一个开放的、厂商中立的标准，大多数主流编程 Agent 都会读取，但 CLAUDE.md 并没有消失——知道哪个文件在哪个工具里优先级更高，可以让你避免 Agent 悄无声息地遵循过时指令的问题。

AGENTS.md 到底是什么

AGENTS.md 最早是 Sourcegraph 的 Amp 团队提出的提案，用来解决一个具体问题：每个编程 Agent 都发明了自己的上下文文件，结果团队不得不同时维护 CLAUDE.md、.cursorrules、.windsurfrules 等等，内容描述的都是同一个项目。OpenAI 和 Google 支持了这个标准，之后它被移交给了 Linux Foundation 旗下的 Agentic AI Foundation。追踪采用情况的报告显示，已有 28+ 款工具支持，超过 60,000 个开源仓库包含该文件（二手数据，精确数字未经审计，仅供参考）。

核心卖点很简单：一份 Markdown 文件，一种格式，每个 Agent 都读同一个真相来源，不用再手动同步五个文件——那些文件一周之内就会开始漂移。

哪些工具真正读取它

这才是你决定是否迁移时真正需要了解的。支持 AGENTS.md 原生的工具包括：

GitHub Copilot coding agent

列表中有一项值得注意。比较指南里流传着 Claude Code 原生读取 AGENTS.md 的报告，但我无法在 Anthropic 官方更新日志中验证这一点，所以我在此做定性描述而非事实陈述：在 Anthropic 自己的文档确认之前，请视为未确认。如果你特别依赖 Claude Code，请保留 CLAUDE.md 作为安全网。

AGENTS.md vs CLAUDE.md vs well known 目录

这三层经常被混为一谈，但它们解决的问题各不相同。

AGENTS.md 和 CLAUDE.md 竞争的是同一份工作（为编程 Agent 提供项目上下文）。well known 目录并不与两者竞争，它是一种发现机制，更像是搜索引擎查找 sitemap 的方式，而非 Agent 读取项目指令的方式。不要把这三个东西当作同一件事的三个版本。

Monorepo 优先级，每个人都搞错的part

在 monorepo 中，最近的 AGENTS.md 生效。位于 packages/api/AGENTS.md 的文件会覆盖仓库根目录为该包设置的任何内容，模式和你已经熟悉的 .eslintrc 或 .gitignore 级联完全一致。如果有适用于所有地方的上下文（如代码风格、提交规范），放在根目录。如果某个包有自己的构建工具或测试运行器，而根目录的上下文不了解，就在该包下放一个自己的文件。

CLAUDE.md 在 Claude Code 中遵循相同的嵌套模式。如果你同时保留两个文件，请让它们的优先级规则保持一致，否则你会遇到这样的问题：Agent 根据打开仓库的工具不同而行为不同。

无损现有配置地迁移

你不需要在一夜之间选一个文件删掉另一个。推荐的迁移方式是重命名加符号链接，这样仍然只认旧文件名的旧工具可以继续工作：

mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md

现在 AGENTS.md 是你的真相来源，支持开放标准的工具直接读取它，Claude Code（或其他仍然硬编码查找 CLAUDE.md 的工具）跟随符号链接获得相同内容。不再需要维护两份重复的文件，不再有两份本应一致的文档之间产生漂移。

对于 monorepo，在每个有自己上下文文件的包上都执行这个操作，而不只是放在根目录。

文件里到底该放什么

保持可操作，而非志存高远。一份读起来像使命宣言的 AGENTS.md 对 Agent 来说是死重量。值得写入的内容：

# AGENTS.md

## Setup
npm install
cp .env.example .env

## Test
npm run test -- --watch=false

## Build
npm run build

## Conventions
- All API routes live in src/app/api, not src/pages/api
- Use the shared Zod schemas in src/lib/schemas, do not redefine types inline
- Never commit generated files in dist/

Agent 可以原样执行的命令、Agent 无法从代码本身推断出的项目特定规范，而不是那些从 package.json 或文件夹结构就已经显而易见的东四。如果你的 AGENTS.md 比 README 还长，那你大概在解释一些 Agent 应该直接从代码中读取的东西。

现在就检查这三件事

从仓库根目录运行 find . -iname "AGENTS.md" -o -iname "CLAUDE.md"，看看你实际上有多少个上下文文件，以及任意两个之间是否存在分歧。

如果你运行的是 monorepo，通过在嵌套的 AGENTS.md 里放一条故意错误的指令，然后观察你的 Agent 是读取了嵌套版本还是根目录版本来确认优先级是否按你的预期工作。

如果你还没准备好完全迁移，先在一个低风险仓库上执行上述符号链接迁移，确认你的现有工具仍然能正确解析 CLAUDE.md，再动那些重要的东西。

如果你想更深入地了解 Agent 上下文和企业级 Agent 堆栈如何配合，我在我网站上做了更详细的讲解。

真正写好 AGENTS.md 内部的指令本身就是一项技能。如果你想要一个起始结构而不是空白文件，我做了一个免费的 Agent system prompt 构建器。

如果你想要在一个真实的 monorepo 上端到端地搭建这套体系，这正是我承接的工作类型。

好奇你们现在到底在偷偷同时维护多少个上下文文件。在评论区留下你的数量，以及它们是否互相一致。