Claude Code の AGENTS.md 対応｜読み込み条件と使い分け

はじめに

Claude Code は、プロジェクトごとの指示を CLAUDE.md から読み込む仕組みを採用しています。一方、他のコーディングエージェント向けに AGENTS.md を用意しているリポジトリでは、CLAUDE.md から AGENTS.md を取り込む、シンボリックリンクを張るといった回避策で、同じ指示を Claude Code にも渡してきました。

2026 年 9 月 18 日公開の Claude Code v2.1.277 で、AGENTS.md を直接読み込む機能が追加されました。ただし、AGENTS.md を置けば常に読み込まれるわけではなく、CLAUDE.md 系ファイルの有無と設定によって結果が変わります。本記事では公式ドキュメントに基づき、自分の環境で何が読み込まれるかの判断材料と、既存の指示ファイルの扱いを整理します。なお、本記事は筆者による実機検証ではなく、公式資料に基づく解説と編集上の構成例です。

結論として、Claude Code は v2.1.277 以降、作業ディレクトリとその上位に CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md がいずれもない場合に限り、既定で AGENTS.md を読み込みます。CLAUDE.md 系ファイルが 1 つでもあると AGENTS.md は読み込まれないため、両方を使う場合は CLAUDE.md からの取り込みか、Project instructions 設定の変更で対応します。すでに CLAUDE.md で AGENTS.md を取り込んでいる構成は、そのまま残して問題ありません。

Claude Code の AGENTS.md 対応で変わること

今回の対応により、他のコーディングエージェント向けに AGENTS.md だけを用意したリポジトリでも、CLAUDE.md や取り込みの記述を追加せずに Claude Code へ指示を渡せるようになりました。対応開始時点のリリースノートと現行ドキュメントでは案内が異なるため、分けて確認します。

参考: Claude Code v2.1.277 リリースノート
“in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead”
（CLAUDE.md がないプロジェクトでは、Claude Code は代わりに AGENTS.md を読み込む。）
https://github.com/anthropics/claude-code/releases/tag/v2.1.277

対応開始時点と現行ドキュメントの違い

v2.1.277 のリリースノートでは、この機能は Bedrock、Vertex、Foundry ではまだ利用できないと記載されていました。現行の公式ドキュメントでは、バージョンごとの注意が次のように案内されています。

現行ドキュメントは v2.1.281 以降への更新を案内する記載に変わっており、リリース時点の「Bedrock、Vertex、Foundry では未提供」をそのまま現在の仕様として扱うのは適切ではありません。一方で、現行ドキュメントには Vertex と Foundry についての個別の記載がなく、CHANGELOG の v2.1.280、v2.1.281 の項目にも AGENTS.md に関する明示的な記述は確認できませんでした（2026 年 9 月 24 日時点）。クラウド経由で利用している場合は、後述の確認手順で自環境の状態を確認することをおすすめします。

AGENTS.md と CLAUDE.md の読み込み条件

既定の動作では、Claude Code は CLAUDE.md 系ファイルがあるかどうかで AGENTS.md を読み込むかを決めます。判定対象は、作業ディレクトリとその上位にある CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md の 3 種類です。同じフォルダーだけでなく上位ディレクトリも判定対象で、個人用の CLAUDE.local.md も含まれます。

一方、ユーザー用の ~/.claude/CLAUDE.md、組織の管理ポリシーとして配布される CLAUDE.md、.claude/rules/ 配下のルールは判定対象外です。これらは AGENTS.md を読み込む場合も、併せて読み込まれます。

ファイル配置別に読み込まれる指示

次の表は、既定の設定（claude-md-or-agents-md）で起動した場合に、プロジェクト指示として何が読み込まれるかを配置例ごとに整理したものです。判定対象外のユーザー用・管理ポリシーの CLAUDE.md と .claude/rules/ は、どの行でも併せて読み込まれるため省略しています。

CLAUDE.md 系ファイルがない場合、作業中にサブディレクトリのファイルを Read ツールで開くと、そのサブディレクトリの AGENTS.md も読み込まれます。ただし、そのサブディレクトリ自体に CLAUDE.md 系の 3 ファイルのいずれかがある場合は対象外です。また、AGENTS.md 内の @path による取り込みは展開され、claudeMdExcludes の除外パターンも適用されます。

