AGENTS.md vs CLAUDE.md: Where Agent Context Actually Lives

AGENTS.md vs CLAUDE.md：AI 代理上下文究竟存放在哪里

If you have opened three different repos this month and found three different context files (AGENTS.md in one, CLAUDE.md in another, both in a third, out of sync), you are not imagining the mess. AGENTS.md is now an open, vendor neutral standard that most major coding agents read, but CLAUDE.md has not gone away, and knowing which file wins where saves you from an agent quietly following stale instructions.

如果你这个月打开了三个不同的代码仓库，却发现了三种不同的上下文文件（有的用 AGENTS.md，有的用 CLAUDE.md，有的两者皆有且内容不同），这并不是你的错觉，确实是一团糟。AGENTS.md 现已成为一个开放的、厂商中立的标准，大多数主流编程代理都能读取它；但 CLAUDE.md 并没有消失，搞清楚在什么情况下该用哪个文件，能避免你的 AI 代理默默遵循过时的指令。

What AGENTS.md actually is

什么是 AGENTS.md

AGENTS.md started as a proposal from Sourcegraph’s Amp team to fix a specific problem: every coding agent invented its own context file, so teams ended up maintaining CLAUDE.md, .cursorrules, .windsurfrules, and whatever else, all describing the same project. OpenAI and Google backed the standard, and it has since moved under the Linux Foundation’s Agentic AI Foundation. Guides tracking adoption report 28+ supporting tools and more than 60,000 open source repos containing the file (secondary source, treat the exact counts as approximate, not audited). The pitch is simple: one Markdown file, one format, every agent reads the same source of truth instead of you hand syncing five files that drift within a week.

AGENTS.md 最初是 Sourcegraph 的 Amp 团队提出的一个方案，旨在解决一个具体问题：每个编程代理都发明了自己的上下文文件，导致团队最终需要维护 CLAUDE.md、.cursorrules、.windsurfrules 等各种文件，而它们描述的其实是同一个项目。OpenAI 和 Google 支持了这一标准，随后它被纳入 Linux 基金会的 Agentic AI Foundation。据追踪采用情况的指南显示，目前已有超过 28 种工具支持该标准，且有超过 60,000 个开源仓库包含此文件（此为二手来源，具体数字仅供参考，未经审计）。其核心理念很简单：一个 Markdown 文件，一种格式，让所有代理读取同一个“事实来源”，而不是让你手动同步五个在一周内就会产生偏差的文件。

Which tools actually read it

哪些工具真正支持读取它

This is the part that matters when you are deciding whether to migrate. Tools with native AGENTS.md support include: GitHub Copilot coding agent, Cursor, Amp, Factory, RooCode, Zed, Warp. Notice what is not confirmed on that list. Reports that Claude Code reads AGENTS.md natively circulate in comparison guides, but I could not verify this against Anthropic’s own changelog, so I am stating it qualitatively here rather than as fact: treat it as unconfirmed until you see it in Anthropic’s own docs, and keep CLAUDE.md in place as your safety net if you rely on Claude Code specifically.

当你决定是否迁移时，这一点至关重要。原生支持 AGENTS.md 的工具包括：GitHub Copilot 编程代理、Cursor、Amp、Factory、RooCode、Zed 和 Warp。注意列表中未确认的部分。虽然对比指南中流传着 Claude Code 原生支持 AGENTS.md 的说法，但我无法在 Anthropic 的官方更新日志中核实这一点，因此我在此仅作定性说明而非事实陈述：在 Anthropic 的官方文档确认之前，请将其视为未证实，如果你主要依赖 Claude Code，请保留 CLAUDE.md 作为你的安全保障。

AGENTS.md vs CLAUDE.md vs the well known directory

AGENTS.md vs CLAUDE.md vs “知名目录” (well-known directory)

Three layers get conflated constantly, and they solve different problems.

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

Layer	What it is	Scope
AGENTS.md	Vendor neutral project context file	Repo or monorepo package level
CLAUDE.md	Anthropic specific context file for Claude Code	Repo or monorepo package level
well known agents directory	Emerging discovery layer for agents to find capabilities at a domain	Domain or service level

层面	定义	作用域
AGENTS.md	厂商中立的项目上下文文件	仓库或 Monorepo 包级别
CLAUDE.md	Claude Code 专用的上下文文件	仓库或 Monorepo 包级别
知名代理目录	用于代理在域名下发现能力的新兴发现层	域名或服务级别

AGENTS.md and CLAUDE.md compete for the same job (project context for a coding agent). The well known directory is not competing with either, it is a discovery mechanism, closer to how a search engine finds a sitemap than to how an agent reads project instructions. Do not treat these as three versions of the same thing.

