Claude CodeのAGENTS.mdが読み込まれない・反映されない原因を、公式仕様とGitHub Issueの実例で整理した

Home / Blog / Claude CodeのAGENTS.mdが読み込まれない・反映されない原因を、公式仕様とGitHub Issueの実例で整理した

2.1.277で正式対応したAGENTS.mdは、読み込まれたかどうかが/contextにすら出ない。公式ドキュメントの仕様と、初回セッションの制約だけでは説明できない非決定的な読み込み失敗の実例(Issue #95589)を整理し、確実に読ませるための回避策までまとめた。

エンジニアのゆとです。

Claude Codeは2.1.277からAGENTS.mdを正式サポートした。CodexやCursor、GitHub Copilotなど複数のツールで指示ファイルを使い回している人にとっては地味に嬉しいアップデートのはずなんだけど、実際に触ってみるとやっかいな性質がある。読み込まれたかどうかを確認する手段が限られている上に、条件を満たしているはずなのに読み込まれないケースが複数報告されている、という点だ。

しかもこれ、症状が「エラーは出ない・警告も出ない・ただ静かに指示が反映されない」という一番厄介なタイプ。settings.jsonが壊れるケースと似ているけど、AGENTS.mdの場合は輪をかけて確認方法が乏しい。この記事では公式ドキュメントに書かれている仕様と、そこからはみ出す形で報告されている実際の不具合を突き合わせて整理する。

まず結論 — 症状別の原因早見表

症状	原因	対処
プロジェクトに`CLAUDE.md`もあるのに`AGENTS.md`の内容が無視される	仕様どおり。`CLAUDE.md`がある場合は`AGENTS.md`は読まれない	`CLAUDE.md`に`@AGENTS.md`のインポートを追加する
`CLAUDE.local.md`だけ置いているのに`AGENTS.md`が読まれない	`CLAUDE.local.md`も「CLAUDE.mdとしてカウント」される仕様。フォールバック条件から外れる	`/config`の「Project instructions」を`claude-md-and-agents-md`に変更する
インストール・アップデート直後のセッションで読まれない	「アップデート後の最初のセッション」は仕様上フィーチャーフラグが未取得で対応外。次のセッションから有効になる	一度セッションを終了して開き直す
Bedrock/Vertex/Foundry経由、またはテレメトリ無効環境で読まれない	仕様上AGENTS.md対応そのものが提供されない環境がある	`CLAUDE.md`に`@AGENTS.md`をインポートして代替する
同じディレクトリ・同じ設定で、セッションによって読まれたり読まれなかったりする	上記のどの条件にも当てはまらない非決定的な不具合が報告されている(2026年9月19日、Issue #95589)	下記の回避策で`CLAUDE.md`経由の読み込みに切り替える
`/context`で確認しようとしても「Memory files」に出てこない	仕様どおり。AGENTS.mdは`/context`のMemory filesに一覧表示されない	セッション開始時の`AGENTS.md loaded`という通知行で確認する

code.claude.com

How Claude remembers your project - Claude Code Docs AGENTS.mdの読み込み条件・優先順位・既知の制限がまとまっている一次情報。この記事の仕様部分は全てここに基づいている。

基本仕様 — CLAUDE.mdとAGENTS.mdはどちらが読まれるのか

公式ドキュメントには、リポジトリの状態ごとにどちらが読まれるかが明記されている。

リポジトリの状態	Claude Codeが読むもの
`AGENTS.md`はあるが、作業ディレクトリとその上位に`CLAUDE.md`も`CLAUDE.local.md`もない	`AGENTS.md`
`AGENTS.md`があり、作業ディレクトリかその上位に`CLAUDE.md`か`CLAUDE.local.md`がある	`CLAUDE.md`系のみ
`CLAUDE.md`が`@AGENTS.md`を既にインポートしている	`CLAUDE.md`（インポート経由で`AGENTS.md`も含む）

ポイントは2つ。1つは「AGENTS.mdはCLAUDE.mdが存在しない場合のフォールバック」という位置づけであること。もう1つは、CLAUDE.local.mdが「CLAUDE.mdとしてカウントされる」ため、個人用のCLAUDE.local.mdを1つ置いただけでAGENTS.mdが読まれなくなるということ。チームでAGENTS.mdに寄せて運用しているつもりが、自分だけCLAUDE.local.mdにメモを書いていたせいでAGENTS.mdの内容を見ていなかった、という事故は普通に起こりうる。

読み込みのタイミングにも階層がある。

セッション開始時: 作業ディレクトリとその上位にあるすべてのAGENTS.md・.claude/AGENTS.md
サブディレクトリ: Claudeがそのディレクトリのファイルをオンデマンドで開いたとき（かつそのディレクトリにCLAUDE.md系が無い場合のみ）
読まれないもの: AGENTS.local.md、AGENTS.override.md、.agents/配下のファイル

最後の「読まれないもの」は地味に見落としやすい。AGENTS.local.mdという名前で個人用ファイルを作っても、Claude Codeはそれを認識しない。命名を真似ただけでは効かない。

Mar 17, 2026 CLAUDE.mdの書き方ガイド｜実運用で分かった設計パターンとアンチパターンCLAUDE.mdを3ヶ月間毎日書き換えながら運用して見えた設計のコツ。読み込み階層の構造、箇条書きvsコードブロックの遵守率の違い、Progressive Disclosure、Auto Memoryとの役割分担、アンチパターンまで実運用ベースで解説。読む →

「/config」の4つの設定値 — デフォルトのままでいいとは限らない

/configから「Project instructions」の値を変更できる。デフォルトはclaude-md-or-agents-md（CLAUDE.mdがあればそちら、無ければAGENTS.md）だが、他に3つの選択肢がある。

設定値	挙動
`claude-md-or-agents-md`（デフォルト）	CLAUDE.mdがあればそちら、無い場合のみAGENTS.md
`claude-md-and-agents-md`	各ディレクトリでCLAUDE.mdを先に、AGENTS.mdを後に、両方読む
`claude-md`	CLAUDE.mdのみ。AGENTS.mdは一切読まない
`managed-only`	組織のmanaged CLAUDE.mdとAuto Memoryのみ。個人・プロジェクトのCLAUDE.mdもAGENTS.mdも全部除外

CLAUDE.local.mdで個人メモを取りつつAGENTS.mdも読ませたい、というよくあるニーズにはclaude-md-and-agents-mdが正解になる。ここを知らずに「CLAUDE.local.mdを置いたらAGENTS.mdが無視された」と混乱している報告を何件か見かけたので、症状に心当たりがあるなら/configを一度開いてみてほしい。

設定ファイルから変更する場合は~/.claude/settings.json（プロジェクト・ローカル設定では無視される点に注意）に書く。

// ~/.claude/settings.json
{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

読み込まれたかどうかを確認する方法 — /contextでは分からない

CLAUDE.mdなら/contextのMemory filesに一覧で出てくるので確認しやすい。ところがAGENTS.mdは/config経由で読まれた場合、/contextのMemory filesには一切表示されない仕様になっている。InstructionsLoadedフックも発火しない。ここは公式ドキュメントにもわざわざ「CLAUDE.mdとAGENTS.mdの違い」として明記されているくらい、素直に確認できない。

確認する手段は次の2つ。

セッション開始時の通知行を見る: インタラクティブセッションならno CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.mdという1行が会話の中に表示される
Claudeに直接聞く: 「今のプロジェクト指示に何が入っているか教えて」と聞けば、読み込まれていればAGENTS.mdの内容に基づいた回答が返ってくる

自分の環境で試すなら、AGENTS.mdの末尾に一時的に固有の合言葉（PURPLE-ELEPHANT-47291のような検索に引っかからない文字列）を仕込んで、新しいセッションでその合言葉を聞いてみるのが一番確実だった。反応した場合は読み込まれている。反応しない場合、Claudeがファイルを能動的に開いて読んだ可能性もゼロではないので、聞き方を「ファイルを開かずに、今持っている指示だけから答えて」にすると誤判定を減らせる。

初回セッション制約だけでは説明できないケースがある

ここまでは公式ドキュメントに書かれている仕様の範囲。ここからが本題で、仕様どおりに設定しても読み込みが安定しない、という報告が出ている。

公式ドキュメントは「AGENTS.md対応が使えない場合」として次を挙げている。

Claude Code 2.1.277より前のバージョン
Anthropicからフィーチャーフラグを取得できないセッション（Bedrock経由、テレメトリ無効など）
インストールまたはアップグレード後の最初のセッション（次のセッションから有効になる）
disableAllHooksやallowManagedHooksOnlyが設定されている、または/pluginでagents-mdプラグインを無効化している場合

つまり「最初のセッションでは読まれない」のは既知の仕様であり、2回目以降なら安定するはずだった。ところが2026年9月19日に報告されたIssue #95589では、これでは説明のつかない挙動が記録されている。

同じバイナリ（2.1.278）、同じディレクトリ、同じファイル、同じ設定、同じフィーチャーフラグの状態で、45分間に8回セッションを起動したところ、読み込まれたセッションと読み込まれなかったセッションが混在した

報告されている8回の内訳はこうだ。

起動時刻	起動方法	読み込み結果
04:17	インタラクティブ	読まれず
04:22	インタラクティブ	読まれず
04:27	`claude -p`	読み込み成功
04:38	`claude -p`	読み込み成功
04:38	インタラクティブ(pty)	読み込み成功
04:40	インタラクティブ(pty)	読み込み成功
04:46	インタラクティブ	読み込み成功（通知表示あり）
05:03	インタラクティブ	読まれず

インストール直後でも最初のセッションでもない。読み込みに成功した回と失敗した回で、起動方法にも一貫した傾向が見えない。読み込みに失敗したセッションはエラーも警告も出さず、指示ファイルが最初から存在しないプロジェクトとまったく同じ見た目になる、と報告者は書いている。つまり「反応がおかしいな」と気づかない限り、プロジェクトのルールが適用されないままタスクが進んでしまう。

github.com

[BUG] AGENTS.md loading is intermittent on 2.1.278 · Issue #95589 · anthropics/claude-code 45分間に8セッション中3回が読み込み失敗、というログ付きの再現報告。この記事執筆時点(2026年9月20日)でまだクローズされていない。

この記事を書いている時点でこのIssueは報告されたばかりで、メンテナーからの反応もまだ付いていない。原因はまだ特定されていないので、「なぜ起きるか」より「起きても実害が出ないようにどう設計するか」で考えたほうが建設的だと思う。

確実に読ませるための回避策 — CLAUDE.mdからのインポート

非決定的な不具合が相手だと、「症状が直るのを待つ」よりも「その経路自体を使わない」ほうが早い。公式ドキュメントも同じ結論で、AGENTS.mdを他ツールとも共有しつつClaude Codeにも確実に読ませたい場合の推奨手順を示している。

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code
[Claude Code固有の指示があればここに追記]

これでCLAUDE.md経由の読み込みに切り替わるので、AGENTS.md単体読み込みの経路（今回の不具合が起きている経路）を通らなくなる。CLAUDE.mdは/contextのMemory filesにも表示されるし、InstructionsLoadedフックも通常どおり発火するので、確認のしやすさという点でも上回る。

シンボリックリンクで済ませる手もあるにはある。

ln -s AGENTS.md CLAUDE.md

ただし2つ制約がある。1つは、EditツールとWriteツールがシンボリックリンク越しの書き込みを拒否する仕様になっていて、Claudeが編集しようとすると「リンク先のAGENTS.mdを直接編集して」という案内が返ってくること。もう1つはWindows。管理者権限かDeveloper Modeが無いとシンボリックリンクを作成できない上に、core.symlinksが有効になっていないGitではコミットしたシンボリックリンクがただのテキストファイルとしてチェックアウトされてしまう。チームに1人でもWindows環境がいるなら、シンボリックリンクではなく@AGENTS.mdインポートを選んだほうが安全だ。

どちらの方法を選んでも、次のセッションで/contextを開いてCLAUDE.mdが「Memory files」に表示されることを確認しておくといい。

Sep 4, 2026 Claude Codeのsettings.jsonが読み込まれない・反映されない原因を、公式ドキュメントとGitHub Issueの実例で整理したsettings.jsonは構文エラーが1つあるだけでファイル全体が丸ごとスキップされる。過去に報告された7件のGitHub Issueと公式ドキュメントの現在の挙動を照らし合わせ、症状別の原因切り分けと確認手順をまとめた。読む →

過去のワークアラウンドを引きずっている人向け — 何を消して何を残すか

AGENTS.mdへの正式対応は2.1.277からなので、それ以前から自力でワークアラウンドを組んでいた人もいるはず。公式ドキュメントには、そのワークアラウンドをどう整理すればいいかまで書かれている。

@AGENTS.mdをインポートしたCLAUDE.md: そのままでいい。二重読み込みにはならない仕様。他に書く内容が無ければCLAUDE.mdごと削除してもいいし、Bedrock等の非対応環境向けに残しておくのも手
「AGENTS.mdを読んで」と文章で指示しているだけのCLAUDE.md: Claudeが能動的にファイルを開いた場合しか読まれない。CLAUDE.mdごと削除してAGENTS.md直接読み込みに任せるか、@AGENTS.mdインポートに書き換える
CLAUDE.mdをAGENTS.mdにシンボリックリンクしていた: そのままでも削除してもいい。どちらでも中身は1回しか読まれない
SessionStartフックでAGENTS.mdの中身をprintしていた: 削除する。直接読み込みが有効なら、そのままだと同じ内容が二重にコンテキストへ入ってしまう

AGENTS.mdとCLAUDE.mdの機能差 — 「/config」経由には抜けがある

「読まれるなら中身は同じでは」と思うかもしれないが、/configのProject instructions経由で読まれたAGENTS.mdには、CLAUDE.mdに対していくつか機能が欠けている。

項目	CLAUDE.md	`/config`経由のAGENTS.md
`/context`のMemory filesに表示	される	されない
`InstructionsLoaded`フックの発火	する	しない（CLAUDE.mdがインポート/シンボリックリンクした場合は発火する）
`--add-dir`で追加したディレクトリの読み込み	`CLAUDE.md`が読まれる	`AGENTS.md`は読まれない
作業ディレクトリ外の`@path`インポート	承認ダイアログが出る	既に外部インポートを承認済みなら確認なしでロードされる

最後の項目は地味にセキュリティ上気になるポイントで、AGENTS.md経由だと外部ファイルのインポートで確認ダイアログが省略されるケースがある。信頼できないリポジトリをcloneしてすぐにセッションを開く運用をしているなら、頭の片隅に置いておいたほうがいい。

FAQ

CLAUDE.mdとAGENTS.mdを両方置いたら両方読まれる?

デフォルト設定(claude-md-or-agents-md)では読まれない。CLAUDE.mdがあればAGENTS.mdは無視される。両方読ませたい場合は/configでclaude-md-and-agents-mdに変更する。

モノレポのサブディレクトリに置いたAGENTS.mdは読まれる?

Claudeがそのサブディレクトリのファイルをオンデマンドで開いたときに読み込まれる。ただし、そのサブディレクトリにCLAUDE.md系のファイルが1つでもあれば、そちらが優先されてAGENTS.mdは読まれない。

サブエージェントを使っているときもAGENTS.mdは読み込まれる?

プロジェクト指示自体をスキップする設定のサブエージェントは、AGENTS.mdもまとめてスキップする。サブエージェントの起動時の読み込み仕様については別記事で詳しく扱っている。

Jun 7, 2026 Claude Code サブエージェント × Worktree Isolation 設計ガイド — 並列実行でコンフリクトを防ぐ実装パターンClaude Codeのカスタムサブエージェントにisolation: worktreeを設定して並列ファイル編集を安全に実行する方法を解説。フロントマター設計、.worktreeinclude設定、自動クリーンアップの仕組みまで。読む →

読み込まれているかどうかを毎回チェックするのが面倒

/contextで確認できないという性質上、完全な自動チェックは難しい。現実的な落とし所は、AGENTS.mdに依存するプロジェクトでは@AGENTS.mdインポート方式に統一してCLAUDE.md経由の読み込みに寄せてしまうことだと思う。確認のしやすさが仕様として保証されている経路を使うほうが、非決定的な不具合の影響を受けずに済む。

AGENTS.mdは「複数のAIコーディングツールで指示ファイルを使い回せる」という触れ込みの割に、Claude Code側の読み込み確認手段がCLAUDE.mdより明らかに弱い。仕様どおりに動かないケースが実際に報告されている以上、当面は「AGENTS.mdを単体で信頼する」より「CLAUDE.mdから確実にインポートする」ほうが、少なくとも自分の手元では安定して動いている。