CLAUDE.mdとAGENTS.md、どっちを正本にする？｜設定ファイルの使い分けを整理

2026年6月23日

こんにちは、みのり（@minori_aimama）です。本業・育児の合間にAI×ブログ副業に挑戦中です。

前回、Claude CodeとCodexを同じフォルダで使うために「正本を1つにした」話を書きました。

そもそもCLAUDE.mdとAGENTS.mdは何が違うのか

どちらも「AIに読ませるルールを書くファイル」ですが、対象が違います。

ファイル	読むツール	位置づけ
`CLAUDE.md`	Claude Code	Claude Code専用の設定ファイル
`AGENTS.md`	Codex・Cursorなど	複数のAIコーディングツールで使われ始めている共通フォーマット

AGENTS.md は対応ツールが増えてきていますが、「業界標準」と言い切るにはまだ早い段階です。標準化されつつある形式、くらいの位置づけだと思っています。

ここで大事なのは、Claude Codeは AGENTS.md を直接読まないということ。Anthropicの公式ドキュメントでも、Claude Codeが読むのは CLAUDE.md で、AGENTS.md を使う場合は CLAUDE.md から読み込ませる形が案内されています。

一方で、Codex側には CLAUDE.md を読ませるオプションがあります。

つまり、どちらを正本にしても、もう片方のツールに読ませるための橋渡しが必要になる。これが「じゃあどっちを正本にするか」という話になった理由です。

判断軸は「Claude Codeだけか、他のAIも使うか」

正本をどちらに置くかは、使い方で分かれました。

使い方	おすすめの正本	理由
Claude Codeだけで使う	`CLAUDE.md`	Claude Codeが直接読む。他に配慮する必要がない
他のAIツールも一緒に使う	`AGENTS.md`	対応ツールにそのまま流用しやすい

Claude Codeしか使わないなら、CLAUDE.mdに全部書けばそれで済みます。わざわざAGENTS.mdに寄せる必要はない。

他のツールも使うなら、AGENTS.mdを正本にした方が扱いやすそうでした。対応ツールが増えたときに設定を足し直す手間が少ない。

CLAUDE.mdを正本にする方法もある

Codex側には、プロジェクトの指示ファイルとしてAGENTS.mdがなければ CLAUDE.md を読ませるという設定もあります。

具体的にはCodexの設定ファイル ~/.codex/config.toml に以下を追加するだけです。

project_doc_fallback_filenames = ["CLAUDE.md"]

Claude Codeは最初からCLAUDE.mdを読むので、橋渡しは不要。Codex側だけ設定すればいい。

Claude Codeがメインで、ちょこっとCodexも触りたいという場合にはこれで十分かと思います。私も最初はこれを設定しました。

AGENTS.mdを正本にする方法

こちらは、CLAUDE.md に @AGENTS.md と書くだけです。

@AGENTS.md

この1行で、Claude Codeは AGENTS.md の内容を読んでくれます。

Codex側は AGENTS.md をそのまま読むので、設定は要りません。両方のツールが同じ内容を参照する状態がこれだけで作れました。

ルールを書き換えるときは AGENTS.md だけを直せばいい。CLAUDE.md と AGENTS.md に同じ内容を書く必要がないので、片方だけ古くなる問題を避けられます。

CLAUDE.mdは消せないけど、1行で済む

AGENTS.mdを正本にしたからといって、CLAUDE.mdは消せません。Claude Codeが読むのはCLAUDE.mdだけなので、ファイルは残す必要があります。

正直、親フォルダにも各プロジェクトフォルダにもAGENTS.mdとCLAUDE.mdの両方があるのは邪魔だなと思いました。

ただ、CLAUDE.mdの中身は @AGENTS.md の1行で済みます。しかも、この1行の下にClaude Code固有の指示を足すこともできる。共通ルールはAGENTS.mdに書いて、Claude Codeだけに伝えたいことはCLAUDE.mdに追加する。入口だけど、拡張ポイントにもなります。

管理コストはほぼゼロだったので、「邪魔だけど実害はない」という結論になりました🫠

私がAGENTS.md正本にした理由

最初はCLAUDE.mdを正本にして、Codex側の config.toml でCLAUDE.mdを読ませていました。

途中で引っかかったのが、config.toml がPCに紐づくということ。PCが変わるたびに設定を入れ直す運用は、引き継ぎ漏れの元でした。

他の人の事例を調べたときも、AGENTS.mdに寄せているケースが多かったです。対応ツールが増えてきているので、今後を考えても扱いやすそうだと判断しました。

まとめると、こういう理由です。

判断ポイント	内容
PC設定に依存しない	AGENTS.mdなら `config.toml` 不要
対応ツールに流用しやすい	新しいツールが出ても正本を使い回せる
橋渡しが簡単	CLAUDE.mdに `@AGENTS.md` の1行で済む