CLAUDE.md 引入 AGENTS.md，Codex 与 Claude Code 会共享同一套规则吗？

在同一仓库中交替使用 Codex 和 Claude Code，最容易被忽略的并不是规则怎么写，而是两个客户端究竟如何发现、选择并加载这些规则。即使 CLAUDE.md 与 AGENTS.md 曾经完全一致，后续维护也可能让它们悄悄分叉，因此需要先弄清导入机制与文件选择逻辑，再设计可验证的共享方案。

CLAUDE.md 引用 AGENTS.md 后，两边真的读到同一套规则吗？

一个团队交替使用 Codex 和 Claude Code。最初，维护者把测试入口、生成目录和提交要求复制到 AGENTS.md 与 CLAUDE.md，各改一次，似乎就完成了兼容。后来测试脚本更名，只更新了前者：同一个修复任务，一边运行新入口，另一边还在寻找旧命令。

这是一个教学情境，本文没有记录对应的跨客户端运行实验。但它暴露的问题很具体：团队想共享的是仍然有效的项目事实，却靠两份独立文本维持一致。把文件内容复制得一样，只能证明复制那一刻没有差异，不能保证下一次修改仍然同步。

Claude Code 官方文档已经给出了一个直接安排：在 CLAUDE.md 中导入 AGENTS.md。与此同时，Codex 的官方文档说明，每个目录最多选择一份项目指令文件，备用文件名是候选顺序，不是额外加载列表。两者结合后的结论是：可以让项目事实只有一份，但仍要分别确认两套工具怎样找到并读取它。 共用文字，不会把加载器也统一。

下面用一个小型 Python 仓库说明如何迁移。产品行为以 2026 年 9 月 16 日核验的官方文档为依据；目录、命令与迁移过程均为教学方案，没有执行客户端启动、任务验证或修改读者配置。

1. 官方支持的导入，解决的是正文重复

Claude Code 的 memory 文档专门介绍了已有 AGENTS.md 的情况：Claude Code 的常规项目入口是 CLAUDE.md，可以让它导入前者，再追加 Claude 专用说明。导入的目标在会话启动时进入上下文。这给“双份手抄”提供了一个更容易检查的替代。Claude Code：AGENTS.md 与导入

假设仓库已有以下布局，两个指令文件都位于根目录：

sample-repo/
├── AGENTS.md
├── CLAUDE.md
├── scripts/check-parser.sh
├── src/parser/
└── tests/parser/

AGENTS.md 保存共同约定，CLAUDE.md 的实际文件内容可以从这一行开始：

@AGENTS.md

这段代码块用于在文章里展示文件内容；写入 CLAUDE.md 时，导入行本身不能再被代码围栏或行内反引号包起来。官方文档指出，这些代码区域会被导入解析跳过。对于人来说，两种排版都能看懂；对于加载器来说，展示一个路径与执行一次导入是不同操作。Claude Code：导入附加文件

相对路径还以包含导入语句的文件所在位置为基准，而不是随便以启动目录解释。如果后来把入口移到另一个位置，原来的相对路径就需要重新核对。不能一边重排文件，一边假定那一行仍指向同一个对象。

这套安排减少的是共同正文的维护副本。它不说明 Codex 会解析 CLAUDE.md，也不说明 AGENTS.md 中出现的任意 @路径 都具有同样的自动展开能力。这里利用的是 Claude Code 文档明确声明的导入功能，不能把一个产品的语法当成所有 Markdown 读取器的通用协议。

2. Codex 的备用文件名，不是“再读一份”

有人可能不想保留 CLAUDE.md 这个小入口，于是转向另一个思路：既然 Codex 支持备用文件名，把 CLAUDE.md 加进配置，两端直接共用它行不行？这个选择可以讨论，但必须先读清“备用”的含义。

Codex 文档给出的项目发现顺序是：从项目根向当前工作目录逐层查找；在每一层，先考虑 AGENTS.override.md，再考虑 AGENTS.md，最后才考虑配置的备用名字。一个目录最多取一份，而不是把这些名字对应的文件全部相加。 不同目录选中的文件才继续按根到当前目录的顺序组成指令链。Codex：项目指令发现与备用文件名

