Claude Media
Claude CodeでAGENTS.mdが動かない2つの原因
Claude CodeTips

Claude CodeでAGENTS.mdが動かない2つの原因

AGENTS.mdがサーバー側フラグ次第で読めない件とCLAUDE.local.mdがフォールバックを止める件を、公式ドキュメントとGitHub issueで確認します。

読了目安 約8分

AGENTS.mdが読まれない主な原因は2つ

Claude Codeはv2.1.277からAGENTS.mdを直接読めるようになりました。CLAUDE.mdを置かずにAGENTS.mdだけを用意すれば、Claude Codeがそれをプロジェクト指示として読み込む仕組みです。

ところがGitHubには「AGENTS.mdを置いたのに読まれない」という報告が複数立っています。原因は大きく2つに分かれます。ひとつはAGENTS.md対応そのものがサーバー側のフラグ配信に依存していた時期があったこと(anthropics/claude-code#95690)、もうひとつはCLAUDE.local.mdを置くとAGENTS.mdへのフォールバックが黙って外れる仕様です(anthropics/claude-code#96117)。前者はv2.1.281で改善済みで、後者はclaude-md-or-agents-mdの既定仕様として残ります。バージョン・プラグイン設定に起因する条件はこのほかにもあり、後段でまとめて確認します。

原因1: フィーチャーフラグ配信がAGENTS.md読み込みをブロックしていた

issue #95690によると、AGENTS.md対応は内部的にビルトインプラグイン(agents-md)として実装され、Statsigのフィーチャーフラグtengu_agents_md_modで有効化されていました。この配信を受け取れないセッションでは、AGENTS.mdを置いても静かに無視されます。

配信を止める条件は次のいずれかです(公式ドキュメントenv-varsの「Features that need feature-flag fetching」節)。

  • DISABLE_GROWTHBOOK / DISABLE_TELEMETRY / DO_NOT_TRACK / CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC のいずれかを設定したセッション
  • Amazon Bedrock・Claude Platform on AWS・Google CloudのAgent Platform・Microsoft Foundryなどのサードパーティプロバイダー経由のセッション(CLAUDE_CODE_PROVIDER_MANAGED_BY_HOSTを設定したホスト側統合を除く)
  • Claude apps gatewayセッション

issueのコメント欄では、DISABLE_TELEMETRYやCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICを0に設定しても配信は止まったままだと報告されています。env-varsドキュメントも「これらの変数は0やfalseを含む非空の値ならどれでもトラフィックを止める」と明記しており、無効化したつもりで0を書いてしまう取り違えが起きやすい箇所です。

CI環境はこの条件に該当しやすい代表例です。issueのコメントではDISABLE_GROWTHBOOK=1やnonessentialトラフィック無効化がCIランナーの一般的な設定であり、そのためAGENTS.mdがCIだけ読まれないケースが報告されていました。

v2.1.281でBedrock・Vertex・Foundry・telemetry無効環境は改善済み

Claude Codeのchangelogによると、v2.1.281で次の変更が入りました。

Changed AGENTS.md support to also work on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled

公式memoryドキュメントも同じ内容を「v2.1.281より前は、Bedrockやtelemetry無効などの一部セッションでCLAUDE.mdしか読まれなかった。該当バージョンではアップデートしてほしい」と記載しています。つまりBedrock・Vertex・Foundry・LLMゲートウェイ経由や、telemetry無効(DISABLE_TELEMETRY・DO_NOT_TRACK・CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC)のセッションは、v2.1.281以降ならAGENTS.mdを読めます。

issue #95690は未クローズのままですが、v2.1.281のchangelogと公式memoryドキュメントは該当環境への対応を明記しています。claude --versionでバージョンを確認し、v2.1.281未満なら更新するのが最初に試すべき対処です。

claude --version

DISABLE_GROWTHBOOK単体で止めたケースがv2.1.281の改善対象に明記されているかは、changelogの文言(Bedrock・Vertex・Foundry・LLMゲートウェイ・telemetry無効)からは読み取れません。CI環境でDISABLE_GROWTHBOOKだけを使っている場合は、更新後も動作を確認してください。

インストール直後やプラグイン無効時も読まれない

公式memoryドキュメントは、フラグ配信のブロック(原因1)とは別に、AGENTS.mdが読まれない条件をさらに2つ挙げています。いずれの条件でも/configの設定パネルにProject instructionsの項目自体が表示されません。

  • Claude Codeのバージョンがv2.1.277より前
  • /pluginでビルトインのagents-mdプラグインを無効化している

これに加えて、v2.1.276以前からv2.1.277以降へアップグレードした直後の最初のセッションでは、AGENTS.mdが読まれないことがあります。env-varsドキュメントの「First session after an install or upgrade」節によると、インストールまたはアップグレード直後の最初のセッションではフラグに紐づく機能がまだ配信されておらず、Claude Codeがそのセッション中にフラグを取得します。次のセッションからは通常どおりAGENTS.mdが読み込まれます。

原因2: CLAUDE.local.mdがAGENTS.mdへのフォールバックを止める

もうひとつの原因は、v2.1.281の修正が入った後でも解消しません。公式memoryドキュメントは、AGENTS.mdを読むかどうかの判定条件をこう説明しています。

  • AGENTS.mdの代わりにCLAUDE.mdを読ませる判定に数える(カウントする)ファイル: 作業ディレクトリまたはその上位にあるCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md
  • 数えず、AGENTS.mdと並行して読み込まれ続けるファイル: ~/.claude/CLAUDE.md、組織のmanaged CLAUDE.md、.claude/rules/配下のファイル

つまりCLAUDE.local.mdはチーム共有用のCLAUDE.mdと同じ扱いで、これが存在するだけでAGENTS.mdへのフォールバックが止まります。CLAUDE.local.mdは個人用の未コミットファイルとして使われることが多く、gitignore対象にしているチームも珍しくありません。

issue #96117はこの挙動を「個人的なメモを1つ足しただけで、共有プロジェクト指示が全部消える」バグとして報告しています。報告者が5回ずつ検証した結果は次のとおりでした(claude -pで各ファイルのコードワードを尋ねる再現手順)。

ファイル構成cwdAGENTS.md読み込みCLAUDE.local.md読み込み
AGENTS.mdのみcwdルートAGENTS.md読み込み5/5CLAUDE.local.md読み込み該当なし
AGENTS.md + CLAUDE.local.mdcwdルートAGENTS.md読み込み0/5CLAUDE.local.md読み込み5/5
AGENTS.md + CLAUDE.local.md + @AGENTS.mdをインポートするCLAUDE.mdcwdルートAGENTS.md読み込み5/5CLAUDE.local.md読み込み5/5
ルートのAGENTS.mdのみcwdsub/AGENTS.md読み込み5/5CLAUDE.local.md読み込み該当なし
ルートのAGENTS.md + sub/CLAUDE.local.mdcwdsub/AGENTS.md読み込み0/5CLAUDE.local.md読み込み5/5

サブディレクトリにCLAUDE.local.mdを置いた場合でも、ルートのAGENTS.mdごと読み込みが止まる点に注意が必要です。作業ディレクトリより上位のどこかにCLAUDE.local.mdがあれば、それだけでフォールバック全体が無効になります。

セッション内では警告が一切出ません。issueが指摘するとおり、「共有指示が何もないプロジェクト」に見えてしまうため、CLAUDE.local.mdを追加した本人以外は原因に気づきにくい構造です。

対処: Project instructionsをclaude-md-and-agents-mdにする

この挙動は、Project instructions設定の既定値claude-md-or-agents-mdが持つ判定条件どおりの結果です。issue #96117はこれをバグとして報告していますが、公式memoryドキュメント上は既定の仕様どおりの動作として説明されています。CLAUDE.local.mdを残したままAGENTS.mdも読ませたい場合は、設定をclaude-md-and-agents-mdに変更します。

/configのProject instructionsからclaude-md-and-agents-mdを選ぶか、~/.claude/settings.jsonに直接書きます。

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

この設定はユーザー設定・--settings・managed settingsでのみ有効で、プロジェクト側やローカル側の設定ファイルに書いても無視されます(公式settings-referenceが明記)。チーム全員に強制したい場合は、個々人の~/.claude/settings.jsonかmanaged settingsに書く必要があります。

claude-md-and-agents-mdにすると、各ディレクトリのCLAUDE.mdを先に、AGENTS.mdをその後に読み込みます。すでにCLAUDE.mdがAGENTS.mdをインポート(@AGENTS.md)している場合は二重読み込みにならないよう自動でスキップされます。

プロジェクト指示を読み込まないサブエージェントは、AGENTS.mdもCLAUDE.mdと同じ扱いでスキップします。公式memoryドキュメントは、起動時にプロジェクト指示を読み込まない設定のサブエージェントについて、AGENTS.mdもまとめて対象外になると説明しています。サブエージェント経由でAGENTS.mdの内容を参照させたい場合は、そのサブエージェント自体の設定でプロジェクト指示の読み込みを有効にしておく必要があります。

もうひとつの回避策: @AGENTS.mdをインポートするCLAUDE.mdを置く

設定を変えたくない場合は、issue内でも報告者自身が使っている回避策として、AGENTS.mdの隣に1行だけのCLAUDE.mdを置く方法があります。

@AGENTS.md

このファイルはCLAUDE.local.mdの有無に関係なくAGENTS.mdを読み込ませられます。公式memoryドキュメントも、CLAUDE.mdが「すでにAGENTS.mdをインポートしている」場合は、フォールバック判定に関わらずAGENTS.mdが読まれると説明しています。

読み込まれているかどうかの確認方法

対話セッションでは、セッション開始時に読み込み状況を示す行が表示されます。

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

この行が出ていない、あるいはCLAUDE.local.mdが読み込まれた旨だけが表示される場合は、上記のいずれかの原因に該当している可能性があります。非対話セッション(claude -pなど)ではこの通知自体が出ないため、AGENTS.mdの内容を実際に尋ねる形で検証するほうが確実です。

複数のコーディングツールでAGENTS.mdとCLAUDE.mdを併用する運用パターンは、AGENTS.mdとCLAUDE.mdで設定を統合する運用パターンで扱っています。Next.jsプロジェクトでAGENTS.mdが自動生成される仕組みはNext.jsのAGENTS.md自動生成とマネージドブロックの仕組みを参照してください。

まとめ

AGENTS.mdが読まれない場合は、まずclaude --versionでv2.1.281以上かを確認します。Bedrock・Vertex・Foundry・LLMゲートウェイ経由やtelemetry無効環境では、それ未満のバージョンでフィーチャーフラグ配信がブロックされ、AGENTS.mdが黙って無視されていました。

バージョンを上げても直らない場合は、作業ディレクトリより上位にCLAUDE.local.mdが無いか確認してください。存在する場合はそれ自体が仕様どおりAGENTS.mdへのフォールバックを止めています。Project instructionsをclaude-md-and-agents-mdにするか、@AGENTS.mdをインポートする1行のCLAUDE.mdを置くことで両方を読み込めます。

いずれにも当てはまらない場合は、/pluginでagents-mdプラグインが無効化されていないか、インストールまたはアップグレード直後の最初のセッションではないかも確認してください。最初のセッションが原因なら、次のセッションを開始し直すだけで解消します。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →