Claude CodeとCodexの指示ファイルを1本にまとめる：AGENTS.mdを本文にしてCLAUDE.mdから読み込む
もくじ
同じ指示を、Claude Code 用の CLAUDE.md と Codex 用の AGENTS.md の2か所に書いていた。
2か所に書いた指示は、いつの間にか片方だけが古くなる。
僕が欲しかったのは、指示を1か所に書くだけで、両方の道具に同じ指示が届く置き方だった。
共通の指示はAGENTS.mdにまとめ、CLAUDE.mdから読み込む
Claude Code と Codex の両方に同じ指示を読ませたいなら、共通の指示は AGENTS.md に1本だけ書く。
そして同じ場所に置いた CLAUDE.md から、@AGENTS.md の1行で読み込む。
どちらもプロジェクトの最上位に置く。
AGENTS.md はたとえばこうなる。
# 作業の指示
- 変更後は、変更箇所に関係するテストを実行する
- 実行できなかったテストと、その理由を報告する
CLAUDE.md は、この1行だけでいい。
@AGENTS.md
Claude Code にしか意味のない指示があるときは、CLAUDE.md のこの行の下に足す。
つながりを図にすると、こうなる。
ただし落とし穴が1つある。
AGENTS.md の中で、さらに別のファイルを @ で読み込ませないほうがいい。
手元で試したところ、Claude Code には届いたが、Codex には届かなかった。
Codex にも読ませたい内容は、AGENTS.md の本文に直接書く。
指示ファイルが二重になると、片方だけ古くなる
1年ちょっと前、僕は Claude Code と Cursor の使い分けに迷っていた。
今は Claude Code と Codex を併用している。
道具が2つになると、指示ファイルも2つになる。
Claude Code は CLAUDE.md を読み、Codex は AGENTS.md を読むからだ。
最初はどちらにも同じことを書いていた。
実際、手元のリポジトリを見直したら、AGENTS.md のほうだけ古いまま止まっているものがあった。
あとから足したいくつかの説明が、AGENTS.md からは抜けていた。
Codex は古い地図を持たされて、それでも黙々と働いていたことになる。
きっかけは、Claude Code が AGENTS.md を読めるようになったというニュースだった。
それなら CLAUDE.md を捨てて全部 AGENTS.md にすればいいのでは、と思って公式ドキュメントを読みに行った。
僕の結論は「CLAUDE.md は捨てずに、入口として残す」だった。
Claude CodeはAGENTS.mdをどう読むか
公式ドキュメント（How Claude remembers your project）によると、Claude Code は v2.1.277 から AGENTS.md を自分で読むようになった。
ただし、いつも読むわけではない。
既定の設定では、作業ディレクトリとその上の階層に CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md のどれかがあるかで動きが変わる。
全プロジェクト共通の ~/.claude/CLAUDE.md は、この判定に数えない。
| 作業ディレクトリとその上の階層にあるもの | Claude Code が読むもの |
|---|---|
AGENTS.md だけ | AGENTS.md |
AGENTS.md と CLAUDE.md の両方 | CLAUDE.md だけ |
AGENTS.md と、@AGENTS.md と書いた CLAUDE.md | CLAUDE.md（その中で AGENTS.md も読み込まれる） |
2行目が大事だ。
両方あると、AGENTS.md は読まれない。
つまり二重に書いていた僕のリポジトリでは、Claude Code は CLAUDE.md しか見ておらず、Codex は AGENTS.md しか見ていなかった。
2人の同僚に、別々の手順書を渡していたようなものだ。
CLAUDE.mdを入口として残す理由
では CLAUDE.md を消して、AGENTS.md だけにすればいいか。
公式ドキュメントは、CLAUDE.md を消す形も認めている。
それでも僕は、@AGENTS.md の1行を持つ CLAUDE.md を残した。
1つめの理由は、Claude Code が AGENTS.md を直接読めない場面があることだ。
組み込みの agents-md プラグインを無効にしている場合や、v2.1.276 以前から上げた直後の最初のセッション（場合による）がこれにあたる。
v2.1.281 より前の版では、Amazon Bedrock 経由のセッションなども読めなかった。
CLAUDE.md から読み込む形にしておけば、こうした場面でも指示が届く。
2つめの理由は、読み込みの扱いが少し変わることだ。
Claude Code には、指示ファイルを読み込んだときに自分で決めた処理を動かせる InstructionsLoaded という仕組みがある。
AGENTS.md を直接読ませた場合、この仕組みは動かない。
CLAUDE.md から @AGENTS.md で読み込んだ場合は、ふだんどおり動く。
そして、残しておいて損がない。
公式ドキュメントには、@AGENTS.md を書いた CLAUDE.md を残しても、AGENTS.md が二重に読まれることはないと書かれている。
Codexで@の読み込みを試した
ここからが本題の落とし穴だ。
Claude Code の CLAUDE.md では、@パス と書くとそのファイルの中身が読み込まれる。
この書き方が AGENTS.md の中でも使えるなら、AGENTS.md を小さなファイルに分けられて便利だ。
ところが Codex の公式ドキュメント（AGENTS.md の説明）には、@ による読み込みの説明が見当たらない。
書いていないことは、できないのか、書き忘れなのか分からない。
分からないので、試した。
Claude Code v2.1.283 と codex-cli 0.157.1 で試した。
説明用に agents-demo/ というフォルダーを作って git で管理し、次の4つのファイルを置いた。
それぞれに別の「合言葉」を書いておき、ファイルを開かずに答えさせる。
答えられた合言葉が、最初から指示として届いていたものになる。
agents-demo/
├── AGENTS.md 合言葉その1と、@extra.md の1行
├── CLAUDE.md @AGENTS.md の1行だけ
├── extra.md 合言葉その2
└── sub/
└── AGENTS.md 合言葉その3
ルートの AGENTS.md の中身はこうだ。
# プロジェクトの指示
合言葉その1は「りんご」。
@extra.md
extra.md にはこう書いた。
合言葉その2は「みかん」。
sub/AGENTS.md にはこう書いた。
合言葉その3は「ぶどう」。
質問はどれも同じにした。
ファイルを開かずに答えてください。いま指示として見えている「合言葉」を、飾りのない1行で、読点で区切って挙げてください。見えていないものは推測しないでください。
まず Codex を、agents-demo/ で起動した。
りんご
@extra.md の先にある「みかん」が、回答に出てこない。
次に、同じ Codex を agents-demo/sub/ で起動した。
りんご、ぶどう
今度は sub/AGENTS.md の「ぶどう」が増えた。
Codex は起動したときに、プロジェクトの最上位から起動したディレクトリまでにある AGENTS.md を読み込む。
起動した場所より下にある AGENTS.md は、この読み込みに入らない。
これは公式ドキュメントに書かれている動きどおりだ。
最後に、Claude Code を agents-demo/ で起動した。
りんご、みかん
CLAUDE.md → @AGENTS.md → @extra.md と、読み込みが2段とも効いている。
並べるとこうなる。
| 道具 | 起動した場所 | 回答 |
|---|---|---|
| Codex | agents-demo/ | りんご |
| Codex | agents-demo/sub/ | りんご、ぶどう |
| Claude Code | agents-demo/ | りんご、みかん |
同じ AGENTS.md を読んでいるのに、Claude Code の回答には「みかん」が出て、Codex の回答には出なかった。
確認した公式ドキュメントにも、Codex が @ で別ファイルを読み込むという説明は無い。
だから僕は、共通の指示を @ による読み込みに頼らないことにした。
Codexの設定でCLAUDE.mdを読ませる手は採らなかった
実は Codex には、AGENTS.md の代わりに読むファイル名を足す設定がある。
~/.codex/config.toml に次のように書くと、AGENTS.md の無い場所では CLAUDE.md を読みに行く。
project_doc_fallback_filenames = ["CLAUDE.md"]
これを使えば、CLAUDE.md を本文のままにしておける。
それでも僕はこの手を採らなかった。
僕の場合、この設定は自分のパソコンの中にしか無く、消えても Codex は何も知らせず、指示を読まずに動き続けるからだ。
標準のファイル名である AGENTS.md に本文を置けば、追加の設定を管理せずに済む。
書き分けの決まり
最終的に、次の決まりに落ち着いた。
| 内容 | 書く場所 |
|---|---|
| 構成、コマンド、コーディング規約、作業の進め方など、両方に守ってほしい指示 | AGENTS.md |
| スキルやフックなど、Claude Code 固有の機能や設定を前提にした指示 | CLAUDE.md の @AGENTS.md より下 |
あわせて、次の2つを守る。
- 同じ内容を2つのファイルに書かない。迷ったら
AGENTS.mdに書く AGENTS.mdの中で@を使って別ファイルを読ませない
すでに両方のファイルがあるなら、先に中身を比べて、片方にしか無い必要な指示を AGENTS.md へ移してから重複を消す。
僕のように片方だけ古くなっていると、新しいほうを消した瞬間に指示が巻き戻る。
仕様は書いていないところで分かれる
Codex の公式ドキュメントには、@ が使えるとも使えないとも書かれていなかった。
書かれていないだけだった。
そして書かれていない部分こそ、道具ごとの違いが潜んでいる。
同じ書き方が両方の道具で使えるか迷ったら、合言葉を置いて答えさせてみる。 今回は、3つの回答を並べるだけで違いが見えた。
おわり😊
