AGENTS.md 和 CLAUDE.md：Claude Code 读哪个、怎样共用一份

什么时候用

• 仓库里已经有 AGENTS.md，想知道 Claude Code 会不会读它。[1]
• 团队同时用 Claude Code 和别的编程 Agent，想只维护一份项目指令。[1][2]
• 想分清「你写的指令文件」和「Claude 自己记的笔记」放在哪、各管什么。[1]

什么时候不用

• 想在其他工具里得到和 Claude Code 完全相同的读取规则：各工具规则不同，请看各自官方文档。[1][3]
• 想把 CLAUDE.md 当成强制约束：官方说明 Claude 把它当作上下文而不是强制配置。[1]

三种组合，Claude Code 默认读哪个

官方文档给出一张表：按仓库里有哪些指令文件，列出 Claude Code 默认读取什么。下面按原意整理。[1]

[1]

判断「有没有 CLAUDE.md」时，下面这些算数：工作目录或其上层目录里的 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md。下面这些不算，会照常和 AGENTS.md 一起加载：~/.claude/CLAUDE.md、组织的 managed CLAUDE.md、.claude/rules/ 里的文件。[1]

注意 CLAUDE.local.md 也算数：为了放个人的未提交指令而新建它，会让 Claude Code 不再自动读你的 AGENTS.md。官方给的办法是在 /config 里把 Project instructions 设为 claude-md-and-agents-md，让两类文件一起读。[1]

• claude-md-or-agents-md：默认值，有 CLAUDE.md 读 CLAUDE.md，没有才读 AGENTS.md。
• claude-md-and-agents-md：CLAUDE.md 和 AGENTS.md 一起读，同一目录里 CLAUDE.md 在前；已经被载入的 AGENTS.md 不会重复读。
• claude-md：只读 CLAUDE.md。
• managed-only：启动时只载入组织的 managed CLAUDE.md 和 auto memory；项目、本地、用户的 CLAUDE.md，.claude/rules/ 里的文件和所有 AGENTS.md 都不载入。子目录的 CLAUDE.md、.claude/rules/ 里的文件和按路径生效的规则仍按需载入。

[1]

官方还列出 Claude Code 读不了 AGENTS.md 的会话：这些会话只读 CLAUDE.md，/config 里也不显示 Project instructions。包括：Claude Code 版本低于 v2.1.277；用 /plugin 停用了读取 AGENTS.md 的内置插件；从 v2.1.276 或更早版本升级后的首个会话（有些情况下，下一次会话起才读）。另外 v2.1.281 之前，部分会话（例如用 Amazon Bedrock 或关闭了遥测）也只读 CLAUDE.md，官方建议更新。要在这些会话里让 Claude 看到 AGENTS.md，就在 CLAUDE.md 里 import 它。[1]

用 import 共用一份

想让 AGENTS.md 成为各工具共用的唯一正文，官方的写法是在它旁边放一个 CLAUDE.md，里面写一行 @AGENTS.md，再把只属于 Claude 的内容写在这一行下面。Claude 先读被引入的文件，再读其余部分。[1]

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

[1]

官方说明，已有的 @AGENTS.md 可以保留：无论 Project instructions 取哪个值，它都不会让 Claude 读两遍 AGENTS.md。如果不需要 Claude 专属内容，也可以用符号链接。[1]

ln -s AGENTS.md CLAUDE.md

[1]

• 编辑：Claude 通过链接读 CLAUDE.md，但 Edit 和 Write 工具不会写入符号链接，会提示去改链接指向的 AGENTS.md。
• Windows：官方建议改用 @AGENTS.md 的 import，因为那里创建符号链接需要管理员权限或开发者模式，Git 也可能把提交的符号链接检出成纯文本。
• 官方建议配置后在下一次会话运行 /context，确认 CLAUDE.md 出现在 Memory files 里。

[1]

import 的细节：@path 支持相对和绝对路径，相对路径按「含 import 的那个文件」所在位置解析；被引入的文件可以继续引入，最多四层。被引入的文件会和 CLAUDE.md 一起载入上下文，所以 import 只帮你整理，不会减少上下文占用。[1]

文件放哪里、作用到哪

[1]

官方不读的 AGENTS 类文件：AGENTS.local.md、AGENTS.override.md，以及 .agents/ 目录下的任何内容。[1]

AGENTS.md 官网的建议是在仓库根目录创建 AGENTS.md；大型 monorepo 可在每个子项目里再放一个。[2]

和 auto memory 有什么区别

官方把两者叫作互补的两套记忆机制：CLAUDE.md（含它的替代 AGENTS.md）是你写的指令；auto memory 是 Claude 根据你的纠正和偏好自己写的笔记。官方也提醒，两者对 Claude 都是上下文，不是强制配置。[1]

[1]

auto memory 存在 ~/.claude/projects/<project>/memory/ 下，是本机文件，不会跨机器共享。官方未写明 AGENTS.md 与 auto memory 之间有什么特殊关系；两者按上表区分即可。上表「前 200 行或 25KB」只针对 MEMORY.md：取先到的上限，超出部分启动时不载入；目录里的其他主题文件启动时不载入，Claude 需要时才按需读取。[1]

跨工具情况（只写官网明示的）

以下只摘录各家官方页面明确写出的内容，彼此规则并不相同，不能当成 Claude Code 的行为。agents.md 官网和 Cursor 官方文档都没有标版本号，以上内容以 2026-10-28 的核验日期为准；Claude Code 官方页写明的版本门槛见本文开头。[1][2][3]

• agents.md 官网：AGENTS.md 是面向编程 Agent 的开放格式，官网列出 Codex、Cursor、Gemini CLI、Zed 等工具兼容；没有必填字段，就是普通 Markdown。
• agents.md 官网：大型 monorepo 可在每个子项目放一个 AGENTS.md，Agent 读取目录树里最近的那个，最近的优先；官网同时写明用户在对话里的明确指令优先于一切。
• Cursor 官方文档：支持项目根目录和子目录里的 AGENTS.md；子目录的 AGENTS.md 在处理该目录及其子目录的文件时自动生效，与上层指令合并，更具体的优先。
• Claude Code 官方文档：AGENTS.md 的读取规则见上文，且官方说明通过设置读取的 AGENTS.md 与 CLAUDE.md 有几处不同，例如 InstructionsLoaded hook 不会触发。

[1][2][3]

各工具对 AGENTS.md 的具体读取行为和版本要求，请以各自官方文档当前页面为准。[2]