AGENTS.mdとは｜対応23ツールとClaude Codeの例外【2026年8月】

最終更新：2026年8月（公式ドキュメントの記述を同月23日に再確認）

弊社では、Claude CodeとOpenAI Codexを毎日並行で走らせています。同じリポジトリを両方のツールで触るので、当然のように起きたのが「指示ファイルの二重管理」でした。

最初は素直にAGENTS.mdを1枚置いて済ませようとしました。ところがCodexは読むのに、Claude Codeがまったく反応しない。プロジェクトの前提を無視した提案を出してくる。ファイル名が悪いのか、置き場所が違うのかと、しばらく設定をいじり回しました。

答えは公式ドキュメントに書いてありました。Claude Codeは仕様としてAGENTS.mdを読まないのです。日本語の解説記事をいくつか読むと「Claude Codeも対応」と書かれているものが複数あり、そこで詰まった時間が正直もったいなかった。

この記事では、公式一次情報だけを根拠に「どのツールが読んで、どれが読まないのか」を確定させます。そのうえで、両方を1枚のファイルで運用する具体的な方法を書きます。弊社が実際に使っている構成そのままです。

AGENTS.mdとは何か — READMEとの決定的な違い

AGENTS.mdは、AIコーディングエージェントに向けてプロジェクトの前提を渡すためのMarkdownファイルです。公式サイトの定義では「AIコーディングエージェント向けのガイダンス用シンプルなオープンフォーマット」とされています。

READMEとの違いは、読み手が誰かという1点に尽きます。READMEは人間向けで、プロジェクトの概要や導入手順を書きます。AGENTS.mdは機械向けで、エージェントが作業するために必要な文脈と制約を書きます。

この区別が実務で効いてくるのは、「人間には自明だが明文化されていないルール」を書く場面です。たとえば「テストはnpm testではなくmake testで回す」「src/legacy/配下は触らない」といった前提は、人間なら口頭で共有できますが、エージェントには毎回説明が必要になります。それを1枚に固定するのがAGENTS.mdの役割です。

標準としての位置づけも整理しておきます。AGENTS.mdはOpenAI・Sourcegraph・Google・Cursorらが共同で策定し、現在はLinux Foundation傘下のAgentic AI Foundation（AAIF）が管理するオープン標準として運用されています。公式サイトによれば60,000を超えるオープンソースプロジェクトが採用しており、OpenAIのメインリポジトリだけで88個のAGENTS.mdが置かれています。

対応ツール23種の全リスト【2026年8月時点・公式準拠】

公式サイトが対応を明記しているツールを、そのまま列挙します。伝聞や推測は混ぜていません。

この23ツールに共通するのは、リポジトリ内のAGENTS.mdを自動で探して読み込むという挙動です。ツールごとに設定を書き分ける必要がなく、1枚置けば横断的に効く。これが「事実上の共通フォーマット」と呼ばれる理由です。

そして、この一覧を上から下まで見てもらうと分かるとおり、Claude Codeは含まれていません。次章で、その理由を公式の記述で確認します。

Claude Codeだけが読まない — 公式が明言する唯一の例外

Anthropicの公式ドキュメント（Claude Codeのメモリ仕様ページ）には、AGENTS.mdという見出しが立っていて、そこにこう書かれています。

Claude Code reads CLAUDE.md, not AGENTS.md.
（Claude Codeが読むのはCLAUDE.mdであり、AGENTS.mdではない）

曖昧さのない断定です。Claude Codeが自動で読み込むのは、以下の階層に置かれたCLAUDE.mdだけです。

読み込み順は上から下、つまり広いスコープから狭いスコープへ。ディレクトリツリーではルート側から順に連結され、起動ディレクトリに近いものが最後に読まれます。上書きではなく連結である点は、運用設計で効いてきます。

なお、AGENTS.md側の階層ルールは思想が違います。公式サイトでは「ディレクトリツリー内で編集対象ファイルに最も近いAGENTS.mdが優先」とされており、モノレポではサブプロジェクトごとに置く運用が想定されています。連結のClaude Code、近接優先のAGENTS.md。この差は覚えておく価値があります。

橋渡し4手法 — 二重管理せずに両方へ効かせる

ここが本題です。AGENTS.mdとCLAUDE.mdの中身を2枚コピーして持つのは、更新漏れの温床になります。公式が示している方法は4つあり、弊社が採用しているのは1番目です。

方法1：CLAUDE.mdから@インポートする（推奨）

CLAUDE.mdの先頭に1行書くだけです。インポートされたファイルはセッション開始時に展開され、その後にClaude固有の指示を追記できます。

@AGENTS.md

