Claude Code 使い方ガイド：AGENTS.mdを直接読み込む設定

Claude Code 使い方：最短の設定手順

次の順に確認してください。

1. claude --versionを実行します。v2.1.277以降が必要です。
2. 必要なら更新します。ネイティブインストールではclaude updateを使えます。HomebrewとWinGetの場合は、それぞれのパッケージマネージャーのアップグレードコマンドを使います。
3. セッションがAnthropicの機能フラグを取得できることを確認します。Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundryなど、サードパーティープロバイダー経由のセッションではAGENTS.mdのネイティブ読み込みを利用できません。テレメトリや必須でない通信を制限する設定によって、機能フラグを取得できない場合も同様です。
4. プロジェクトパスにAGENTS.mdまたは.claude/AGENTS.mdを置きます。デフォルトモードでは、作業ディレクトリとその上位階層にプロジェクトCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdが存在しないことも確認してください。
5. 両方のファイル群を使う場合は、/configを開き、Project instructionsをclaude-md-and-agents-mdに設定します。
6. 新しいセッションでテストします。インストールまたはアップグレード直後の最初のセッションは例外になるため、次のセッションを開いてから判定してください。

以上がネイティブ機能を使う手順です。/configにProject instructionsが表示されない場合は、これまでどおりCLAUDE.mdに@AGENTS.mdを記述してインポートしてください。

Claude Codeが実際に選ぶファイル

新しい仕組みは、すべての指示ファイルを一律に走査するものではなく、切り替え器として動作します。デフォルトのclaude-md-or-agents-mdモードでは、Claude CodeはまずプロジェクトレベルのClaude向け指示を探します。作業ディレクトリまたはその上位階層に該当するClaudeファイルが1つもない場合に限り、AGENTS.mdへフォールバックします。

見落としやすいのが適用範囲です。親ディレクトリにCLAUDE.local.mdがあると、フォールバックは抑止されます。一方、個人用の~/.claude/CLAUDE.md、組織が管理するCLAUDE.md、.claude/rules/は抑止しません。同じリポジトリを開いた2人の開発者で挙動が異なるという報告の多くは、この違いで説明できます。

フォールバックが適用されると、Claude Codeはセッション開始時に、作業ディレクトリとその上位階層にあるAGENTS.mdおよび.claude/AGENTS.mdを読み込みます。サブディレクトリにあるAGENTS.mdは、Claudeがその配下のファイルを読んだ時点で後から読み込まれることがあります。ただし、そのサブディレクトリに条件該当のClaudeファイルがない場合に限ります。AGENTS.local.md、AGENTS.override.md、.agents/配下のファイルを直接読み込むことはありません。

これはフォルダー検索というより、建物の電気系統を選ぶ切り替え器に近い仕組みです。最初に有効な指示回路が選ばれるため、もう一方の回路に正しいファイルがあっても、接続されないことがあります。

Project instructionsモードを意図的に選ぶ

/configを開いてProject instructionsを探し、リポジトリで何を正本にするかに合わせて選びます。

• フォールバック、claude-md-or-agents-md：すでにAGENTS.mdを使っており、プロジェクトClaudeファイルがないリポジトリに適しています。これがデフォルトです。
• 両方、claude-md-and-agents-md：AGENTS.mdに共通ルールを置き、CLAUDE.mdにClaude固有の指示を追加する場合に適しています。
• Claudeのみ、claude-md：共有エージェント指示をまだClaude Codeへ渡したくないチームに適しています。
• 管理対象のみ、managed-only：組織ポリシーと自動メモリは読み込む一方、起動時にはリポジトリ指示を読み込まない、管理された起動環境に適しています。

両方モードでは、各ディレクトリでClaudeの内容が先に、AGENTSの内容が後に読み込まれます。CLAUDE.mdが同じAGENTS.mdをすでにインポートしている場合や、そこへのシンボリックリンクになっている場合は、重複読み込みも回避されます。

選択内容は次のメッセージから有効になり、新しいセッションにも引き継がれます。また、ユーザー設定内の組み込みagents-md@builtinプラグイン、--settingsファイル、管理対象設定にも保存できます。Claude Codeはプロジェクト設定ファイルとローカル設定ファイルにあるこの項目を無視するため、リポジトリ側が全開発者の選択をひそかに固定することはできません。管理者は、管理対象設定を通じて組織全体の選択を一元管理できます。