下面只描述同一个目录内的选择，不能拿它代表整个项目或全局配置：

同目录内的条件	对 Codex 选择的影响
有可用的 AGENTS.override.md 与 AGENTS.md	优先选择 override，不把两份当补充段落合并
有可用的 AGENTS.md，又配置了 CLAUDE.md 备用名	选择 AGENTS.md，备用名不因此追加进去
前面的候选不存在或为空，且实际配置包含 CLAUDE.md	才可能选到该备用文件

官方说明还包含空文件会被跳过的条件，因此核对时不能只看文件名是否存在。更重要的是，这里的“最多一份”只适用于同一目录；不能误写成 Codex 整次会话只会读取一个指令文件。

假设根目录 AGENTS.md 已经存在，把 CLAUDE.md 添加到备用列表，并不能让其中的专属说明自动进入 Codex。如果维护者以为那是一个补充清单，就会出现“配置看起来写了，预期内容却没加入”的误判。继续在两个文件里补同一句话，只是在掩盖错误的加载假设。

反过来，如果团队确实把共同正文放在 CLAUDE.md，并依靠备用配置让 Codex 读取，它就多了一个环境前提：实际运行 Codex 的配置也必须包含那个文件名。开发者电脑、自动化账号和隔离工作环境是否一致，都需要验证。即使成功读到了正文，也不能据此假定 Codex 会展开其中的 Claude 专用导入语法。备用名改变的是文件发现，不等于启用另一个客户端的解释器。

3. 迁移时，先合并事实差异，再移除副本

回到教学仓库。团队真正需要共同知道的是：解析逻辑在哪里，哪条维护中的命令检查相关修改，以及哪些文件不能直接编辑。这些信息描述项目，不依赖操作者选择哪个客户端。

例如 AGENTS.md 中可以写：

解析实现位于 src/parser/，对应测试位于 tests/parser/。
局部解析修改先执行 scripts/check-parser.sh。
涉及公共行为或依赖变化时，按现有 CI 扩大检查范围。
生成目录由生成器维护；修改生成输入后重新生成，不直接补产物。
完成说明列出实际命令、结果与未覆盖部分。

这只是待迁移的示意内容。脚本是否存在、解释器是否正确、生成目录具体是哪一个，必须从实际仓库核对；不能把示意中的“生成目录”原样留下，再要求 Agent 猜路径。把同一句错话共享给两个工具，并不会因为消除了重复而变正确。

客户端专属部分则要另外判断。例如某个入口提示使用它自己的内置命令查看上下文，这条操作只适用于那个工具，就不应伪装成项目共同要求。最简单的 CLAUDE.md 可以只保留导入行；确有专属操作说明时，再放在导入之后，并标明对象。

也不要把两边对同一业务行为的矛盾藏进“专属规则”。若共同文件要求局部修改先跑解析测试，Claude 专用段却要求任何改动都跳过测试，这不是接口适配，而是项目政策冲突。维护者应先决定共同要求，再讨论工具如何完成它。否则文件看似去重了，实际执行仍会分叉。

这里有一个容易忽视的收益：命令细节继续由脚本和 CI 维护，共同文件只说明选择条件。以后脚本内部增加前置检查，两端都能通过同一个入口获得变化，不必继续把一整串实现细节复制到两份提示中。共享事实源的价值来自减少需要人工保持一致的地方，而不是追求目录里只能出现一个 Markdown 文件。

迁移时先区分共同事实、客户端入口与待裁决冲突，再决定各项内容的去向。

如果已经有两份很长的指令，直接把 CLAUDE.md 替换成导入行会很快，却可能把仅存在于其中的真实项目要求一起丢掉。较稳妥的做法，是先在一个候选改动中比较差异，而不是按文件名决定谁天然正确。

例如旧 AGENTS.md 写的是新测试脚本，旧 CLAUDE.md 仍写旧命令；这组差异应回到仓库脚本与 CI 裁决。若前者只有“运行测试”，后者记录了某个测试需要本地服务，那么后者可能保留着必要前置条件，不能因为准备删除副本就顺手删去。

