AGENTS.mdをClaude Codeに読ませる｜v2.1.277で標準対応、橋が要る場合とCodex 32KiB上限

AIコーディングエージェントにプロジェクトのルールを教えるファイルは、ツールごとにバラバラだった。その乱立を1つにまとめようとして生まれたのが AGENTS.md で、公式サイトによれば6万を超えるOSSプロジェクトが採用している。長らくClaude Codeだけがこれを読まず、symlinkか@importで「橋」を架ける必要があった。その状況は 2.1.277（2026-09-18）で変わった。ただし読まれるのは「CLAUDE.mdが無いとき」だけで、確認方法も変わっている。本記事は2026-08-05の初出時に実測した内容に、2.1.277での実測を加えて全面的に更新した。

この記事では、AGENTS.mdをClaude Codeに読ませる方法を、2.1.277での実測と公式ドキュメントの記述、Next.js・Apache Airflowの実物、そしてCodexのソースコードで確かめた挙動をもとに整理する。Claude Code自体の全体像は Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き にまとめてある。

AGENTS.mdとは——READMEの「エージェント版」が中立の標準になるまで

AGENTS.mdは、AIコーディングエージェントに向けてプロジェクトの文脈と指示を書くための、ただのMarkdownファイルだ。公式サイトはこれを「エージェント版のREADME」と表現している。README.mdが人間向けのクイックスタートや貢献ガイドであるのに対し、AGENTS.mdにはビルド手順・テストコマンド・コーディング規約といった、READMEに書くと雑然とするがエージェントには必要な情報を置く。

重要なのは、これが特定ベンダーの独自ファイルではなくなっている点だ。公式サイトの記述によれば、AGENTS.mdはOpenAI Codex・Amp・Google Jules・Cursor・Factoryといった各社の協働から生まれ、現在はLinux Foundation傘下のAgentic AI Foundationが運営を引き継いでいる。

この移管は実際にリポジトリのURLにも表れている。かつての openai/agents.md にアクセスすると、現在は agentsmd/agents.md へリダイレクトされる（実際にHTTPリダイレクトを追跡して確認した）。ライセンスはMIT、スター数は23,419（2026-08-05時点）から24,400（2026-09-19時点）に伸びている。

採用規模は「2つの単位」で見る必要がある

普及の規模を語るときは数え方に注意がいる。公式サイトは「6万を超えるOSSプロジェクトが利用」と書いているが、GitHubのコード検索で filename:AGENTS.md を引くと176,352件がヒットする（2026-08-05時点）。

この2つは矛盾していない。単位が違うだけだ。前者は「プロジェクト数」、後者は「ファイル数」で、AGENTS.mdはサブディレクトリごとに置ける仕様のため1プロジェクトが複数ファイルを持つ。公式サイト自身も「執筆時点でOpenAIのメインリポジトリには88個のAGENTS.mdがある」と書いている。フォークも件数に乗る。どちらかが誤りだと断じるのではなく、別々の指標として扱うのが正しい。

Claude CodeはAGENTS.mdを読むようになった——v2.1.277・既定は「CLAUDE.mdが無いときだけ」

2026-08-05の初出時、Claude Codeの公式ドキュメントには「Claude Codeが読むのは CLAUDE.md であって AGENTS.md ではない」と書かれていた。その記述は消え、現在の同じページには「Claude Codeは AGENTS.md をプロジェクト指示として読める。他のコーディングエージェント向けに整えたリポジトリは、CLAUDE.mdもimportも設定も足さずに動く」とある。CHANGELOG 2.1.277の1行目も「AGENTS.md対応を追加：CLAUDE.mdの無いプロジェクトではAGENTS.mdを代わりに読む（Bedrock・Vertex・Foundryでは未対応）」だ。

ただし「読む」には条件がある。公式ドキュメントの表を、当サイトの実測（Linux x86_64・Claude Code 2.1.277・2026-09-19）で裏取りした結果と並べる。実測は、CLAUDE.mdとAGENTS.mdに別々の合言葉（返答の先頭・末尾に特定の語を置く指示）を仕込み、claude -p の返答にどちらが出るかで判定した。

「CLAUDE.mdがある」の判定に数えられるのは、作業ディレクトリとその上位にある CLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.md の3種類。個人の ~/.claude/CLAUDE.md、組織のmanaged CLAUDE.md、.claude/rules/ は数えられず、AGENTS.mdと並んで読み込まれ続ける。