新しいセッションが読んだファイルを確かめる

破壊的な指示ではなく、無害な識別文字列を使います。確認したいファイルに次の1行を追加してください。

Project probe: BASALT-HERON.

次にセッションを閉じ、リポジトリで新しいセッションを開始して、What is the project probe?と尋ねます。BASALT-HERONと正しく返れば、その内容がセッションのコンテキストに届いています。確認後は追加した行を削除してください。

判定を/contextだけに頼らないでください。直接読み込まれたAGENTS.mdは、Memory filesの一覧に表示されません。デフォルトのフォールバックを使う対話型セッションでは、起動時にAGENTS.md loadedと表示されることがあります。無害な識別文字列を尋ねる方法なら、ほかの選択モードでも確認できます。

識別文字列を答えられない場合は、次の順に確認します。

1. バージョン： v2.1.277以降か。
2. セッション回数： インストールまたはアップグレード直後の最初のセッションではないか。
3. プロバイダー： Anthropicの機能フラグ取得を妨げるプロバイダー経由のセッションではないか。
4. 環境： テレメトリまたは必須でない通信を制御する環境変数によって、取得が無効になっていないか。
5. プラグインとポリシー： 組み込みのagents-mdプラグインが有効で、disableAllHooksまたはallowManagedHooksOnlyによってブロックされていないか。
6. ファイル階層： デフォルトモードの場合、現在の階層またはその上位に、条件に該当するCLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.mdがないか。
7. モード： /configが意図した挙動を選んでいるか。

/configにProject instructionsが表示されないこと自体も診断材料です。そのセッションは未対応バージョンを使っているか、この機能を利用できない状態です。

ネイティブ機能が使えない環境ではインポートを残す

Bedrock、Vertex、Foundryなどのサードパーティープロバイダー経由のセッション、テレメトリ制限環境、複数バージョンが混在するチームでは、従来のインポートが最も安全な互換レイヤーです。AGENTS.mdと同じ場所にあるCLAUDE.mdへ、次の内容を記述します。

@AGENTS.md

その下にはClaude固有の指示を追加できます。Claudeは、インポートされた共通ファイルを先に読み、その後にClaude固有の追加内容を読みます。この橋渡しを残したまま対応ユーザーが両方モードを選んでも、二重読み込みにはなりません。

CLAUDE.mdからAGENTS.mdへのシンボリックリンクも使えますが、クロスプラットフォームではインポートのほうが安全です。Windowsでシンボリックリンクを作るには、管理者権限または開発者モードが必要になることがあり、Gitにも適切なシンボリックリンク設定が必要です。直接読み込みが動作するようになったら、AGENTS.mdを出力するSessionStartフックは削除してください。内容を重複して注入するおそれがあります。

今回のリリースで、保守にかかる手間の構造が変わります。これまでは、複数エージェント向けのポリシーを1つにまとめたいチームでも、2つのファイル、インポート用のつなぎ、またはフックを抱えがちでした。対応セッションなら、コミットする指示ファイルを1つにできます。ただし、Claudeの利用料金が安くなるわけではありません。Anthropicの料金ページでは、月額$20のProプランにClaude Codeが含まれています。減らせるのは同期箇所と、古いルールを参照するセッションです。

インストール、プロジェクトコンテキスト、日々のコマンド操作まで含めた設定全体は、Claude Codeの詳しい使い方で解説しています。リポジトリで専門エージェントも定義している場合は、サブエージェントガイドで個別の起動コンテキストを確認できます。

導入効果が大きい7つのケース

新しい切り替え機能が解消する連携課題の大きさを基準に並べています。

最初の3ケースは、問題の影響が人とリポジトリの数だけ増えるため、特に大きな効果を見込めます。エージェントを1つだけ使う個人リポジトリにも利便性はありますが、効果は限定的です。

この仕組みから作れるプロダクト

1. 複数エージェント対応の指示診断ツール

各コーディングエージェントがどの指示ファイルを読み込むか、正確に説明するローカルCLI兼CIチェックを構築します。リポジトリへ展開する前に確実な判定が必要なプラットフォームチームやコンサルティング会社なら、対価を払う可能性があります。

