Claude Codeは、CLAUDE.mdが無ければAGENTS.mdを指示書にする

OpenAI Codex用に書いた指示書ファイルと、Claude Code用に書いた指示書ファイルが、同じプロジェクトに2つ並んでいる。中身はほとんど同じなのに、手順や注意点を直すたびに両方を書き換える。複数のAIコーディングツールを併用している開発者なら、この二重管理を一度は面倒に感じたことがあるはずだ。

この面倒の一部が、Claude Code側の変更で解消した。バージョン2.1.277から、Claude Codeは他のツールと共通の指示書ファイルを直接読めるようになった。CodexやCursor、Gemini CLIなど複数のツールが使う「AGENTS.md」がそれだ。公式changelogの該当項目には、「プロジェクトにCLAUDE.mdが無ければ、Claude CodeはAGENTS.mdを代わりに読む」とある。

ただし、この一文だけを読んで「AGENTS.mdを置けば両方読まれる」と考えると外れる。読まれるかどうかは、プロジェクトに何が既にあるかで決まる。

両方あるとどちらが読まれるか

Anthropicの公式ドキュメントは、リポジトリの状態ごとにClaude Codeが実際に読むファイルを次のように整理している。

この3パターンから分かるのは、既定の動作が「CLAUDE.mdが無いときだけAGENTS.mdを読む」という早い者勝ちの優先順位だという点だ。既にCLAUDE.mdがあるプロジェクトの隣にAGENTS.mdを置いても、Claude Codeはそちらを一切開かない。

自分は最初、「対応した」というニュースを見て、両方のファイルを置けば両方読まれるようになったと思い込んでいた。公式ドキュメントのこの表を読み直して、優先順位が逆向きだったと気づいた。

AGENTS.mdを直接読むにはバージョン2.1.277以降が必要で、npmレジストリの記録によれば日本時間2026年9月19日に公開されている。それより前のバージョンでは、今までどおりCLAUDE.mdしか読まない。手元のバージョンはclaude --versionで確認できる。

次に気になるのは、両方のファイルを読ませたい場合や、AGENTS.mdだけに一本化したい場合の設定だ。

両方読ませるには

Claude Codeのセッション中に/configを開くと、「Project instructions」という項目がある。次の4つの値から選ぶと、読む組み合わせを変えられる。公式ドキュメントによる説明は次のとおり。

ここで見落としやすいのが、前の表にあったCLAUDE.local.mdの扱いだ。Codex用にAGENTS.mdを書いたリポジトリに、自分専用の作業メモとしてCLAUDE.local.mdを1つ追加したとする。すると次のセッションから、既定の設定のままではAGENTS.mdが読まれなくなる。判定に数えられるファイルはCLAUDE.mdだけでなくCLAUDE.local.mdも含まれる、と公式ドキュメントは明記しているからだ。

つまり、チーム共通のAGENTS.mdが、個人用の書きかけメモを1つ足しただけで黙って無視されるようになる。CLAUDE.local.mdを残したままAGENTS.mdも読ませることはできる。「Project instructions」をclaude-md-and-agents-mdに変えればよい。設定は/configからのほか、~/.claude/settings.jsonにpluginConfigsとして書く方法もある。

ここまでは「どちらを読むか」の話だった。では実際に読まれたとき、AGENTS.mdはCLAUDE.mdとまったく同じように働くのだろうか。

CLAUDE.mdとの違い

AGENTS.mdが「Project instructions」の設定経由で読まれる場合、CLAUDE.mdと挙動が変わる点が2つある。

• セッション開始時に発火するInstructionsLoadedフックは、CLAUDE.mdでは発火するが、AGENTS.mdをこの設定経由で読んだときは発火しない。CLAUDE.mdが@AGENTS.mdで読み込んだ場合は、通常どおり発火する
• 作業ディレクトリの外にあるファイルを@pathで読み込む「外部import」は、CLAUDE.mdでは読み込みのたびに承認を求められるが、AGENTS.mdでは、そのプロジェクトで一度承認済みなら確認なしで読み込まれる

以前からsymlinkや@AGENTS.mdのimportを使ってAGENTS.mdを無理やり読ませる工夫をしていた人は、その設定を消す必要はない。CLAUDE.mdに@AGENTS.mdという一行があっても、二重に読み込まれることはない。「Project instructions」の値に関わらずそうなる、と公式ドキュメントは明記している。

ここまでの挙動は、いずれも対応バージョンのClaude Codeで動いている前提の話だ。自分の環境ではそもそも使えるのかも確認しておきたい。

使えるバージョンと環境

直接読み込みが効くのはバージョン2.1.277以降になる。/pluginから内蔵のagents-mdプラグインを無効にしているセッションでは、旧バージョンと同じくCLAUDE.mdだけになる。公式changelogの2.1.277の項目には、対応していない環境も注記されている。Amazon Bedrock・Google Vertex AI・Microsoft Foundry経由のセッションが、それにあたる。

この制限のうち、テレメトリを無効にしたセッションなど一部は、公式ドキュメントによれば最新のバージョン2.1.281で解消済みだ。npmレジストリの記録では、2.1.281は日本時間2026年9月24日未明、この記事を書いている今日の朝とほぼ同じタイミングで公開されている。Bedrock・Vertex AI・Foundry経由のセッションは、この記事の執筆時点でもまだ対応していない。

まとめ

Claude Code 2.1.277以降では、プロジェクトにCLAUDE.mdが無い場合に限り、Codexなど他ツール用のAGENTS.mdをそのまま指示書として読む。CLAUDE.mdやCLAUDE.local.mdが既にあるプロジェクトでは、既定の設定のままでは何も変わらない。

両方を読ませたい場合や、AGENTS.mdへ一本化したい場合は設定を変える。/configを開いて「Project instructions」をclaude-md-and-agents-mdなどへ変更すればよい。