この機能はエンジン本体ではなく、同梱の「mod」である agents-md として実装されている。4つのモード（claude-md-or-agents-md・claude-md-and-agents-md・claude-md・managed-only）の意味、設定の書き方、公開ソースの読み解きは Claude Code modsとは｜AGENTS.md対応のagents-md modをソースで読み、4つのモードを実測 に分けた。本記事では「結局どうすれば読まれるか」に絞る。

それでも橋が要る3つの場合

標準対応で解決しないケースが3つ残る。

・Claude固有の指示を足したい——CLAUDE.mdを置いた瞬間にAGENTS.mdは（既定では）読まれなくなる。CLAUDE.mdに @AGENTS.md と書くか、各自の設定で両方読むモードにする。チームで揃えるなら前者
・標準対応が効かないセッション——CHANGELOGがBedrock・Vertex・Foundryを未対応と明記。公式ドキュメントはさらに「フィーチャーフラグを取得しないセッション（サードパーティ経由・テレメトリ無効）」「対応版へ更新した直後の最初のセッション」を挙げる。/config にProject instructionsの行が出なければこの状態
・2.1.276以前の版が混在——古い版はAGENTS.mdを一切読まない。全員が更新するまでは橋を残す

この3つに当てはまるなら、初出時に整理した2つの方法がそのまま使える。

方法1: @importで読み込む

CLAUDE.mdの中で @ に続けてパスを書くと、そのファイルが起動時に展開されてコンテキストに載る。AGENTS.mdをそのまま取り込みつつ、Claude固有の指示を下に足せる。

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

インポートは相対パス・絶対パスの両方が使え、インポート先がさらに別ファイルをインポートする入れ子も最大4段まで許される。なお @ をコードスパン（バッククォート）で囲むとインポートされず、ただの文字列として扱われる。公式ドキュメントは「@AGENTS.md を含むCLAUDE.mdは残してよい。どのモードでもAGENTS.mdが二重に読まれることはない」としている。

方法2: symlinkにする

Claude固有の追記が不要で、かつ旧版やBedrock環境を抱えているなら、CLAUDE.mdをAGENTS.mdへのシンボリックリンクにするのが最も単純だ。

ln -s AGENTS.md CLAUDE.md

成功しても何も出力されない。反映を確かめるには、次のセッションで /context を実行して Memory files の一覧に CLAUDE.md が出ることを見る。symlinkの場合はCLAUDE.mdとして読まれるので、この確認方法が使える。

Next.jsの実物を読む——CLAUDE.mdの正体は9バイトのsymlinkだった

理屈はわかった。では実際の大規模プロジェクトはどちらを使っているのか。Next.jsで確かめた（以下、2026-08-05時点の実測）。

まず、vercel/next.js にAGENTS.mdは実在する。しかもcanaryブランチだけでなく、最新リリースタグ v16.3.0 にも入っている。ルートのAGENTS.mdは25,280バイト・512行あり、モノレポ構造の説明・ビルドコマンド・テスト方針が書かれている。

そしてファイルの冒頭2行目に、こう書いてある——CLAUDE.md はこのファイルへのsymlinkであり、同一のファイルである、と。

これをGitHub APIで裏取りすると、面白いことがわかる。Contents APIで CLAUDE.md を引くと、type が file、size が 25,280 と返ってくる。つまりAPIの応答だけを見ると、25KBの普通のファイルが独立して存在するように見える。

しかしGit treeを見ると正体が出る。

gh api "repos/vercel/next.js/git/trees/canary" \
  --jq '.tree[]|select(.path=="CLAUDE.md" or .path=="AGENTS.md")|{path,mode,size}'

返ってくるのはこうだ。

Gitのファイルモード 120000 はシンボリックリンクを表す。サイズはわずか9バイト——実際にblobを取得して展開すると、中身は AGENTS.md という9文字の文字列そのものだった。

同じ調べ方を主要リポジトリに広げると、方針が3つに分かれているのが見えた。

（いずれも各リポジトリの既定ブランチ、2026-08-05時点の実測）

