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

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の仕様として残っています。

症状からたどる確認の順番

どちらの原因か分からないときは、手間の小さい確認から順に当たります。memoryドキュメントのトラブルシューティングも、CLAUDE.mdの有無、バージョン、/configの表示の順で案内しています。

1つ目に当たれば仕様どおりの挙動です(CLAUDE.local.mdなら原因2)。2つ目以降に当たれば原因1か、後述のインストール直後・プラグイン無効の場合です。

原因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セッション

0を書いても配信が戻らないのは、DISABLE_TELEMETRYとCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICの2つです。この2つは、0やfalseを含む非空の値ならどれでも通信を止めるとenv-varsに書かれています。issueのコメント欄にも、0にしても止まったままだという報告があります。一方DISABLE_GROWTHBOOKとDO_NOT_TRACKは通常の真偽値で、0なら配信は止まりません。

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

env-varsの「First session after an install or upgrade」節には、もうひとつ効く条件があります。毎回まっさらなCIコンテナでは、前回のセッションが保存したフラグがないため、どの実行も「最初のセッション」になります。ANTHROPIC_AUTH_TOKENだけで認証し、ANTHROPIC_BASE_URLをAnthropic以外のホストに向けた構成でも、フラグを取りにいく資格情報がありません。

issueのコメントには、回避の手がかりも出ています。プロジェクトの.claude/settings.jsonのenvで2つの変数を空にしても効きませんでした。claude --settings '{"env":{"DISABLE_TELEMETRY":"","CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":""}}'を渡すと、2回目のセッションから読めたという報告です(v2.1.280での確認)。1回目はフラグを取得するだけで終わります。

バージョンごとに変わった読み込み範囲

issue #95690は未クローズのままです。ただしchangelogとmemoryドキュメントは、v2.1.281以降のこれらの環境で読めると明記しています。

DISABLE_GROWTHBOOKだけで止めている構成は、changelogの文言に名指しされていません。CI環境でこの変数だけを使っているなら、更新後も動作を確かめてください。

claude --version
# 例: 2.1.289 (Claude Code)

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

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

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

v2.1.276以前からv2.1.277以降へ上げた直後の最初のセッションでも、読まれないことがあります。この場合は、Claude Codeがそのセッション中にフラグを取得して保存し、次のセッションから通常どおり読み込みます。

原因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へのフォールバックが止まります。

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

サブディレクトリにCLAUDE.local.mdを置くと、ルートのAGENTS.mdもsub/自身のAGENTS.mdも読まれません。作業ディレクトリより上位のどこかにCLAUDE.local.mdがあれば、それだけでフォールバック全体が無効になります。

報告によると、~/.claude/CLAUDE.mdではこの現象は起きません。$HOMEの下にあるリポジトリでも、AGENTS.mdは3/3で読まれました。memoryドキュメントの判定条件と同じ結果です。

セッション内の警告もありません。issueには、飛ばしても警告も起動時の通知も出ないとあり、共有指示のないプロジェクトにしか見えない点が、気づきにくさの理由です。

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

この挙動は、Project instructions設定の既定値claude-md-or-agents-mdが持つ判定条件どおりの結果です。issue #96117はバグとして報告していますが、memoryドキュメントは既定の仕様として説明し、CLAUDE.local.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の3か所です。プロジェクト側やローカル側の設定ファイルに書いても無視されます(settings-referenceに明記)。チーム全員に効かせたいなら、各自の~/.claude/settings.jsonかmanaged settingsに書きます。

--settingsは、v2.1.289のclaude --helpで「Path to a settings JSON file or a JSON string to load additional settings from」と説明されています。ファイルでもJSON文字列でも渡せます。

claude-md-and-agents-mdにすると、各ディレクトリのCLAUDE.mdを先に、AGENTS.mdをその後に読み込みます。CLAUDE.mdが@AGENTS.mdでインポート済みのときは、二重読み込みを避けて自動でスキップされます。

プロジェクト指示を読み込まない設定のサブエージェントは、AGENTS.mdもCLAUDE.mdと一緒にスキップします。サブエージェントにAGENTS.mdの内容を参照させたいなら、そのサブエージェント側で読み込みを有効にします。

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

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

@AGENTS.md

このファイルは、CLAUDE.local.mdがあっても、フラグ配信が止まったセッションでもAGENTS.mdを読み込ませます。memoryドキュメントも、CLAUDE.mdがAGENTS.mdをインポート済みなら、フォールバックの判定に関係なく読まれると説明しています。

CLAUDE.mdに「AGENTS.mdを読むこと」と文章で書くだけの方法は、効き方が違います。Claudeが自分でそのファイルを開くと判断したときにしか見えません。@AGENTS.mdというインポートに置き換えます。

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

一覧にAGENTS.mdが載らない古い版では、Claudeにプロジェクト指示の内容を尋ねる形で確かめます。

対話セッションでは、起動時の会話に読み込みを示す行も出ます。

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

memoryドキュメントが行の表示を説明しているのは対話セッションだけです。claude -pのような非対話では、issue #96117のようにコードワードを書いたファイルを用意し、Claudeに尋ねる検証が確実です。

ひとつ注意があります。issueの報告者は、尋ねるコードワードを「プロジェクト用」の1つだけにすると、CLAUDE.local.md側の語が答えとして返ってくると書いています。プロジェクト用とローカル用の2つを同時に尋ねます。

AGENTS.mdとして読まれないファイルと、読まれ方の違い

名前や置き場所が違うために、置いたつもりのファイルがAGENTS.mdとして扱われないこともあります。memoryドキュメントに載っているのは次の4つです。

読まれているのに期待どおり動かない場合は、CLAUDE.mdとの違いが原因のことがあります。設定経由で読んだAGENTS.mdでは、InstructionsLoadedフックが発火しません。CLAUDE.mdがインポートまたはシンボリックリンクしているAGENTS.mdなら、フックは通常どおり発火します。

また、作業ディレクトリ外への@pathインポートは、CLAUDE.mdなら承認を求められます。AGENTS.mdでは、そのプロジェクトで外部インポートを承認済みの場合に限り、確認なしで読み込まれます。

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

まとめ

経路上にCLAUDE.mdかCLAUDE.local.mdがあるなら、読まれない原因は仕様です。claude-md-and-agents-mdか、@AGENTS.mdを書いた1行のCLAUDE.mdで両方を読ませられます。

経路上に何もないのに読まれないときは、バージョンと実行環境(Bedrock・telemetry無効・CI・インストール直後)を疑います。