## Claude Code

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

この形なら、共通ルールはAGENTS.mdに一元化したまま、Claude Codeにだけ効かせたい指示を下に足せます。インポートは相対パス・絶対パスの両方が使え、再帰的なインポートも最大4階層まで許容されます。

方法2：シンボリックリンクを張る

Claude固有の追記が不要なら、リンク1本で済みます。

ln -s AGENTS.md CLAUDE.md

成功しても何も出力されません。次のセッションで /context を実行し、Memory files の一覧にCLAUDE.mdが出ていれば読み込めています。ただしWindowsではシンボリックリンク作成に管理者権限か開発者モードが必要なため、公式も方法1のインポートを推奨しています。

方法3：/import コマンドで取り込む

Claude Code v2.1.213以降では /import が使えます。AGENTS.mdなどの指示ファイルを対応するCLAUDE.mdへ一度きりコピーし、MCPサーバー・コマンド・サブエージェント・スキルの設定も引き継ぎます。既存プロジェクトをClaude Codeへ移行するときの初期セットアップ向きです。

方法4：/init に読み取らせる

環境変数 CLAUDE_CODE_NEW_INIT=1 を設定して /init を実行すると、AGENTS.mdに加えて .devin/rules/、.windsurf/rules/、.clinerules まで読み取り、生成するCLAUDE.mdへ反映します。なお環境変数なしの通常の /init でも、Cursorの .cursor/rules/ とCopilotの .github/copilot-instructions.md は読み取り対象です。

コピペで使えるプロンプト5種

AGENTS.mdは「何を書くか」で品質が決まります。ゼロから考えるより、既存のリポジトリから抽出させたほうが早く、しかも実態に合います。弊社で使っているプロンプトをそのまま置きます。

1. 既存リポジトリからAGENTS.mdを起こす

このリポジトリを調査して AGENTS.md の草案を作ってください。

含める項目:
- プロジェクト概要（3行以内）
- ビルド/テスト/lint の実行コマンド（package.json や Makefile から実際に確認すること）
- コードスタイル規約（既存コードから推測ではなく、設定ファイルの実値を根拠にする）
- 触ってはいけないディレクトリと理由
- コミットメッセージ / PR の規約

制約:
- 推測で書かず、根拠にしたファイル名を各項目の末尾に括弧書きで添えること
- 200行以内に収めること

2. 人間の暗黙知を吐き出させる棚卸し

これから新しいメンバーがこのリポジトリに参加します。
コードを読んだだけでは絶対に分からない前提を、質問形式で10個挙げてください。

例:「なぜ src/legacy/ は変更禁止なのか」
その10個のうち、AGENTS.md に書くべきものを選んで理由を添えてください。

3. 橋渡しが効いているかを検証する

いま読み込まれている指示ファイルを列挙してください。
そのうえで、AGENTS.md に書かれている「テストの実行コマンド」を
そのまま引用して答えてください。

引用できない場合は「読み込めていない」と明言してください。

3番目は地味ですが重要です。インポートやリンクが効いているかを、推測でなく引用で確認できます。読めていなければ引用できないので、設定ミスがその場で分かります。

4. モノレポ用に分割する

このモノレポの構成を確認し、AGENTS.md を階層分割する案を出してください。

- ルートに置くべき「全体共通の規約」
- 各パッケージに置くべき「そのパッケージ固有の規約」
を分けて、それぞれのファイルパスと内容の骨子を提示してください。

判断基準: 2つ以上のパッケージで共通するならルート、1つだけならパッケージ側。

5. 肥大化したファイルを削る

この AGENTS.md を読み、以下の基準で削減案を出してください。

削る対象:
- コードやディレクトリ構成を見れば分かる情報
- 一度しか使わない手順（別ドキュメントへ分離すべきもの）
- 他の項目と矛盾している記述

残す対象:
- ツールの初期値と違う独自ルール
- 過去に事故が起きた箇所の注意書き

削減前後の行数と、削った理由を項目ごとに示してください。

5番目が必要になるのは、運用して数ヶ月経った頃です。Anthropicの公式ドキュメントはCLAUDE.mdについて200行以内を目標にすべきとし、長いファイルはコンテキストを消費して指示の遵守率を下げると明記しています。AGENTS.md側にも同じ力学が働きます。

【要注意】現場で踏んだ失敗パターン4つ

弊社がClaude CodeとCodexを併用するなかで、実際に時間を溶かした4つです。

失敗1：AGENTS.mdを置いてClaude Codeにも効いていると思い込む

❌ ルートにAGENTS.mdを1枚置いて完了とする
⭕ CLAUDE.mdから @AGENTS.md でインポートし、/context の Memory files に出ることを確認する