Next.jsとAirflowはsymlinkで1本化している。2.1.277以降のClaude Codeから見ると、この2つは「CLAUDE.mdがある」プロジェクトなのでCLAUDE.md（＝実体はAGENTS.md）が読まれ、結果は変わらない。「AGENTS.mdのみ」の4つは、8月時点ではClaude Codeから規約が見えなかったが、いまは橋なしで読まれる。一方でReactとDenoはCLAUDE.mdしか置いていない——AGENTS.md対応のエージェントからは、これらのリポジトリの規約は見えないままだ。

Next.jsは階層ごとに書き分けている

Next.jsのAGENTS.mdはルートの1枚だけではない。リポジトリ全体を走査すると5個あり、サイズの配分に設計意図が読み取れる。

ルートに全体像を厚く書き、サブディレクトリには数百バイトの差分だけを置く——という配分になっている。この形が効くのは、Codexが「編集対象に最も近いAGENTS.mdを優先する」仕様だからだ。公式FAQも、指示が衝突した場合は最も近いファイルが勝ち、ユーザーのチャット指示がそのすべてに優先する、と説明している。Claude Codeも、サブディレクトリのファイルをReadした時点でその階層のAGENTS.mdを添付するので（前掲の実測表の最終行）、この配分はそのまま活きる。

ルートのAGENTS.md本文にも、この階層構造に沿った指示が書かれている。たとえば「サブディレクトリのファイルを編集する前に、リポジトリルートから対象ディレクトリまでの各階層の README.md をすべて読むこと」といった、エージェントの探索手順そのものを規定する記述がある。人間向けのREADMEには通常書かない種類の指示で、AGENTS.mdが何のための場所かがよく表れている。

何もしない・symlink・@importどれを選ぶか——4方式の比較

選択肢は「何もしない」が加わって4つになった。判断軸は「Claude固有の指示を足したいか」「標準対応が効かない環境を含むか」「Windowsを含むか」の3つだ。

「2ファイルを別々に手で書く」を非推奨にしているのは、内容のズレが必ず起きるからだ。片方だけ更新された規約は、どちらのエージェントを使っているかで挙動が変わる原因になり、しかも気づきにくい。CLAUDE.md側の書き方そのものは当サイトの「CLAUDE.mdの書き方」の記事に詳しい。

Codexは32 KiBで打ち切る——Airflowの35,417バイトは最後まで読まれない

Claude Code側の読み込み条件が片づいても、Codex側には読み込みバイト数の上限が残る。ここはCodexのソースコードを直接読んで確かめた（2026-08-05時点）。

codex-rs/core/src/config/mod.rs に上限の定数がある。

pub(crate) const AGENTS_MD_MAX_BYTES: usize = DEFAULT_PROJECT_DOC_MAX_BYTES; // 32 KiB

設定スキーマ（codex-rs/core/config.schema.json）でも project_doc_max_bytes の default は 32768 と定義されている。問題はこの32 KiBがどう消費されるかだ。codex-rs/core/src/agents_md.rs の読み込みループはこうなっている。

・max_total に32,768を入れ、これを remaining として持つ
・プロジェクトルートから作業ディレクトリまでのAGENTS.mdを順に読む
・ファイルサイズが remaining を超えたら、そのファイルを途中で切り捨てる
・remaining が0になったら、残りのファイルは読まずに打ち切る

つまり32 KiBは1ファイルあたりの上限ではなく、全ファイルで共有する予算である。しかも超過分は警告なしに切り捨てられる。

これがどう効くかを、実在するリポジトリの数字で見る。

Apache Airflow は、agents.md公式サイトが採用例として挙げている代表的なプロジェクトだ。ここのAGENTS.mdは全部で14個あり、合計84,176バイト。そしてルートの AGENTS.md 単体で35,417バイトある。

上限は32,768バイト。つまり——

ルートのファイルだけで予算を使い切るため、末尾2,649バイトが落ち、さらに13個のサブディレクトリ側AGENTS.mdは1バイトも読み込まれない。たとえば registry/AGENTS.md は20,339バイトあるが、registry/ の中でCodexを起動しても、この20KBは載らない計算になる。

対してNext.jsは25,280バイトで、残り7,488バイト（予算の23%）の余裕がある。ネストした4ファイル（合計1,350バイト）を足しても26,630バイトで上限内に収まる。

