Anthropic 实际发布的内容
发布说明只有一条。其背后的文档页面题为“Claude 如何记住您的项目”，其中承载了这一机制，并以适用范围开头："Claude Code 可以将 AGENTS.md 读取为您的项目指令，因此已经为其他编码智能体设置好的仓库无需添加 CLAUDE.md、导入或设置即可直接工作。"
接下来是一个三行的表格，压缩了整个故事。一个拥有“AGENTS.md，且在您的工作目录或其上级目录中没有 CLAUDE.md 或 CLAUDE.local.md”的仓库会获得“您的 AGENTS.md”。一个拥有“AGENTS.md，且在您的工作目录或其上级目录中存在 CLAUDE.md 或 CLAUDE.local.md”的仓库会获得“仅您的 CLAUDE.md 文件”。而一个拥有“已导入 AGENTS.md 的 CLAUDE.md”的仓库会获得“您的 CLAUDE.md，其中通过导入包含了 AGENTS.md”。
生效规则被单独列出，这部分非常值得复制到您自己的笔记中。那些“生效，从而使 Claude 读取它们而不是 AGENTS.md”的文件是“工作目录或其上级任何目录中的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md”。那些“不生效，并继续与 AGENTS.md 一起加载”的文件是“您的 ~/.claude/CLAUDE.md、您组织的托管 CLAUDE.md 以及 .claude/rules/ 文件”。
Anthropic 还在一条单独的注释中用通俗的语言写下了这个陷阱："因为 CLAUDE.local.md 生效，所以在依赖 AGENTS.md 的项目中添加一个该文件以保留您自己未提交的指令，会阻止 Claude 为您读取 AGENTS.md。"
并且还有一个确认界面。当没有任何文件生效时，文档指出在会话开始时，Claude 会读取“工作目录及其上级目录中的每个 AGENTS.md 和 .claude/AGENTS.md”，并且“在交互式会话中，您会在对话中看到类似 no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md 的一行内容”。
同一周还有第二个形式相同的变化。提前一天发布的版本 2.1.275 “新增了将您在 claude.ai 账户上启用的技能和插件同步到已登录该账户的终端会话的功能；可通过 syncClaudeAiSkills: false 或 syncClaudeAiPlugins: false 选择退出。”将这两者结合起来看，模式显而易见：您的会话启动时加载的内容已经发生了两次转移，而无需任何人编辑仓库中的文件。
这改变了什么，没有改变什么
它改变了哪个文件具有权威性，而不是文件本身的内容。如果您的仓库中只有 AGENTS.md，行为会得到改善，您无需进行任何操作。如果两者都有，则完全没有变化 —— Claude 会读取它一直读取的 CLAUDE.md，而旁边的 AGENTS.md 仍然只能被其他工具读取。最容易感到意外的是那些做了最多工作的人：那些为了让两个世界保持同步而构建了导入或符号链接的人，现在有两个机制在做同一件事。
它不会改变文件的解析方式。在每个 AGENTS.md 内部，“@path 导入会被展开，claudeMdExcludes 模式适用，并且跳过项目指令的子智能体（subagents）也会跳过这些文件。”
它确实改变了您的验证方式。在四个有文档记录的地方，通过设置读取的 AGENTS.md 与 CLAUDE.md 的行为有所不同。在 /memory 和 /context 中的 Memory files（记忆文件）列表中，CLAUDE.md 会被“列出”，而 AGENTS.md 则“不列出。要确认 Claude 已读取它，请在默认值下寻找 AGENTS.md loaded 行，或询问 Claude 它的项目指令是什么。”InstructionsLoaded 钩子对前者会“触发”，对后者则“不触发”，尽管它们“对于 CLAUDE.md 导入或符号链接到的 AGENTS.md 会照常触发”。使用 --add-dir 添加的目录会加载其 CLAUDE.md，但不会加载其 AGENTS.md。并且，对工作目录之外的文件的 @path 导入“仅在您已批准此项目的外部导入时加载，无需提示”。
它也不会同时到达所有地方。文档列出了“Claude 仅读取 CLAUDE.md 文件，且 Project instructions 不会出现在 /config 设置面板中”的会话：v2.1.277 之前的版本、不“从 Anthropic 获取功能标志的会话（例如，因为您使用 Amazon Bedrock 或其他第三方提供商，或者您禁用了遥测）”、您“安装或升级后的首次会话”，以及“您或您的组织设置了 disableAllHooks or allowManagedHooksOnly，或者您禁用了内置的 agents-md 插件”的设置。
人们会从中得出什么误解，以及为什么不应该这样想
“我现在可以删除我的 CLAUDE.md 了。” 只有在仓库中没有任何 Claude 特有内容的情况下才可以。文档描述了在“您的某些会话无法直接加载 AGENTS.md”时保留 CLAUDE.md 的情况，这是一个真实的类别，而非假设。
“从现在开始，这两个文件都会被读取。” 只有在四个 Project instructions（项目指令）值之一的设置下才会如此。默认值 claude-md-or-agents-md 会读取“您的 CLAUDE.md 文件，或者当您的工作目录或其上级目录中没有 CLAUDE.md 或 CLAUDE.local.md 时，读取您的 AGENTS.md 文件”。读取两者需要设置为 claude-md-and-agents-md，它会“一起读取它们，先读取每个目录的 CLAUDE.md 文件，然后读取其 AGENTS.md”。
“我的导入现在是多余的，所以我应该把它删掉。” 文档对一种设置给出了相反的说法：对于“包含 @AGENTS.md 的 CLAUDE.md”，它指出“您可以保留它。无论您使用哪种 Project instructions 值，保留导入绝不会让 Claude 读取 AGENTS.md 两次”。
“我的设置中没有任何重复内容。” 其实有一个。对于“打印 AGENTS.md 的 SessionStart 钩子”，指导意见是“将其删除。一旦 Claude 直接读取 AGENTS.md，该钩子就会向上下文中添加第二个副本”。
“我写的文件就是上下文。” 指令文件是一个常设简报，而破坏长项目的关键问题通常与决策有关，而非惯例 —— 比如您在 6 月份决定采用两种方法中的哪一种，以及原因。这一记录值得与您的智能体在启动时读取的文件分开，这也是 为什么长上下文不是记忆 中所阐述的论点。
解决方案：确定哪个文件承载项目，然后确认会话已读取它
步骤 1：盘点生效的文件，而不仅仅是您记住的文件
检查是向上进行的，而不仅仅是在项目根目录中。遍历您的工作目录及其上方的每个目录，寻找以下三个确切的名称：CLAUDE.md、.claude/CLAUDE.md 和 CLAUDE.local.md。该路径上的任何一个文件都足以让 Claude 仅读取 CLAUDE.md 文件。
另外两个名称也值得一看，因为它们在“不读取”下有文档记录：“AGENTS.local.md、AGENTS.override.md 或 .agents/ 目录下的任何内容。”如果有人将个人覆盖拆分到其中一个文件中，它们以前就没有到达 Claude Code，现在也不会开始。
无论哪种方式，您的个人和组织级文件都是安全的。它们“不生效，并继续与 AGENTS.md 一起加载”，因此充满您自己习惯的 ~/.claude/CLAUDE.md 并不是取消仓库文件的原因。
步骤 2：有意识地选择 Project instructions 值
输入 /config 并主动设置 Project instructions（项目指令），而不是继承默认值。这四个值对应四个真实情况：当一个文件显然是项目的指令时，选择 claude-md-or-agents-md；当您想要共享文件加上 Claude 特有的补充内容时，尤其是当您保留 CLAUDE.local.md 时，选择 claude-md-and-agents-md；当项目发生分歧且共享文件仅供其他工具使用时，选择 claude-md；以及 managed-only，它在启动时“仅加载您组织的托管 CLAUDE.md 和自动记忆”。
该值也可以存在于设置中，而不是面板中，位于用户设置文件、--settings 文件或托管设置中内置 agents-md 插件 ID 的 pluginConfigs 下。对于团队来说，有一个限制很重要：“Claude Code 在项目和本地设置文件中会忽略它。”您无法在仓库内部将此选择交付给您的同事，这意味着它应该写在您的入职说明中。无论您采取哪种途径，“您的更改将从您发送的下一条消息以及每个新会话中开始应用。”
步骤 3：确认加载，然后仅删除重复的临时解决方案
启动会话并寻找那一行。在默认值且不存在生效文件的情况下，对话会显示 no CLAUDE.md found; AGENTS.md loaded:，后跟路径。如果您使用的是 claude-md-and-agents-md，或者您保留了导入，请运行 /context 并确认 CLAUDE.md 出现在 Memory files（记忆文件）下 —— 这是导入和符号链接途径的官方验证方法。
然后根据类型而不是凭直觉处理旧的临时解决方案。保留 @AGENTS.md 导入。删除仅在字面上告诉 Claude 读取另一个文件的 CLAUDE.md，因为“Claude 只有在决定打开文件时才会看到 AGENTS.md”。符号链接需要“无需操作，或删除符号链接。无论哪种方式，Claude 都会读取一次内容”。打印该文件的 SessionStart 钩子应该去掉。
如果您是第一次选择符号链接途径，有两个限制适用。编辑和写入工具“拒绝通过符号链接进行写入”，这种拒绝“会引导 Claude 改为编辑链接的目标文件 AGENTS.md”。在 Windows 上，“在其中创建符号链接需要管理员权限或开发人员模式，并且除非启用了 core.symlinks，否则 Git 会将提交的符号链接检出为纯文本文件。”
在 MemoryLake 中进行设置
指令文件回答了“您应该在这里如何工作”。它们并不是“我们决定了什么，以及何时决定”的合适归宿 —— 一旦您要同时处理两个文件名和一个设置，这种区别就会变得更加明显。一个您有意识地写入 MemoryLake 条目的独立存储，可以将决策及其原因保留在一个地方，而这并不取决于本周哪个文件名胜出。您用自己的话亲自编写这些条目。不会从 Anthropic 的文件或设置中读取、写入或删除任何内容。
步骤 1：创建 API 密钥
登录并从您的工作区设置中生成一个 API 密钥。这是您的智能体和集成所使用的凭据，因此在开始迁入任何内容之前，请先创建它。
步骤 2：上传您的第一批记忆
从那些不断需要重新解释的条目开始：架构决策、您曾经争论过的惯例、文件中看起来有些武断的限制背后的原因。将它们写成简短、独立的笔记，而不是长篇大论的文档，以便每个笔记都可以单独检索。
步骤 3：连接您的 AI 和智能体
连接您实际使用的助手和编码智能体。然后，您的常设存储就会跨工具与您同行，而无需理会每个工具本月更偏好哪一个指令文件名。
这在实践中改变了什么
它改变了入职流程。以前，“阅读 CLAUDE.md”是一个完整的指令。现在，同事可以克隆同一个仓库，运行同一个版本，却得到不同的项目指令，因为他们保留了上一个工作中的 CLAUDE.local.md。虽然不会发生报错，但得到的回答可能信息不够全面。请将预期的 Project instructions（项目指令）值写入您的设置说明中，因为仓库本身无法承载它。
它改变了“一个文件适用于所有工具”的含义。共享文件的想法仍然很好，但围绕它的规则因工具而异。例如，Kiro 的引导文档指出“AGENTS.md 文件不支持包含模式，并且总是被包含” —— 相同的文件名，不同的加载契约。如果您在多个智能体之间维护一个文件，该文件是共享的，但行为却不是，这正是 为什么智能体忽略您的指令文件 中描述的相同差距。
它改变了您迁移笔记的价值。如果您已经按照 如何将 CLAUDE.md 迁移到 AGENTS.md 中的路径将内容移入 AGENTS.md，那么移动本身仍然成立 —— 但“保留两个文件”的结局现在变成了只读取其中一个文件的情况，因此这是首先需要重新审视的步骤。
它还改变了您解读安静会话的方式。一个没有报错的会话并不等于加载了所有内容的会话 —— 这与分层设置中的模式相同，在分层设置中，解决方法是找出哪一层胜出，而不是重写内容，正如 如何调和冲突的 CLAUDE.md 层 中所述。
多个智能体读取的指令文件的最佳实践
将生效规则放在仓库中，而不是留在某个人的脑海里。在共享文件顶部附近添加一条注释，指明会取消它的文件名，可以为下一个人省去一个困惑的下午。
将常设惯例与带有日期的决策分开。惯例属于每个工具都会读取的文件。决策、权衡以及限制存在的原因属于可检索的地方，这正是 如何将项目文档转化为 AI 记忆 中所作的区别。
每个环境检查一次加载，而不是每个项目检查一次。文档记录的不可用情况是环境性的 —— 提供商、遥测、钩子策略、升级后的首次会话 —— 因此在新机器或 CI 镜像上进行一次检查即可覆盖其上的每个仓库。
保持关注启动时还会出现什么。已登录 claude.ai 账户的技能和插件现在会同步到终端会话中，这是常设行为的第二个来源，不受您仓库中任何文件的控制 —— 临近 如何在 Claude Code 会话之间共享上下文 中描述的边界。
不要假设其他智能体也发生了改变。共享文件承诺的内容与每个工具加载的内容之间的差距，正是 如何阻止 Codex 跳过 AGENTS.md 规则 中记录的相同失败案例。
最后，将该文件视为简报，而不是存档。长指令文件会与会话的其他部分争夺空间，而在压缩后能保留下来什么则是另一个问题，这在 Claude Code 自动压缩中保留什么 中有所提及。
结论
头条新闻是 Claude Code 支持读取 AGENTS.md。但真正会改变某人下午工作状态的部分是，只有当工作目录及其上级所有目录中都不存在三个特定文件名时，它才会读取它，而个人的 CLAUDE.local.md 就是其中之一，并且确认加载了哪个文件的信息存在于会话行中，而不是 /memory 列表中。
花十分钟时间：列出生效的文件，有意识地设置 Project instructions（项目指令），启动会话并阅读加载行。然后决定哪个文件是项目的常设简报 —— 并将解释该简报的决策保存在不会随文件名更改而更改的地方。