AGENTS.mdをClaude Codeに読ませる｜symlinkと@importの違いとCodex 32KiB上限

AIコーディングエージェントにプロジェクトのルールを教えるファイルは、ツールごとにバラバラだった。その乱立を1つにまとめようとして生まれたのが AGENTS.md で、公式サイトによれば6万を超えるOSSプロジェクトが採用している。ところが——Claude CodeはAGENTS.mdを読まない。

この記事では、AGENTS.mdをClaude Codeに読ませる2つの方法を、公式ドキュメントの記述と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時点）。

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

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

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

Claude CodeはAGENTS.mdを読まない——公式ドキュメントが明言している

ここが本題だ。Claude Codeの公式ドキュメントには AGENTS.md という見出しの節が置かれていて、そこにはこう書かれている——Claude Codeが読むのは CLAUDE.md であって AGENTS.md ではない、と。

つまり、AGENTS.mdだけを置いたリポジトリでClaude Codeを起動しても、そこに書いた規約は一切読まれない。エラーも警告も出ない。ただ静かに無視されるので、気づきにくい。

公式ドキュメントが案内している橋は2つある。CLAUDE.mdからAGENTS.mdをインポートする方法と、CLAUDE.mdをAGENTS.mdへのsymlinkにする方法だ。順に見ていく。

方法1: @importで読み込む

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

@AGENTS.md

## Claude Code

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

インポートは相対パス・絶対パスの両方が使え、インポート先がさらに別ファイルをインポートする入れ子も最大4段まで許される。なお @ をコードスパン（バッククォート）で囲むとインポートされず、ただの文字列として扱われる。

方法2: symlinkにする

Claude固有の追記が不要なら、CLAUDE.mdをAGENTS.mdへのシンボリックリンクにしてしまうのが最も単純だ。公式ドキュメントもこのコマンドをそのまま載せている。

ln -s AGENTS.md CLAUDE.md

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

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

理屈はわかった。では実際の大規模プロジェクトはどちらを使っているのか。Next.jsで確かめた。

まず、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本化している。一方でReactとDenoはCLAUDE.mdしか置いていない——AGENTS.md対応のエージェントからは、これらのリポジトリの規約は見えないことになる。移行はまだ途上だ。

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

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

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

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

symlinkと@importどちらを選ぶか——3方式の比較

橋の架け方は実質3つある。判断軸は「Claude固有の指示を足したいか」と「Windowsを含むか」の2つだ。

「2ファイルを別々に手で書く」を非推奨にしているのは、内容のズレが必ず起きるからだ。片方だけ更新された規約は、どちらのエージェントを使っているかで挙動が変わる原因になり、しかも気づきにくい。CLAUDE.md側の書き方そのものは CLAUDE.mdの書き方？AIに仕事を任せる人が最初に学ぶべきセクション設計と失敗パターン に詳しい。

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

橋を架けたあとに効いてくるのが、読み込みバイト数の上限だ。ここはCodexのソースコードを直接読んで確かめた。

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——といった顔ぶれだ。

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

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

read: AGENTS.md

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

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

そしてClaude Codeは、前述のとおりsymlinkか@importで橋を架ける必要がある。この3つは「対応ツール一覧に載っているが、追加の一手が要る」グループだと捉えるとよい。ツールごとのファイル名の対応関係そのものは AI時代のMDファイルを整理する｜CLAUDE.md・.cursorrules・AGENTS.md・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 も読み込み対象に加わる。

これは「AGENTS.mdの内容をCLAUDE.mdに取り込む」初期化の助けにはなるが、生成時に一度取り込むだけである点に注意がいる。以後AGENTS.mdを更新しても自動では追随しないので、継続的に同期させたいならやはりsymlinkか@importを使う。

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

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

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

2. Claude Code向けの橋を架ける。 Claude固有の指示が不要ならsymlink、あるいはWindowsを含むなら@import。

ln -s AGENTS.md CLAUDE.md

3. 実際に読み込まれたかを確認する。 Claude Codeのセッションで /context を実行し、Memory files の一覧に CLAUDE.md が出ていることを目視する。ここに出ていなければ読み込まれていない。

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

アンチパターン

・AGENTS.mdだけ置いてClaude Codeでも読まれると思い込む——最も多い誤解。エラーが出ないので気づきにくい。/context で確認する習慣をつける
・AGENTS.mdとCLAUDE.mdを手で二重管理する——必ずズレる。symlinkか@importで単一の実体にする
・ルートのAGENTS.mdに全部詰め込む——32 KiBの予算を1ファイルで使い切ると、サブディレクトリ向けの指示が丸ごと無効になる。Airflowが現にその状態にある
・矛盾する指示を複数階層に書く——公式FAQによれば、衝突時は編集対象に最も近いAGENTS.mdが勝ち、ユーザーのチャット指示がすべてに優先する。意図しない上書きを避けるため、階層ごとの役割を決めておく
・書きっぱなしにする——公式FAQは「living documentation として扱え」としている。規約が変わったら更新する

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

まとめ——「標準になった」と「全部のツールが読む」は別の話

AGENTS.mdはLinux Foundation傘下に移り、6万を超えるプロジェクトが採用する共通フォーマットになった。それでもClaude Codeは読まない。この2つは矛盾ではなく、標準の普及と個々のツールの実装が別物だというだけのことだ。

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

・橋を架ける——ln -s AGENTS.md CLAUDE.md か、CLAUDE.mdに @AGENTS.md の1行。Claude固有の指示を足すなら後者、Windowsを含むなら後者
・確認する——/context の Memory files に出ているかを見る。出ていなければ読まれていない
・サイズを見る——Codexは合計32 KiBで静かに打ち切る。Airflowのようにルートだけで超過していると、サブディレクトリの指示は1バイトも載らない

Next.jsとAirflowが揃ってsymlinkを選んでいるのは、この問題に対する現時点で最も摩擦の少ない答えが「実体を1つにする」ことだからだろう。9バイトのシンボリックリンク1本で、2つのエコシステムに同じ規約を配れる。

参照ソース

・AGENTS.md 公式サイト — フォーマットの目的、対応エージェント一覧、FAQ、Agentic AI Foundationへの移管
・agentsmd/agents.md（GitHub） — 公式リポジトリ（MIT）。openai/agents.md からのリダイレクト先
・Claude Code公式ドキュメント: How Claude remembers your project — 「Claude Code reads CLAUDE.md, not AGENTS.md」の記述、@import・symlinkの案内、/init の読み取り対象
・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上限を超える実例