比较后只需给每个差异明确去向：确认仍有效的共同要求进入 AGENTS.md；已经过期的信息删除；真正只适用于 Claude 的操作留在 CLAUDE.md。未能确认的冲突先保留为迁移阻塞，不把猜测写成两个客户端都会接受的新规则。

确认共同正文以后，再把 CLAUDE.md 改为导入加必要的客户端说明。审阅这次差异时应能看出，旧正文中的每项有效约定去了哪里。一个删掉两百行、只剩导入语句的提交，也需要说明保留下来的事实，而不能只以“文件更简洁”为验收理由。

本例选择 AGENTS.md 作共同正文，有一个直接好处：Codex 可以沿已声明的默认项目入口发现它，Claude Code 使用文档支持的导入；团队不必为了这次共享再要求每个 Codex 环境增加备用名。它仍然是两个入口，只是共同事实不再手工维护两遍。对于只需要兼容这两个工具的小仓库，这通常比先引入生成系统更容易解释和检查。

4. 同一提交、同一目录，也要开两次新会话检查

迁移后的文件静态检查，只能回答引用目标存在、旧副本是否移除、共同要求是否保留。接下来要确认的是实际客户端，而不是从代码审阅推导已经生效。

先记录准备验收的仓库提交、客户端及其版本、启动工作目录和实际配置范围。本文没有固定任何已安装 CLI 版本，因此这些都是读者需要填写的条件。若只写“用 Codex 测过”，却没有说明从根目录还是子目录启动、使用哪个配置环境，别人就可能无法复现同一条加载路径。

对 Codex，要核对当前目录路径上的候选文件，尤其是会让同目录 AGENTS.md 不被选中的 override；对 Claude Code，要核对入口里的导入是否是实际语法、相对路径是否指向预期对象。两端的用户级或其他已启用说明，也可能加入上下文。因此共同段相同不等于完整有效指令集合逐字相同。

Codex 官方文档说明指令链在运行启动时建立，并在验证和排障部分建议重启或新运行后检查。Claude 的上述导入也在会话启动时展开。检查文件修改时应使用各自新的会话；不要因为旧对话能回答一条刚刚粘贴的规则，就把它当成重新加载文件的证据。Codex：验证设置

实际检查可以分成连续的两件事。先用对应工具提供的加载记录或上下文查看入口，确认共同正文通过哪条路径进入；再给一个可还原的局部任务，观察它是否选择了预期脚本、是否报告未覆盖内容。让模型复述一句规则可以辅助定位，但不能代替加载来源与实际动作记录。这里不需要扩展成完整效果基准：本次验收回答的是迁移有没有接通、有没有改变约定，尚不能证明任务成功率提高。

如果一端失败，应先根据记录定位它是没有找到入口、选了其他候选、导入没有展开，还是读到了却没有执行。前几种需要修加载安排；最后一种未必能靠重新复制文件解决。未观察到的项目保持待确认，不能用另一端成功替它验收。

5. 保留两个简单入口，有时比消灭所有重复更好

共享不是越彻底越好。若共同内容只有几条稳定的项目事实，AGENTS.md 加一个很短的 CLAUDE.md 入口已经足够。此时新增多级导入、符号链接或自动生成步骤，会带来新的路径与运行环境要求，未必值得。

如果两个客户端的真实工作方式差别很大，也应允许专属部分存在。需要避免的是手抄同一业务事实，而不是强迫所有文字完全相同。共同约定和专属行为混在一份文件里，最后可能要写大量“如果你是某工具”的分支，反而让维护者更难判断改动影响谁。

最终交付应是一份能读懂的迁移安排：共同正文由 AGENTS.md 维护，CLAUDE.md 使用明确导入；事实差异已经裁决；两端各有待执行或已取得的加载与行为记录。备用文件名只在确有命名需求时采用，并把配置前提写清。这样，团队能少维护一份重复事实，同时保留对两套加载过程的解释能力，而不是用“共享成功”掩盖尚未核实的半边路径。