实际可以迁移的内容
纯文本指令内容可以完全迁移。 设置命令、代码风格、测试指令、PR 规范、架构约束——这些是大多数 CLAUDE.md 文件的大部分内容，而 AGENTS.md 也是一样：一个不需要任何特定前置元数据（frontmatter）的 Markdown 指令文件。
全局启用的作用域可以迁移，但每个工具都有其注意事项。 根目录下的 AGENTS.md 会被读取它的工具视为全局启用。Codex “在开始任何工作之前都会读取 AGENTS.md 文件”。Zed “支持将 AGENTS.md 作为个人和项目级 agent 引导的主要指令文件”。Cursor 将 AGENTS.md 列为支持嵌套子目录的“.cursor/rules 的简单替代方案”。Devin “将根据你代码库中的特定文件（包括……CLAUDE.md 和 AGENTS.md）自动拉取并更新知识（Knowledge）”。
目录级作用域可以迁移，但其运行机制有所不同。 两种格式都支持按目录配置的文件。Claude Code 会从你的工作目录向上遍历目录树，并将找到的文件拼接起来，顺序为“从文件系统根目录向下到你的工作目录”。Codex 也以相同的方向构建其链条——“Codex 从根目录向下拼接文件，用空行连接。更接近当前目录的文件会覆盖先前的引导，因为它们在合并后的提示词中出现得更晚。”Cursor 的嵌套 AGENTS.md 文件会“与父目录合并，更具体的指令具有更高的优先级”。
相同的形式，三种不同的加载器。嵌套指令是可行的，但不要假设它们的优先级语义完全相同。
一个文件，四种不同的加载器
在合并之前值得了解的是：在每个工具中，“读取 AGENTS.md”的含义略有不同，这些差异决定了你该如何组织该文件。
Codex 每次运行都会构建一次指令链。它从 Codex 主目录中的全局文件开始，然后从项目根目录向下遍历到你的工作目录，每个目录最多获取一个文件，并自上而下进行拼接。它还对整个链条设置了上限——“一旦合并后的大小达到 project_doc_max_bytes 定义的限制（默认 32 KiB），就会停止添加文件”。
Cursor 将根目录下的 AGENTS.md 视为 .cursor/rules 的免配置替代方案，嵌套文件会“与父目录合并，更具体的指令具有更高的优先级”。
Zed 将其作为个人和项目范围的主要指令文件——个人配置位于 ~/.config/zed/AGENTS.md，项目文件则在“冲突时覆盖个人 AGENTS.md”。它的项目加载器会从列表中获取第一个匹配的文件，这就是为什么过期的规则文件会产生影响的原因。
Devin 根本不把它作为指令加载；它“将根据你代码库中的特定文件（包括……CLAUDE.md 和 AGENTS.md）自动拉取并更新知识（Knowledge）”。这些知识是否能进入会话取决于固定（pinning）和触发器描述。
这四个工具的实际结论是一致的：保持根文件简短，并将具体细节推到目录级文件中。这样可以同时满足 Codex 的上限、Cursor 的优先级以及 Zed 的覆盖行为。
在连接这些文件时，有一个小小的安慰：@AGENTS.md 导入不会触发 Claude Code 的外部导入审批对话框。该对话框只有在导入“解析到工作目录之外”时才会出现——而仓库根目录下的 AGENTS.md 就在工作目录内部，因此导入加载时不会弹出提示。
无法迁移的内容——有三点，这也是你保留 CLAUDE.md 而不是直接删除它的原因：
@path 导入。Claude Code 的导入语法在 AGENTS.md 中没有对应项。
CLAUDE.local.md。在每个目录中附加在 CLAUDE.md 之后的、未提交的个人笔记。没有对应项。
任何 Claude Code 自己写入的内容。根据定义，自动生成的记忆是 Claude 特有的。
手动迁移步骤
文档中记录了两种路径。根据你是否需要 Claude 特有的内容来进行选择。
步骤 1：将共享内容移入 AGENTS.md
在仓库根目录下创建 AGENTS.md，并将所有与工具无关的内容移入其中——包括设置、测试、风格、规范。然后阅读 CLAUDE.md 中剩余的内容并进行分类：真正属于 Claude 特有的指令保留，其他内容全部移除。
在此过程中，对于那些已经不再适用的部分，请直接删除而不是迁移。合并文件是删除描述已停用服务的段落的最佳时机。
如果你的仓库中还有 .cursorrules、.windsurfrules 或 .clinerules，现在也把它们合并进来。有几个工具会原生读取 AGENTS.md，而 Zed 的项目指令加载器会从一个列表中获取第一个匹配的文件，该列表包括 .rules、.cursorrules、.windsurfrules、.clinerules、.github/copilot-instructions.md、AGENT.md、AGENTS.md、CLAUDE.md 和 GEMINI.md——因此，留下一个过期的 .cursorrules 可能会完全遮蔽你新创建的 AGENTS.md。
步骤 2：将 Claude Code 连接到同一个文件
Anthropic 的文档记录了两种方法。导入版本，允许你保留 Claude 特有的补充内容：
@AGENTS.md
## Claude Code
对 `src/billing/` 下的更改使用 plan 模式。根据文档，“Claude 会在会话开始时加载导入的文件，然后追加其余内容”。或者使用软链接（symlink），“如果你不需要添加 Claude 特有的内容”：
ln -s AGENTS.md CLAUDE.md直接来自官方文档的两点验证说明：“该命令在成功时不输出任何内容。在你的下一个会话中，运行 /context 并确认 CLAUDE.md 出现在 Memory files（记忆文件）下。”而在 Windows 上，“创建软链接需要管理员权限或开发人员模式，因此请改用 @AGENTS.md 导入方式。”
如果你不想手动分类，有一个值得了解的捷径：/init “读取 .cursor/rules/ 或 .cursorrules 中的 Cursor 规则，以及 .github/copilot-instructions.md 中的 Copilot 规则，并将相关部分合并到生成的 CLAUDE.md 中。在设置 CLAUDE_CODE_NEW_INIT=1 的情况下，/init 还会读取 AGENTS.md、.devin/rules/、.windsurf/rules/ 或 .windsurfrules 以及 .clinerules。”注意方向——这是从你的其他文件生成 CLAUDE.md，这与你在这里想要的操作相反，但这是在分类之前，在一个地方查看你积累的所有内容的最快方法。
然后检查你的大小预算。Codex “一旦合并后的大小达到 project_doc_max_bytes 定义的限制（默认 32 KiB），就会停止添加文件”，并建议在达到限制时提高限制或拆分到嵌套目录中。Claude Code 的指导原则是，文件越长消耗的上下文越多，且会降低指令遵循度。合并为一个文件是目标，但合并为一个巨大的文件则不是。
更好的方法：保持文件简短并使知识可检索
合并可以让你用一个文件代替三个文件。但这并不会改变文件本身擅长的事情——指令文件擅长的是引导方向，而不是承载你项目的推理过程。
上述每个加载器都会在每次运行时将全局启用的内容拼接进上下文中。这正是大小限制存在的原因。因此，你最希望 agent 了解的部分——为什么架构是这样的、你已经尝试并放弃了哪些方法、使某个奇怪决定变得正确的约束条件——恰恰是不属于随每次请求一起发送的文件中的内容。
这就是 MemoryLake 的用武之地：将你持久的项目知识保存在一个工具可以读取的层中，从而使 AGENTS.md 保持简短，同时使推理过程随时可用。设置只需三个步骤。
步骤 1：创建 API 密钥
登录 MemoryLake 并创建一个 API 密钥。一个凭证即可连接你使用的所有工具。
步骤 2：上传你的第一批记忆
在整理 CLAUDE.md 时，你会发现第三堆既不属于这两个文件的内容。将这些内容写成简短的条目，每条记录一个断言：
带有产生这些决策的约束条件的决策。 “写入操作通过 outbox 表进行，因为支付服务商在没有幂等键的情况下会进行重试。”规则只说明了前半部分；只有这个版本才能阻止 agent 再次提出替代方案。
已被排除的方法。 这是价值最高的一类，也是代码库中任何地方都不存在的内容。
跨仓库知识。 适用于你拥有的每个项目的领域词汇和标准。AGENTS.md 在设计上是针对单个仓库的；而这并非如此。
你进行过不止一次的纠正。 如果你已经说过两次，说明这是一个缺失的条目——而且原因应该写在它旁边。
步骤 3：连接你的 AI 和 agent
连接你使用的工具。MemoryLake 可以通过 MCP 和 API 访问，因此支持原生 MCP 的 agent（包括 Claude Code、Codex 和 OpenClaw）可以通过指向 MCP 服务器进行连接，而其他助手则通过 API 读取相同的记忆。
三个客观的局限性。MemoryLake 并不是 AGENTS.md 的替代品——你仍然需要该文件，上述合并工作本身就非常有价值。它只保存你或你的 agent 写入其中的内容，因此步骤 2 是手动的。此外，指令文件是上下文，而不是强制性的配置；记忆层并不能改变这一点。
这在实践中带来了什么改变
一个文件，且保持准确。 三个逐渐偏离的副本合而为一，原生读取 AGENTS.md 的工具无需针对每个工具进行单独配置即可直接使用。
Claude Code 保持正常工作。 @AGENTS.md 导入是官方文档中记录的、只有一行且可逆。你无需在标准和现有设置之间做出妥协。
大小限制不再是问题。 对于引导方向来说，32 KiB 非常宽裕，但对于知识库来说则远远不够。将这两项工作分开，可以让你保持在限制之内。
过期的规则文件不会遮蔽你的新文件。 一旦你了解了 Zed 会从其列表中获取第一个匹配的文件，删除 .cursorrules 就成了迁移工作的一部分，而不是三周后让你百思不得其解的谜团。
接入新工具零成本。 列表中的大多数工具已经可以读取 AGENTS.md，而任何不读取它的工具都可以通过 MCP 读取记忆层——这种形式在在 Cursor 和 Claude Code 之间共享同一个记忆中有所介绍。
合并指令文件的最佳实践
将共享内容放在 AGENTS.md 中，将 Claude 特有的内容放在导入行下方。 这是官方文档推荐的模式，它能保持 diff 的可读性。
合并后删除 .cursorrules 和 .windsurfrules。 否则，采用“首次匹配”的加载器可能会选中过期的文件。
如果你有 Claude 特有的指令，请使用导入方式，而不是软链接。 在 Windows 上，无论如何都请使用导入方式。
使用 /context 进行验证。 在你的下一个会话中，确认 CLAUDE.md 出现在 Memory files（记忆文件）下，而不是凭空假设。
保持在限制大小之内，并在文件增大时按目录拆分。 Codex 的默认限制是整个链条 32 KiB；嵌套文件是官方文档中推荐的保持在限制之内的方法。
不要将文档直接粘贴进去。 而是引用它们。随着代码的变化，副本会变得过时——这也是为什么 agent 会忽略你编写的指令文件背后的核心观点。
将其提交到 git。 这正是让合并后的文件成为团队资产而非个人资产的关键。
不要将原因写在文件中，而是放在可检索的层中。 AGENTS.md 负责引导方向，记忆负责论证。这种分离才能让文件保持足够简短，从而真正被遵循。
结论
AGENTS.md 凭借其“平淡无奇”赢得了胜利：一个名称可预测的开放 Markdown 文件，已有超过 60k 个仓库和大多数主流 agent 在读取它。合并到该文件可以消除三个文件各自演变、逐渐偏离的问题，而 Claude Code——这个读取 CLAUDE.md 而不是 AGENTS.md 的著名工具——在官方文档中提供了一个一行的桥接方法，即通过 @AGENTS.md 导入，或者在没有 Claude 特有内容需要添加时使用软链接。
合并无法解决的是指令文件本就不该承担的部分。每个加载器都会在每次请求时发送全局启用的内容，这就是为什么它们都有大小限制。因此，将共享指令移入 AGENTS.md，将 Claude 特有的内容保留在导入行下方，删除过期的规则文件，并将你的决策、约束条件和被否决的方法放在你的 agent 可以查询的层中。一个能被切实遵循的简短文件，胜过一个会被截断的冗长文件。