Claude Code の AGENTS.md 対応を整理｜CLAUDE.md との優先順位と /config の 4 設定

まず、既存の CLAUDE.md を残すか判断する

Claude Code v2.1.277 以降は、作業ディレクトリと上位階層に CLAUDE.md 系のファイルが無い場合、AGENTS.md を直接読み込みます。両方あれば既定では CLAUDE.md 系が選ばれ、変更する場所は /config の Project instructions です。

ただし、対応したからといって CLAUDE.md を一律に削除する必要はありません。個人用の CLAUDE.local.md、利用する接続先、既存の import によって、残したほうがよい構成もあります。

本記事は 2026 年 9 月 21 日に確認した公式資料を基に、「自分のリポジトリでは何が読まれるか」と移行手順を整理します。指示に何を書くかは CLAUDE.md のベストプラクティス、書き始めるための例は CLAUDE.md テンプレート集 を参照してください。

v2.1.277 で変わったことと対象外の接続先

v2.1.277 では、既存の AGENTS.md を import なしで読む経路が追加されました。公式 changelog の説明は次のとおりです。

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config (not yet on Bedrock, Vertex or Foundry)

日本語にすると、「CLAUDE.md が無いプロジェクトでは AGENTS.md を読み、/config の Project instructions で変更できる。ただし Bedrock・Vertex・Foundry は未対応」という内容です。

Enterprise 導入などで接続先を統一しているチームは、ファイルを整理する前に利用環境を確認してください。対象外の環境でも、CLAUDE.md からの import は引き続き選べます。

自分のリポジトリでは何が読まれるか

次の表は、直接読み込みを利用できる環境で、既定値 claude-md-or-agents-md を使った場合の整理です。公式のメモリ仕様 に基づきます。

「CLAUDE.md が無い」は、リポジトリのルートだけを見た判定ではありません。Claude Code を起動した場所と、その上のディレクトリも調べます。

~/.claude/CLAUDE.md・組織の managed CLAUDE.md・.claude/rules/ の 3 つは、AGENTS.md を使うと無視されるという意味ではありません。既定設定では AGENTS.md と併せて読み込まれ、プロジェクトの判定を妨げないという区別です。

判定対象のファイルが無ければ、開始時には作業ディレクトリと上位階層の AGENTS.md・.claude/AGENTS.md が読み込まれます。親ディレクトリに置いた指示も含まれるため、ルートのファイルを改名しただけで移行が終わったと判断しないでください。

読み込みを会話の表示で確認する

リポジトリを整理したら、対象の作業ディレクトリで対話セッションを開始し、既定設定の読み込み表示を確認します。公式資料に掲載された表示例です。

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

見るのは AGENTS.md loaded: とファイルのパスです。設定経由で直接読んだ AGENTS.md は、/memory や /context の Memory files 一覧には出ません。一覧に無いことは、読み込み失敗を意味しません。

既定以外の設定を使う場合などは、Claude に「このプロジェクトの指示内容を要約してください」と質問する方法も公式資料で案内されています。ファイル固有の規約が回答に含まれるかを確認してください。ただし、規約を読み込めたことと、すべての出力が規約を守ることは別であり、テストやレビューは引き続き必要です。

CLAUDE.local.md を追加すると AGENTS.md が読まれなくなる

共通規約を AGENTS.md に集約した後、自分用の指示だけを CLAUDE.local.md に書く場面を考えます。既定設定では、その追加によって「CLAUDE.md 系がある」と判定されるため、AGENTS.md は直接読み込みの対象外です。

同じリポジトリでも、個人用ファイルを持つメンバーだけ読み込み対象が違う状態になり得ます。Git の差分に共通規約の変更が無くても起こる点に注意してください。公式ドキュメント は、この場合に claude-md-and-agents-md を選ぶ方法を案内しています。

FIXIT

自分用のメモを足しただけで、共通ルールを読まなくなるの？

Hayate

既定ではそうです。個人用の指示も使うなら、両方を読む設定に揃えるのが早いです。

/config で読み込み対象を選ぶ

Claude Code のセッション内で /config を開き、Project instructions を変更します。公式の設定表 には、次の値が定義されています。

選ぶ場面は本記事の運用提案です。managed-only は、起動時にプロジェクト・ローカル・ユーザーの CLAUDE.md、.claude/rules/、すべての AGENTS.md を除外します。ただし、サブディレクトリの CLAUDE.md・.claude/rules/ やパス指定のルールは、該当ファイルを読む際に読み込まれます。「セッション全体で managed 指示以外を一切読まない」という設定ではありません。

settings.json に書く場合は配置先を選ぶ

設定ファイルでは pluginConfigs の agents-md@builtin に指定します。次は両方を読む例です。

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

配置先は ~/.claude/settings.json、--settings で渡すファイル、または managed settings です。プロジェクト設定の .claude/settings.json とローカル設定の .claude/settings.local.json に書いても、この項目は無視されます。チームのリポジトリに追加するだけでは全員へ適用されません。

変更は次のメッセージと新しいセッションから適用されます。権限設定も併せて整理するなら、Claude Code の permissions 設定 で設定ファイルの役割を確認してください。

CLAUDE.md と扱いが異なる箇所を確認する