なおCodexには関連する設定がいくつかある。project_doc_fallback_filenames（既定は空配列）にファイル名を並べると、AGENTS.mdが無いときの代替として探しにいく。AGENTS.override.md はローカル優先の上書き用ファイル。プロジェクトルートの判定は project_root_markers（既定は .git）で行われ、ルートより上へは遡らない。

どのツールがAGENTS.mdを読むのか——設定が要るものと要らないもの

公式サイトが挙げている対応エージェントは20種類を超える。Codex（OpenAI）、Jules（Google）、Factory、Aider、goose、opencode、Zed、Warp、VS Code、Devin（Cognition）、UiPathのAutopilot & Coded Agents、Junie（JetBrains）、Amp、Cursor、RooCode、Gemini CLI、Kilo Code、Phoenix、Semgrep、GitHub Copilot coding agent、Ona、Windsurf、Augment Code——といった顔ぶれだ。2026-09-19時点の公式リポジトリREADMEにClaude Codeの名前はまだ無いが、実装側は追いついた。

ただし「対応」の中身は一様ではない。そのまま読むものと、設定を書いて初めて読むものがある。公式FAQが具体的な設定例を挙げているのは次の2つだ。

Aiderは .aider.conf.yml に1行足す。

read: AGENTS.md

Gemini CLIは .gemini/settings.json で読み込むファイル名を指定する。

{
  "context": { "fileName": "AGENTS.md" }
}

Claude Codeは、2.1.277以降なら「そのまま読む」側に入る。ただしCLAUDE.mdが無い場合に限る、という条件つきだ。Bedrock・Vertex・Foundryや旧版では、前述のとおりsymlinkか@importで橋を架ける必要が残る。ツールごとのファイル名の対応関係そのものは AI mdファイルとは｜CLAUDE.md・AGENTS.md・.cursorrules・GEMINI.mdの違いと使い分け早見表 に一覧がある。

Claude Codeの/initが読むもの

補足として、Claude Codeの /init は既存のルールファイルを読み取ってCLAUDE.mdを生成する。既定では Cursor のルール（.cursor/rules/ または .cursorrules）と Copilot のルール（.github/copilot-instructions.md）を参照する。さらに環境変数 CLAUDE_CODE_NEW_INIT=1 を設定すると、AGENTS.md・.devin/rules/・.windsurf/rules/ または .windsurfrules・.clinerules も読み込み対象に加わる（2026-08-05時点の確認）。

これは「AGENTS.mdの内容をCLAUDE.mdに取り込む」初期化の助けにはなるが、生成時に一度取り込むだけである点に注意がいる。しかも生成されたCLAUDE.mdが置かれた時点で、既定ではAGENTS.mdは読まれなくなる。AGENTS.mdだけで運用するなら /init は使わず、CLAUDE.mdを置かないほうが素直だ。

自分のリポジトリに導入する手順とアンチパターン

ここまでの内容を、実際に置くときの手順に落とす。

1. AGENTS.mdをリポジトリルートに作る。 必須の項目や決まったスキーマは無い。公式FAQも「必須フィールドは無い、ただのMarkdown」と明言している。よく書かれるのはプロジェクト概要・ビルドとテストのコマンド・コードスタイル・テスト手順・セキュリティ上の注意といったところだ。

2. CLAUDE.mdを置くかどうかを決める。 AGENTS.mdだけで足り、全員が2.1.277以上なら何も置かない。Claude固有の指示が要るならCLAUDE.mdに @AGENTS.md を書く。旧版やBedrock等を抱え、追記も不要ならsymlink。

ln -s AGENTS.md CLAUDE.md

3. 実際に読み込まれたかを確認する。 CLAUDE.md経由（symlink・@import）なら、セッションで /context を実行し、Memory files の一覧に CLAUDE.md が出ていることを目視する。標準対応で直接読ませた場合はMemory filesに出ないので、対話セッション冒頭の no CLAUDE.md found; AGENTS.md loaded: <パス> の行を見る。どちらにも出ていなければ読み込まれていない。

4. サイズを確認する。 Codexも使うなら32 KiBの予算を意識する。ルートのAGENTS.mdが肥大しているとサブディレクトリ側が落ちる。

find . -name AGENTS.md -not -path "./node_modules/*" -exec wc -c {} +

なお既存の AGENT.md（単数形）から移行する場合、公式FAQはリネームしたうえで後方互換のsymlinkを残す手順を示している。

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