これが冒頭で書いた、私たちが最初に踏んだ穴です。Codex側では機能しているぶん、気づくのが遅れます。「片方だけ挙動がおかしい」と感じたら、まず読み込みを疑ってください。

失敗2：コードを読めば分かることを延々と書く

❌ ディレクトリ構成の一覧、依存パッケージの列挙、アーキテクチャの概説
⭕ ツールの初期値と異なる独自ルール、過去に事故った箇所の注意、明文化されていない判断基準

エージェントはリポジトリを読めます。読めば分かることを書くと、行数だけ増えて肝心の指示が埋もれます。Anthropicの公式ドキュメントも、/doctor による削減提案では「コードから導出できる内容を削り、落とし穴・理由・ツール初期値と違う規約を残す」という方針を採っていると説明しています。判断基準としてそのまま使えます。

失敗3：矛盾した指示を放置する

❌ ルートと各パッケージのAGENTS.mdで、テストコマンドの記述が食い違ったまま
⭕ 階層をまたいだ矛盾を定期的に棚卸しする

公式ドキュメントは「2つのルールが矛盾する場合、Claudeはどちらかを恣意的に選ぶ可能性がある」と明言しています。矛盾は無視されるのではなく、どちらが採用されるか分からない状態になる。ここが怖いところです。

失敗4：指示ファイルで「絶対に止めたい操作」を止めようとする

❌ AGENTS.mdに「本番へのpushは禁止」と書いて安心する
⭕ 強制したい操作はhookや権限設定でブロックする

これは実装層の話として重要です。公式ドキュメントは、CLAUDE.mdについて「Claudeはこれをコンテキストとして扱い、強制された設定としては扱わない」「Claudeの判断に関わらず操作をブロックしたいなら、PreToolUseフックを使うこと」と明記しています。指示ファイルはガイドであって、ガードレールではありません。破壊的操作の抑止を指示文だけに依存させないでください。

弊社の実運用 — 2ツールを1本のルールで回す

参考までに、弊社の構成を書いておきます。特別なことはしていません。

Claude Code側は階層を分けています。~/.claude/CLAUDE.md に全プロジェクト共通の停止線（外部送信の承認ルール、ファイル配置ルールなど）を置き、各リポジトリのCLAUDE.mdにはそのプロジェクト固有の事情だけを書きます。連結して読まれるので、リポジトリ側で共通ルールを繰り返す必要がありません。

Codex側は ~/.codex/AGENTS.md をグローバルの指示として持ち、~/.codex/rules/ に危険操作の停止ルールを分離しています。そしてClaude側の資産をCodex側へ日次で同期するスクリプトを、launchdで毎朝走らせています。

ここで学んだのは、同期の対象を絞ることの重要性です。当初は全部ミラーしようとして、Codex側のコンテキスト予算を圧迫し、かえって指示の可視性が落ちました。いまはルールとプロンプトだけ自動同期し、スキル類は必要なものだけ明示的に追加する運用にしています。

非エンジニアがこうした運用を組めるようになるまでの具体的な流れは、非エンジニアを3ヶ月で社内FDEにする方法で書いています。

そのまま使えるAGENTS.mdテンプレート

ゼロから考えると手が止まるので、2種類置いておきます。まずは最小版から始めて、詰まったところだけ足していくのが失敗しにくい進め方です。

最小版（初日はこれで十分）

# AGENTS.md

## プロジェクト概要
社内向けの在庫管理API。Node.js 22 / TypeScript / PostgreSQL。

## コマンド
- 開発サーバー: `npm run dev`
- テスト: `npm test`（Vitest。単体のみ）
- E2E: `npm run test:e2e`（Playwright。CIでのみ実行）
- Lint: `npm run lint`（自動修正は `npm run lint:fix`）

## コードスタイル
- インデントは半角2スペース
- 型定義は `src/types/` に集約する
- `any` は使わない。どうしても必要なら理由をコメントで書く

## 触らないディレクトリ
- `src/legacy/` — 移行前の旧実装。参照はOK、変更は禁止
- `migrations/` — 手動編集禁止。`npm run migrate:create` で生成する

## コミット / PR
- コミットは Conventional Commits（`feat:` `fix:` `chore:`）
- PRには再現手順とテスト結果を貼る

ポイントは、すべての項目が検証可能な具体性で書かれていることです。「テストを書く」ではなく「Vitestで単体、E2EはCIのみ」。「きれいに書く」ではなく「半角2スペース」。この差が遵守率に出ます。

実務版に足す項目