AGENTS.md の直接読み込みは、CLAUDE.md のファイル名を置き換えただけの機能ではありません。運用で確認したい違いを、公式の比較表 に沿って整理します。

読み込み監査を InstructionsLoaded に依存しているチームは、移行前に記録方法を確認してください。CLAUDE.md が AGENTS.md を import する場合や、AGENTS.md への symlink になっている場合には、通常どおりフックが発火します。

共通ルールを作業ディレクトリの外に置く構成では、この差が承認の求められ方に現れます。承認画面が出ないことを「承認なしで読める」と解釈してはいけません。

Project instructions が表示されない場合

公式資料の利用できない条件 に該当すると、CLAUDE.md 系だけが読み込まれ、/config に Project instructions が表示されません。リポジトリを変更する前に、次の条件を順に確かめてください。

接続先については、changelog が Bedrock・Vertex・Foundry の未対応を明記しています。バージョンだけを揃えても、全員が直接読み込めるとは限りません。

組織の設定を変えずに共通規約を使うなら、CLAUDE.md からの import が選択肢になります。承認済みの設定を維持したまま、読み込み経路をチーム内で共有してください。

既存の import・symlink・フックを整理する

すでに AGENTS.md を読ませていた場合は、現在の方法ごとに後始末が異なります。公式の移行案内 を基にした判断表です。

フックを削除する前には、代わりの読み込み経路を確認してください。直接読めない環境では先に import を用意します。

symlink は閲覧と編集で扱いが異なります。Claude Code の Edit・Write はリンク越しの書き込みを拒否するため、編集先はリンクの実体である AGENTS.md です。また Windows を使うメンバーがいる場合は、権限や Git の core.symlinks に依存しない import を公式資料が勧めています。

モノレポでは起動場所と Read した場所を確かめる

Claude Code は起動時に上位階層の指示を探すだけでなく、サブディレクトリ内のファイルを Read ツールで開いた際にも、そのディレクトリの AGENTS.md を読み込みます。既定設定では、そのサブディレクトリ自身に CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md が無いことが条件です。探索条件の出典 を確認してください。

たとえば packages/api/AGENTS.md があっても、セッション開始時にすべてのパッケージの指示がまとめて読まれるとは限りません。ルートから起動する場合とパッケージ内で起動する場合を分け、実際に編集する場所の規約を確認してください。

Codex・Cursor・Gemini CLI と共有できる範囲

AGENTS.md を共通規約の実体にすることは可能です。ただし、同じ名前のファイルを置いても、探索範囲や追加ファイルの扱いまでは統一されません。

出典は Claude Code のメモリ仕様、Codex の指示ファイル仕様、Cursor Rules、Gemini CLI のコンテキストファイル仕様 です。

Codex は各階層で AGENTS.override.md、AGENTS.md、設定した project_doc_fallback_filenames の順に探します。グローバル設定のディレクトリ (既定は ~/.codex) でも override が優先され、プロジェクト指示の合計サイズは project_doc_max_bytes の既定値で 32 KiB が上限です。この上限は Codex の仕様であり、AGENTS.md 共通の制限ではありません。

本記事では、共通規約を通常の AGENTS.md に置き、override に必須ルールを隠さず、ツール固有の import 構文に依存しない構成を提案します。Gemini CLI のファイル名設定と Claude Code の利用条件も揃えれば、規約本文を 1 ファイルで共有する運用は可能です。ネストした指示を読むタイミングと、ツールごとの設定は、規約を 1 ファイルにしても揃いません。ここは各ツールの仕様に合わせて設計してください。

ツール自体の使い分けを決める際は、Claude Code と Codex の Enterprise 比較 も参考になります。

チームの構成に合わせて規約の実体を決める

ここまでの仕様を踏まえると、移行先は次のように選べます。いずれも本記事の運用提案です。

共通規約を import する構成なら、CLAUDE.md は次のように短く保てます。コードブロックはファイル内容の例です。

@AGENTS.md
 
## Claude Code 固有の指示
変更案を実装する前に、対象ファイルと検証コマンドを説明してください。

共通規約を両ファイルへコピーせず、AGENTS.md を修正すれば済む状態にします。両方を直接読む構成でも同じで、CLAUDE.md 側には共通規約と矛盾しない固有指示だけを残してください。

FIXIT

じゃあ、全員が新しい読み方に切り替えなくてもいいんだ？

Hayate

はい。僕なら環境が混在する間は import を残します。規約の実体を揃えれば二重管理は避けられます。

移行は読み込み確認までをセットにする

まずバージョンと接続先を確認し、作業ディレクトリから上の CLAUDE.md 系を調べてください。その後、共通規約の実体と読み込み方法を決め、不要になった文章の指示やフックを整理します。

最後に、実際の作業場所で新しいセッションを開始し、読み込まれたパスと指示内容を確認しましょう。個人用の CLAUDE.local.md があるメンバーや、別の接続先を使うメンバーも確認できれば、チームの移行手順として共有できます。

AI 開発ツールの運用ルールを整えたい方へ

AI 駆動開発のクリエイティブスタジオである FIXIT の AI 開発ツール導入支援 では、ツール選定とチームの運用ルール作りを支援しています。複数ツールに分かれた規約や読み込み確認の手順を整理したい方は、お問い合わせ から現在の構成をお聞かせください。