アンチパターン

・CLAUDE.mdを置いたまま「AGENTS.mdも読まれている」と思い込む——2.1.277以降で最も起きやすい誤解。既定ではCLAUDE.mdが勝ち、AGENTS.mdは無言で落ちる。CLAUDE.local.md でも同じことが起きる
・標準対応を前提に橋を外したら、Bedrock利用者や旧版の同僚が読めなくなる——環境が混在するチームは、@AGENTS.md 1行のCLAUDE.mdを残すのが安全。二重には読まれない
・AGENTS.mdとCLAUDE.mdを手で二重管理する——必ずズレる。symlinkか@importで単一の実体にする
・「AGENTS.mdを読め」とCLAUDE.mdに文章で書く——Claudeが自分で開く気になったときしか効かない。公式ドキュメントも、消すか @AGENTS.md に置き換えよとしている
・ルートのAGENTS.mdに全部詰め込む——Codexの32 KiBの予算を1ファイルで使い切ると、サブディレクトリ向けの指示が丸ごと無効になる。Airflowが現にその状態にある
・矛盾する指示を複数階層に書く——公式FAQによれば、衝突時は編集対象に最も近いAGENTS.mdが勝ち、ユーザーのチャット指示がすべてに優先する。意図しない上書きを避けるため、階層ごとの役割を決めておく
・書きっぱなしにする——公式FAQは「living documentation として扱え」としている。規約が変わったら更新する

AGENTS.mdそのものの書き方——3層のロード構造やテンプレート、セクション設計の具体例——は AGENTS.mdとは｜書き方・ベストプラクティスとCLAUDE.mdの違いをCodex/Devinで解説 で詳しく扱っている。本記事はそこから一歩進んで「Claude Codeにいつ読まれるか」と「実際に何バイト読まれるか」に絞った。

まとめ——「標準対応した」と「どんな環境でも読まれる」は別の話

AGENTS.mdはLinux Foundation傘下に移り、6万を超えるプロジェクトが採用する共通フォーマットになった。そして2.1.277でClaude Codeも読むようになった。ただし既定は「CLAUDE.mdが無いときだけ」で、Bedrock・Vertex・Foundryや旧版では相変わらず読まれない。標準の普及、個々のツールの実装、そのツールが動く環境——3つは別物だ。

実務上の要点は3つに絞られる。

・CLAUDE.mdを置くか決める——AGENTS.mdだけで足り、全員が2.1.277以上なら置かない。Claude固有の指示や旧版・他環境の同僚がいるなら @AGENTS.md 1行のCLAUDE.mdを残す。残しても二重には読まれない
・確認する——CLAUDE.md経由なら /context の Memory files、直接読ませたなら冒頭の AGENTS.md loaded 行。出ていなければ読まれていない
・サイズを見る——Codexは合計32 KiBで静かに打ち切る。Airflowのようにルートだけで超過していると、サブディレクトリの指示は1バイトも載らない

Next.jsとAirflowが揃ってsymlinkを選んでいたのは、当時「実体を1つにする」ことが最も摩擦の少ない答えだったからだ。2.1.277以降、その9バイトのリンクは「旧版と他環境への保険」に役割を変えた。外すのは、チーム全員の環境を確かめてからでよい。

参照ソース

・AGENTS.md 公式サイト — フォーマットの目的、対応エージェント一覧、FAQ、Agentic AI Foundationへの移管
・agentsmd/agents.md（GitHub） — 公式リポジトリ（MIT）。openai/agents.md からのリダイレクト先
・Claude Code公式ドキュメント: How Claude remembers your project — §AGENTS.md：読まれる条件の表、Project instructionsの4値、CLAUDE.mdとの差分、以前の回避策の扱い
・Claude Code CHANGELOG 2.1.277 — 「Added AGENTS.md support」とBedrock・Vertex・Foundryの但し書き
・anthropics/claude-code — mods/agents-md — 標準対応を実装した同梱modのソースとREADME
・openai/codex — codex-rs/core/src/agents_md.rs — AGENTS.mdの探索・連結・切り捨てロジック
・vercel/next.js — AGENTS.md — 25,280バイトの実物。CLAUDE.mdはこれへのsymlink
・apache/airflow — AGENTS.md — 35,417バイト。32 KiB上限を超える実例