Codex
一份指令文件喂两个代理:让 Claude Code 和 Codex 共用同一份说明
同时用 Claude Code 和 Codex,就得维护 CLAUDE.md 和 AGENTS.md 两份指令文件,改着改着就会漂移。作者给出一个原则:只保留一份原件,让另一边指过去,并在文件内部用条件语句和分区处理两个工具的差异。
今天就能做
- 今天就把 CLAUDE.md 精简成 @AGENTS.md 一行加 Claude 专属内容,让 AGENTS.md 成为唯一原件
- 如果原件是 CLAUDE.md,在 ~/.codex/config.toml 里加一行 project_doc_fallback_filenames = ["CLAUDE.md"]
- 在共享文件开头写明身份声明和 Codex 专属条件,用 /context 验证文件确实被加载
复制出来的文件迟早会分叉
- 复制是最省事的方案,但只要某天只改了其中一份,两边就开始不一致,往往要等代理违反规则后才发现
- 作者检查自己主目录下两份文件:md5 相同却是两个独立文件,说明一直在靠手工同步,文件里甚至写着'以后用 git 合并',等于承认了这种管理方式的代价
- 核心原则只有一条:保留一份原件,其他路径都指向它
谁有 import 能力,谁就去跟随
- Claude Code 只读 CLAUDE.md,支持 @path 导入其他文件(最多 4 跳);Codex CLI 读 AGENTS.override.md → AGENTS.md → fallback,本身不支持导入
- 所以推荐让 AGENTS.md 当原件,CLAUDE.md 只写两行:@AGENTS.md 加上 Claude 专属内容的分隔标题
- 如果你的原件已经是 CLAUDE.md,改 Codex 侧:在 ~/.codex/config.toml 里加 project_doc_fallback_filenames = ["CLAUDE.md"]
- 注意 Codex 每个目录只选一个文件,同一目录放两份不会都被读取;AGENTS.override.md 可临时覆盖某目录的规则而不动原件
第三种选择:symlink
- ln -s AGENTS.md CLAUDE.md 直接在文件系统层面解决,不用改任何工具配置
- Windows 上建 symlink 需要管理员权限或开发者模式,Claude Code 官方文档也建议 Windows 用 @AGENTS.md 导入而非 symlink
- git 以 mode 120000 存 symlink,可以提交链接本身;更稳妥的做法是仓库只放原件,链接留给各机器自己建
一份文件服务两个模型,开头先声明身份
- 在文件最顶部写明:本文件同时作为 Claude Code 的 CLAUDE.md 和 Codex 的 AGENTS.md 被读取
- 再加一条'仅当你是 Codex'的条件:把文档里的 /xxxx 技能调用读作 $xxxx,因为 Codex CLI 会把 / 开头当作斜杠命令处理
- 模型知道自己是谁,'仅当你是 Codex'这类条件真正生效,记法差异一行条件就能解决,不必拆成两份文档
能力差异:共享规则 + 分工具小节
- 记法差异用条件语句,能力差异不行。例如子代理发现指令矛盾时怎么办:Claude 的子代理与主会话有双向通道,可以现场询问;Codex 的子代理是一次性无头的,没有通道
- 正确做法:触发条件(指令与意图矛盾、约束使目标不可达、不可逆操作无事先约定)写在共享父节,处理方式分别写进 Claude 专属和 Codex 专属子节
- 把触发条件复制进每个分节,等于把重复问题搬回文件内部;分节超过三个,说明这是工具差异而非指令差异,应该对齐用法而不是继续加长文档
改完之后验证加载
- 在 Claude Code 会话里运行 /context,检查 Memory files 列表里是否出现该文件
- 最常见的失败是链接建好了、文件实际没被读取,所以最后一步的确认不能省
原文:One Instruction File, Claude and Codex
来源:DEV Community · 2026-11-19
查看原文本文由 AI 阅读原文后整理,未经人工逐字核对,内容以原文为准。
登录后可以点赞、查看和发表评论