Project instructions 設定で変わる読み込み

既定の動作を変える場合は、セッション内で /config を開き、Project instructions の値を変更します。選択できる値は次の 4 つです。

変更は次に送信するメッセージから反映され、以降の新しいセッションにも適用されます。

設定ファイルで指定する場合は、組み込みの agents-md プラグインの設定として pluginConfigs に記述します。有効な記述先は ~/.claude/settings.json、--settings で指定したファイル、管理設定（managed settings）で、プロジェクト設定やローカル設定のファイルに書いても無視されます。リポジトリの設定ファイルでチーム全員の読み込み方式をそろえることはできないため、組織で統一する場合は管理設定、リポジトリ単位で読み込ませたい場合は後述の @AGENTS.md 取り込みが選択肢になります。

次は、ユーザー設定で両方のファイルを読み込ませる公式ドキュメントの記述例です。

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

読み込み順と矛盾した指示の扱い

見つかった指示ファイルは互いに上書きせず、連結してコンテキストに入ります。ディレクトリ階層ではファイルシステムのルート側から作業ディレクトリへ向かって並び、同じディレクトリでは CLAUDE.md の後に CLAUDE.local.md が続きます。claude-md-and-agents-md を選んだ場合は、各ディレクトリの CLAUDE.md 系ファイルの後に AGENTS.md が並びます。

ただし、後から読み込まれた指示が優先されるわけではありません。公式ドキュメントは、2 つのルールが矛盾する場合、Claude がどちらかを任意に選ぶ可能性があると説明しています。AGENTS.md と CLAUDE.md を併用する場合は、同じ項目を両方に書かず、役割を分けて矛盾を残さない運用をおすすめします。

CLAUDE.md と扱いが異なる点

設定によって直接読み込まれた AGENTS.md は、CLAUDE.md と一部の挙動が異なります。

InstructionsLoaded フックで読み込みを記録している場合や、--add-dir で共有ディレクトリの指示を読み込ませている場合は、AGENTS.md へ移行する前にこの差を確認することをおすすめします。

AGENTS.md が読み込まれない場合の確認手順

公式ドキュメントが挙げる主な原因は、作業ディレクトリやその上位にある CLAUDE.md 系ファイルです。ここでは、バージョンや設定画面など確認しやすい項目から順に整理します。

claude --version

公式ドキュメントは、v2.1.280 より前の環境での代替手段として、プロジェクト指示の内容を Claude に尋ねる方法を挙げています。ただし、Claude は作業中に AGENTS.md を開いて内容を答えることもできるため、回答だけでは起動時に読み込まれたかを区別できません。読み込みの確認は /memory の表示を基準にし、Claude の回答は補助的な材料として扱うことをおすすめします。

本章の手順と表示内容は、Claude Code 公式ドキュメント（How Claude remembers your project）に基づいています。

既存の指示ファイルをどう使い分けるか

AGENTS.md への対応後も、既存の CLAUDE.md を一律に削除する必要はありません。既存の回避策の種類、Claude 固有の指示の有無、AGENTS.md を読み込めない環境が残るかどうかで判断します。

既存の回避策ごとの変更要否

シンボリックリンクは、Claude Code の Edit・Write ツールがリンク経由の書き込みを拒否し、リンク先の AGENTS.md を編集するよう促す点に注意が必要です。Windows ではリンクの作成に管理者権限または開発者モードが必要で、Git の core.symlinks が無効なクローンでは 1 行だけのテキストファイルとしてチェックアウトされます。公式ドキュメントは、Windows の利用者がいる場合は @AGENTS.md の取り込みを使うよう案内しています。

維持・共通化・併用の判断材料

新たに構成を決める場合や、回避策を見直す場合は、次の 4 パターンから選ぶと整理しやすくなります。表の「向いているケース」と「注意点」は、公式ドキュメントの仕様をもとにした編集上の整理です。