運用が始まったら、次の3ブロックを追加します。どれも「事故ってから足した」たぐいの内容です。

## セキュリティ
- `.env` `*.pem` `credentials.json` は読み込まない・出力しない
- 外部APIキーが必要な処理は、キー自体でなく環境変数名で参照する
- 本番DBへの接続文字列をコードやログに書かない

## 破壊的操作
- `git push --force` は禁止
- DBのマイグレーション巻き戻しは実行せず、手順だけ提示する
- ファイル削除は1件ずつ提示して承認を取る

## 判断に迷ったとき
- 仕様が曖昧なら実装せず、選択肢を2つ出して質問する
- 既存の実装パターンと矛盾する場合は、既存側に合わせる

ただし前章で書いたとおり、「破壊的操作」ブロックは強制力を持ちません。本当に止めたい操作は、Claude Codeならhookや権限設定で塞いでください。このブロックの役割は、エージェントに意図を伝えて事故の確率を下げることであって、防壁ではありません。

チームで運用する5つのポイント

1人で使うぶんには置くだけで済みますが、チームで共有し始めると別の論点が出てきます。

1. バージョン管理に載せる。 AGENTS.mdはチーム共有の資産なので、リポジトリにコミットします。逆に個人の好み（好きなテストデータ、自分用のサンドボックスURL）は共有ファイルに書かず、Claude Codeなら CLAUDE.local.md を作って .gitignore に入れます。

2. 更新のきっかけを決めておく。 Anthropicの公式ドキュメントは、CLAUDE.mdへ追記すべきタイミングとして「同じミスが2回目に起きたとき」「コードレビューでエージェントが知っておくべきだった指摘が出たとき」「前のセッションと同じ訂正を打ったとき」「新メンバーに同じ説明が必要なとき」を挙げています。AGENTS.mdでもそのまま使える基準です。

3. レビュー対象にする。 AGENTS.mdの変更はPRでレビューします。ここが野放しだと、個人の思いつきがチーム全体の挙動を変えてしまいます。

4. 定期的に矛盾を掃除する。 階層をまたいだ矛盾は、放置すると「どちらが効くか分からない」状態を生みます。四半期に一度でいいので、全階層を並べて読む時間を取ってください。

5. 肥大化を測る。 行数は放っておくと増えます。200行という目安を持ち、超えたら前章のプロンプト5番で削減案を出させるのが手軽です。ファイルを分けても、インポートで読み込む以上コンテキストの消費量は変わらない点に注意してください。分割は整理のためであって、軽量化にはなりません。

法人での本格導入や、チーム全体でのAIコーディング運用設計については、Uravationの法人向けサービスでご相談いただけます。

導入5ステップ — 所要時間の目安つき

ここまでの内容を、実際の手順に落とします。既存プロジェクトへ後から入れる想定です。

ステップ1：現状の指示ファイルを棚卸しする（5分）

まず、リポジトリに何が散らばっているかを確認します。ツールごとに別々のファイルが増えているのはよくある状態です。

ls -la AGENTS.md CLAUDE.md .cursorrules .clinerules 2>/dev/null
ls -la .cursor/rules/ .github/copilot-instructions.md .windsurf/ 2>/dev/null

複数見つかったら、それぞれの中身が矛盾していないかをこの時点で確認してください。統合してから進めたほうが、あとの手戻りが減ります。

ステップ2：AGENTS.mdを1枚作る（15分）

前章の最小版テンプレートをベースに、前々章のプロンプト1番でリポジトリから実値を抽出させます。ポイントは、ビルドコマンドやスタイル規約を推測させず、設定ファイルの実値を根拠にさせることです。ここで推測が混ざると、以降ずっと間違った前提で動きます。

ステップ3：Claude Code側の橋渡しを張る（1分）

printf '@AGENTS.mdn' > CLAUDE.md

Claude固有の指示を足したい場合は、この下に見出しを作って書き足します。同一で良いならシンボリックリンクでも構いません。

ステップ4：読み込みを検証する（2分）

ここを飛ばさないでください。設定した気になって進むのが、いちばん時間を失うパターンです。

Claude Codeのセッションで /context を実行し、Memory files の一覧にCLAUDE.mdが出ているかを見ます。そのうえで、前々章のプロンプト3番を投げて、AGENTS.mdの中身を引用させます。引用できれば確実に読めています。

ステップ5：チームへ展開する（10分）

AGENTS.mdとCLAUDE.mdをコミットし、CLAUDE.local.md を .gitignore に追加します。PRの説明に「AIエージェント向けの指示ファイルを追加した」ことと、更新したい場合はPRを出す運用であることを書いておくと、以降の運用が揃います。