需要はすでに検索行動に表れています。claude code setupの米国での月間検索数は約1,900件、claude md vs agents mdは480件で、前年比1,500%増です。販売可能な最小構成では、ファイルツリーを走査し、Claude Codeのバージョンとプロバイダー設定を読み取り、上位ファイルによる遮蔽を検出して、読み込み順を提示します。有料のチーム向け機能では、複数リポジトリに同じポリシーを適用できます。

これはテンプレート作成ではなく診断の問題を解くため、3案の中で最も有望です。ただし、プラットフォーム依存のリスクがあります。Anthropicが同様のチェックをclaude doctorへ組み込む可能性があるため、長期的な価値を持たせるには、単一のClaudeコマンドに依存せず、複数のコーディングエージェントを対象にしてポリシー変更の履歴まで扱う必要があります。

2. AGENTS.mdの初期作成・リントツール

ビルドコマンド、テストルール、ディレクトリ境界、レビュー要件を簡潔なAGENTS.mdへまとめるガイド付きエディターを作り、矛盾や曖昧な表現も検査します。複数のエージェントを導入し始めた小規模な開発チームが購入者になります。

agents mdの米国での月間検索数は約2,900件です。より具体的なagents md best practicesは210件で、前年比750%増となっています。MVPに必要なのは、リポジトリスキャナー、短いヒアリング、下書き生成、重複・矛盾した指示を見つけるリントルールです。巨大なポリシーマニュアルを作るのではなく、簡潔なプロジェクトファイルを推奨するプロバイダーの方針に沿うべきです。

弱点は、差別化が難しいことです。Markdownの下書きなら、どのコーディングエージェントでも作れます。実際の読み込み順を検証し、対応する各ツールが結果を読み取ったと証明できて初めて、独自の価値が生まれます。

3. 混在環境向けの移行監査

CLAUDE.md、AGENTS.md、インポート、シンボリックリンク、フック、階層化されたルール、プロバイダーごとの例外を整理し、安全に指示元を1つへ移行する計画をレポートとして提供します。複数のエージェントツールを使う代理店や大規模チームが主な購入者です。

claude md vs agents mdは米国で月間480件検索され、前年比1,500%増です。この数字は、現場の混乱を直接示す珍しい需要データです。MVPは、読み取り専用のリポジトリ分析ツールとプルリクエスト計画で構成できます。未対応セッションで橋渡しが必要になる可能性があるため、自動的に削除してはいけません。

弱点は、鮮度の高い期間が短いことです。チームが安定した共通ファイルの慣行へ収束すれば、一度きりの移行需要は縮小します。継続的なポリシー監査とプロバイダー互換性チェックを中核サービスに育てる必要があります。

制約と率直な評価

ネイティブのフォールバックが取り除くのは、橋渡しの手間です。プロジェクト指示が強制ルールになるわけでも、すべてのプロバイダーが対応するわけでも、競合する指示が自動的に解決されるわけでもありません。Anthropicは指示ファイルをコンテキストとして説明しています。必ずブロックすべきコマンドがあるなら、権限ルールまたはPreToolUseフックを使ってください。

また、AGENTS.mdがCLAUDE.mdと同じ診断画面に表示されるようになるわけでもありません。直接読み込まれたファイルは、/memoryにも/contextのMemory files一覧にも現れません。この不整合があるため、移行チェックリストには無害な識別文字列による確認を残しておく価値があります。

1台のノートPCでネイティブ読み込みを確認できたからといって、複数プロバイダーが混在する環境から、動作中のインポートを削除してはいけません。矛盾を確認せずに両方モードを選ぶのも避けるべきです。同じディレクトリではClaudeの内容がAGENTSの内容より先に読まれますが、コンテキスト上の順番は強制力のあるポリシー優先順位ではありません。

それでも今回のリリースは、運用面で意味のある改善です。AGENTS.mdを共通の正本としてきたリポジトリなら、別名のファイルを正本のように扱わずにClaude Codeを利用できるようになりました。小さな機能ですが、連携への効果は大きい変更です。

リポジトリに合った信頼できるマルチエージェント指示システムが必要なら、エージェント設計と導入を支援できます。