チームで共有するリポジトリでは、CLAUDE.md から @AGENTS.md を取り込む構成が、個人の設定値（managed-only を除く）や非対応セッションの有無に左右されにくく、読み込み結果をそろえやすい構成です。Claude 固有の指示がなく、利用者全員が対応バージョンを使える場合は、AGENTS.md のみに共通化する選択肢もあります。

AGENTS.md に統一したリポジトリでは、メンバーが個人用に CLAUDE.local.md を追加すると、その人の環境では AGENTS.md が読み込まれなくなります。個人用の指示を使う場合の設定方法を、README などで共有しておくとよいでしょう。

共通指示と Claude 固有指示の記述例

以下は、運用スクリプトのリポジトリを想定した編集上の記述例です。ディレクトリ名やコマンドは例示のため、自環境に合わせて置き換えてください。どのエージェントにも共通するルールは AGENTS.md に、Claude Code の機能に依存する指示は CLAUDE.md に分けています。

AGENTS.md（各エージェント共通）

# 運用スクリプト共通ルール

## 変更範囲
- 変更対象は scripts/ と tests/ に限定する
- inventory/production/ 配下のファイルは編集しない

## 確認方法
- 変更後は make lint と make test を実行し、結果を報告する

## 機密情報
- 認証情報や API キーをコード、ログ、コミットメッセージに含めない
- .env の値を出力しない

CLAUDE.md（Claude Code 固有）

@AGENTS.md

## Claude Code
- scripts/network/ 配下を変更する場合は、plan モードで計画を提示してから編集する

CLAUDE.md の先頭に @AGENTS.md を置くと、取り込んだ AGENTS.md が先に読み込まれ、その後に Claude 固有の指示が続きます。取り込み構文はコードスパン内では展開されないため、CLAUDE.md の中では取り込み行をバッククォートで囲まずに記述します。

指示ファイルと権限制御の違い

記述例の「本番用のファイルを編集しない」「機密情報を出力しない」は、あくまで Claude への指示です。AGENTS.md と CLAUDE.md のどちらに書いても、操作を強制的に止める仕組みにはなりません。

参考: Claude Code Docs（How Claude remembers your project）
“Claude treats them as context, not enforced configuration.”
（Claude はこれらを、強制力のある設定ではなくコンテキストとして扱う。）
https://code.claude.com/docs/en/memory

特定のファイルやコマンドの操作そのものを制限したい場合は、指示ファイルではなく、権限設定の permissions.deny や PreToolUse フックで制御します。公式ドキュメントでは、組織全体でツールやパスの利用を制限する場合は管理設定の permissions.deny、行動上の指針は管理用の CLAUDE.md という役割分担が示されています。

指示ファイルは作業方針や確認方法を伝える用途、権限設定は操作の可否を決める用途に分けておくと、AGENTS.md への移行時にも役割が混ざりにくくなります。コード中の脆弱性や認証情報の混入を検査したい場合は、専用のプラグインを使う方法もあります。Claude Code 上での脆弱性スキャンは『Claude Security プラグインの使い方｜脆弱性スキャンとパッチ提案の手順』で解説しています。

まとめ

Claude Code の AGENTS.md 対応は、CLAUDE.md 系ファイルがない場合に AGENTS.md を読み込む仕組みで、既存の CLAUDE.md を置き換えるものではありません。自環境のファイル配置と設定を確認したうえで、共通指示と Claude 固有指示の置き場所を決めることが、移行判断の起点になります。

• AGENTS.md の直接読み込みは Claude Code v2.1.277 以降で対応
• 上位ディレクトリや CLAUDE.local.md があると既定では AGENTS.md を読み込まない。
• Bedrock 利用時などは v2.1.281 以降への更新が案内されている。
• Project instructions の設定はプロジェクトの設定ファイルでは無効
• 読み込みの確認は Claude の回答ではなく /memory の表示を基準にする。
• 既存の @AGENTS.md 取り込みは二重読み込みにならず、残してよい。
• 操作の制限は指示ファイルではなく権限設定やフックで行う。

以上、最後までお読みいただきありがとうございました。