ここまでで、合計30分強です。作業量としては小さいのに、エージェントの提案精度に効く範囲は広い。費用対効果でいえば、AIコーディング環境の整備の中でもかなり上位に来る作業だと考えています。

よくある質問

AGENTS.mdはどこに置けばいいですか

リポジトリのルートです。モノレポの場合は各サブプロジェクトにも置けます。公式仕様では「ディレクトリツリー内で編集対象ファイルに最も近いAGENTS.mdが優先」されます。

AGENTS.mdとCLAUDE.mdの違いは何ですか

AGENTS.mdは23ツールが読む横断標準、CLAUDE.mdはClaude Code専用です。両者は共存できます。Claude CodeはAGENTS.mdを読まないため、CLAUDE.mdからインポートするかリンクを張って橋渡しします。

書き方の決まりはありますか

フォーマットは通常のMarkdownで、必須の書式はありません。公式が推奨するセクションは、プロジェクト概要・ビルド/テストコマンド・コードスタイル・テスト手順・セキュリティ上の考慮事項・コミットメッセージ/PR規約です。

日本語で書いても機能しますか

機能します。ただし冗長になりやすいので、箇条書きと具体的な数値・コマンド名を優先してください。「適切にフォーマットする」より「インデントは半角2スペース」のほうが遵守されます。

ベストプラクティスは何ですか

①コードから導出できる情報を書かない ②検証可能な具体性で書く ③200行以内を目安に保つ ④矛盾を定期的に棚卸しする ⑤強制したい操作はhookや権限設定に逃がす。この5つです。

Codexでの具体的な書き方をもっと知りたい

Codexに特化した階層設計とテンプレートは、Codex AGENTS.mdの書き方｜7パターンと階層設計で詳しく解説しています。本記事はツール横断の標準仕様、あちらはCodex実装に振った内容です。

広まっている誤解の訂正 — 2026年8月時点のスナップショット

この記事を書くにあたって日本語の解説記事をひととおり読みましたが、事実と食い違う記述が複数ありました。実害が出やすいものを3つ挙げて訂正しておきます。

誤解1：「Claude CodeもAGENTS.mdに対応している」

対応していません。Anthropicの公式ドキュメントに「Claude Code reads CLAUDE.md, not AGENTS.md」と明記されています。この誤解が厄介なのは、設定が効いていないことに気づけない点です。エージェントは何も言わずに、前提を知らないまま作業を進めます。

実際に効いているかどうかは、思い込みで判断せず /context と引用テストで確認してください。

誤解2：「ファイルを分割すればコンテキストが軽くなる」

軽くなりません。公式ドキュメントは、インポートで分割しても「インポートされたファイルは起動時に読み込まれコンテキストへ入る」と明記しています。分割の効能は整理と保守のしやすさであって、トークン消費の削減ではありません。

本当に軽くしたいなら、パス限定のルール（対象ファイルを触ったときだけ読み込まれる仕組み）へ移すか、そもそも記述を削る必要があります。

誤解3：「指示ファイルに書けば守らせられる」

守らせられません。前章でも触れましたが、公式は指示ファイルを「コンテキストであって、強制された設定ではない」と位置づけています。守ってほしい規約はここに書き、守らせないと事故になる操作はhookや権限設定で物理的に塞ぐ。この2層に分けるのが正しい設計です。

この線引きを曖昧にしたまま「AGENTS.mdに禁止と書いたから大丈夫」としている運用は、けっこう見かけます。事故が起きるまで気づけない種類のリスクなので、早めに分けておくことをおすすめします。

まとめ — 5分で終わる作業

この記事の要点をもう一度だけ整理します。

• AGENTS.mdは23ツールが読むオープン標準で、Agentic AI Foundationが管理している
• Claude Codeだけは読まない。これは公式ドキュメントに明記された仕様
• 橋渡しはCLAUDE.mdに @AGENTS.md と1行書くだけ
• 読み込めたかは /context の Memory files で確認する
• 指示ファイルはガイドであって強制力はない。止めたい操作はhookで止める

AIエージェントを業務に組み込む全体像は、AIエージェント完全ガイドにまとめています。あわせてどうぞ。

参考・出典

• AGENTS.md 公式サイト（対応ツール一覧・配置ルール・推奨セクション／2026年8月23日参照）
• Anthropic「How Claude remembers your project」（CLAUDE.md階層・AGENTS.mdの扱い・インポート構文・200行推奨／2026年8月23日参照）
• ＠IT「コーディングAIをもっと使いやすく、新標準『AGENTS.md』」（標準化の経緯／2026年8月23日参照）

佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。
100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。
SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。