Claude CodeがAGENTS.mdを読み込むようになりました。ただし公開直後に多くのエンジニアが気づいたとおり、プロジェクトを開いた最初のセッションでは反映されません。この記事では、AGENTS.mdとは何か、なぜ初回セッションで読み込まれないのか、CLAUDE.mdとの使い分けまで整理します。
この記事の要点
- Claude CodeはAGENTS.mdを読み込みますが、新規に置いた直後の最初のセッションでは反映されず、セッションを開き直すと読み込まれるようになります。
- AGENTS.mdはClaude Code専用の仕様ではなく、複数のAIコーディングツールが共通で参照できる形式として公開されています。
- プロジェクト固有の細かいルールはCLAUDE.md、ツール横断で共有したい方針はAGENTS.mdという役割分担にすると運用がぶれません。
AGENTS.mdとは何か
AGENTS.mdは、AIコーディングエージェント向けにプロジェクトの背景やルールを書いておくための共通ファイル仕様です。特定の一社が決めたものではなく、複数の開発ツールベンダーが合意した形式として公開されています（出典: https://agents.md）。README.mdが人間向けの説明であるのに対し、AGENTS.mdはエージェント向けの指示書という位置づけです。
Claude CodeがAGENTS.mdを読み込む仕組み
Claude Codeはこれまで、プロジェクト直下のCLAUDE.mdを読み込んでコンテキストとして使ってきました。これに加えて、AGENTS.mdが存在する場合はその内容もあわせて読み込む挙動が確認できます。両方のファイルが同じプロジェクトにあってもエラーにはなりません。
CLAUDE.mdと共存させても問題ないか
結論として、共存させても動作します。ただし同じ内容を両方に書くと指示が重複し、コンテキストを無駄に消費します。役割を分けて書き分けるほうが安全です。
なぜ初回セッションでは読み込まれないのか
AGENTS.mdを新規作成した直後、最初のセッションでは指示が反映されないという報告が複数のエンジニアから上がっています。公式ドキュメントで明記された仕様ではないため、断定はできません。プロジェクト起動時のファイルスキャンや、コンテキストの初期化タイミングが関係していると考えられます。実際に、セッションを一度終了して開き直すと反映される、という報告はおおむね一致しています。
実際に試してみた
手元の小さなリポジトリにAGENTS.mdを新規作成し、簡単なルール（コミットメッセージは日本語で書く）を書いて挙動を確認しました。ファイルを作成した直後のセッションでは、その指示が反映されている様子はありませんでした。セッションを終了して開き直すと、以降のやり取りでは指示が反映されるようになりました。体感できるほどの遅延ではなく、再起動一回で解決する範囲です。
CLAUDE.mdとAGENTS.mdの使い分け
| 項目 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 対応ツール | Claude Codeのみ | 複数のAIコーディングツール |
| 主な用途 | プロジェクト固有の詳細ルール | ツール横断で共有したい基本方針 |
| 初回セッションでの反映 | 安定して反映される | 新規追加直後は反映されないことがある |
| 併用可否 | 可能 | 可能（内容の重複に注意） |
チームで使うツールがClaude Codeだけなら、無理に両方管理する必要はありません。逆に、Cursorやほかのエージェントも併用しているなら、AGENTS.mdへの一本化を検討する価値があります。
デメリット・向いていないケース
AGENTS.mdへの一本化には注意点もあります。まず、初回セッションで反映されない挙動があるため、その場ですぐ効かせたい緊急の指示には向きません。また、Claude Code固有の設定、たとえば権限まわりのルールはAGENTS.mdの範囲外です。結局、CLAUDE.mdや設定ファイル側の管理が必要になります。開発ツールがClaude Codeだけに統一されているチームなら、無理に移行せずCLAUDE.mdのみで運用したほうがシンプルです。ツールを増やす予定がないなら、様子見でも構いません。
次にやること
AGENTS.mdを試すなら、まず小さなプロジェクトに置いてみてください。ファイル作成直後と、セッションを開き直した後の両方で挙動を確認するのがおすすめです。複数のAIツールを併用しているチームは、AGENTS.mdへの移行を一度検討してみる価値があります。
よくある質問
Q. Claude CodeはAGENTS.mdをいつから読み込みますか？
A. 正確なバージョンやリリース時期は公式のリリースノートで確認する必要があります。少なくとも最近のバージョンでは読み込みが確認できています。
Q. AGENTS.mdとCLAUDE.mdは両方置いても大丈夫ですか？
A. 両方置いても動作します。ただし内容が重複すると指示が冗長になるため、役割を分けて書くのがおすすめです。
Q. AGENTS.mdが反映されない場合はどうすればいいですか？
A. まずファイルの配置場所とファイル名を確認してください。それでも反映されない場合は、セッションを一度終了してから開き直してみてください。
Q. AGENTS.mdはClaude Code以外でも使えますか？
A. はい。特定のツールに依存しない共通仕様として公開されており、複数のAIコーディングツールで参照されています。
Q. 既存のCLAUDE.mdをAGENTS.mdに書き換える必要はありますか？
A. 必須ではありません。Claude Codeしか使っていないチームなら、CLAUDE.mdのみで運用を続けても問題ありません。
Q. AGENTS.mdはどこに置けばいいですか？
A. プロジェクトのルートディレクトリに置くのが基本です。CLAUDE.mdと同じ階層に置いて動作を確認するとよいでしょう。
Q. 初回セッションで反映されないのは不具合ですか？
A. 公式に不具合として明言されているわけではありません。現時点では、報告されている挙動のひとつとして捉えるのが妥当です。