AGENTS.md 和 CLAUDE.md 在争夺同一个任务（为编程代理提供项目上下文）。而“知名目录”并不与两者竞争，它是一种发现机制，更类似于搜索引擎查找站点地图（sitemap），而不是代理读取项目指令的方式。不要把这三者视为同一事物的三个版本。

Monorepo precedence, the part everyone gets wrong

Monorepo 的优先级规则：每个人都容易搞错的地方

In a monorepo, the nearest AGENTS.md wins. A file at packages/api/AGENTS.md overrides anything set at the repo root for that package, the same pattern you already know from .eslintrc or .gitignore cascading. If you have context that applies everywhere (coding style, commit conventions), put it at root. If a package has its own build tooling or test runner that the root context does not know about, give that package its own file. CLAUDE.md follows the same nested pattern in Claude Code specifically. If you keep both files, keep the precedence rules identical across them, otherwise you get an agent that behaves differently depending on which tool opened the repo.

在 Monorepo 中，最近的 AGENTS.md 优先级最高。位于 packages/api/AGENTS.md 的文件会覆盖仓库根目录中为该包设置的任何内容，这与你已经熟悉的 .eslintrc 或 .gitignore 的级联模式相同。如果你有适用于全局的上下文（如编码风格、提交规范），请将其放在根目录。如果某个包有根目录上下文未知的构建工具或测试运行器，请为该包单独创建一个文件。CLAUDE.md 在 Claude Code 中也遵循同样的嵌套模式。如果你同时保留这两个文件，请确保它们的优先级规则一致，否则你的代理会因为打开仓库的工具不同而表现出不同的行为。

Migrating without breaking your existing setup

在不破坏现有配置的情况下进行迁移

You do not need to pick one file and delete the other overnight. The recommended migration is a rename plus a symlink, so legacy tools that only look for the old filename keep working:

你不需要在一夜之间二选一并删除另一个。推荐的迁移方式是重命名加上符号链接（symlink），这样只查找旧文件名的遗留工具仍能正常工作：

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

Now AGENTS.md is your source of truth, tools that support the open standard read it directly, and Claude Code (or any tool still hardcoded to look for CLAUDE.md) follows the symlink and gets identical content. No duplicate maintenance, no drift between two files that were supposed to say the same thing. For a monorepo, run this per package that has its own context file, not just at root.

现在 AGENTS.md 成为了你的事实来源，支持开放标准的工具会直接读取它，而 Claude Code（或任何仍硬编码查找 CLAUDE.md 的工具）会通过符号链接读取到相同的内容。无需重复维护，也不会出现两个本应内容一致的文件产生偏差的情况。对于 Monorepo，请在每个拥有独立上下文文件的包中执行此操作，而不仅仅是在根目录。

What to actually put in the file

文件里到底该写什么

Keep it operational, not aspirational. An AGENTS.md that reads like a mission statement is dead weight to an agent. What earns its place:

保持实用性，不要写成愿景声明。读起来像使命宣言的 AGENTS.md 对代理来说是累赘。真正有价值的内容包括：

# 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/

代理可以逐字执行的命令、代码本身无法推断出的项目特定约定，以及任何在 package.json 或文件夹结构中不显而易见的内容。如果你的 AGENTS.md 比 README 还长，你可能是在解释那些代理本应直接从代码中读取的内容。

Three things to check right now

现在就该检查的三件事

1. Run find . -iname "AGENTS.md" -o -iname "CLAUDE.md" from your repo root and see how many context files you actually have, and whether any two of them disagree.

2. If you run a monorepo, confirm precedence is doing what you think by putting a deliberately wrong instruction in a nested AGENTS.md and watching whether your agent picks up the nested version or the root one.

3. If you are not ready to fully migrate, do the symlink move above on one low-risk repo first and confirm your existing tooling still resolves CLAUDE.md correctly before touching anything that matters.

4. 在仓库根目录运行 find . -iname "AGENTS.md" -o -iname "CLAUDE.md"，看看你到底有多少个上下文文件，以及它们之间是否存在冲突。

5. 如果你使用 Monorepo，通过在嵌套的 AGENTS.md 中放入一条故意错误的指令，观察代理是读取嵌套版本还是根目录版本，从而确认优先级逻辑是否符合预期。

6. 如果还没准备好完全迁移，先在一个低风险的仓库上尝试上述符号链接操作，在触碰核心项目之前，确认现有工具仍能正确解析 CLAUDE.md。