AGENTS.mdは、AIコーディングエージェントにビルド手順やテストコマンド、コード規約を伝えるためのMarkdownファイルです。公式サイトは「エージェント向けのREADME」と説明しており、OpenAI Codex、GitHub Copilot、Cursor、Gemini CLIなど20を超えるツールが読み込みます。Claude Codeもv2.1.277以降は直接読み込む仕様です。ただし、どの階層のファイルを読むか、CLAUDE.mdと並んだときにどちらを採るかはツールごとに違います。この記事では主要ツールの読み込み仕様を公式ドキュメントで突き合わせ、モノレポでの配置、Claude Codeとの併用設定、読み込みの確認コマンドまでを示します。
まとめ：AGENTS.mdを正本にして各エージェントへ読ませる要点
AGENTS.mdは必須項目の無いただのMarkdownで、リポジトリのルートに1本置けば、Codex・Copilot・Cursorはそのまま読みます。Claude Codeはv2.1.277以降なら読みますが、作業ディレクトリかその上位にCLAUDE.mdやCLAUDE.local.mdが1つでもあると、既定ではAGENTS.mdを読みません。Gemini CLIは既定のファイル名がGEMINI.mdなので、設定でAGENTS.mdを指定します。
複数のエージェントを使うチームでは、共通の指示をAGENTS.mdに集め、CLAUDE.mdには@AGENTS.mdのインポート行とClaude固有の指示だけを書く構成が、どのバージョンでも確実に動きます。モノレポでは優先順位の考え方がツールごとに違うため、上下のファイルで矛盾する指示を書かないことが前提です。
AGENTS.mdの仕様：エージェント向けREADMEとして決まっていること
必須項目を持たないプレーンなMarkdownとしてのAGENTS.mdの仕様
公式サイトagents.mdのFAQは、必須のフィールドは無く「AGENTS.mdはただの標準Markdown」だと答えています。見出しの名前も自由です。決まっているのは、編集中のファイルに最も近いAGENTS.mdが優先されること、チャットで利用者が明示した指示はすべてのファイルより優先されることの2点だけ。globで適用範囲を指定する仕組みは無く、適用範囲はディレクトリの位置で表します。
案内サイトは2025年8月20日にOpenAIが公開し、2026年11月4日時点ではLinux Foundation傘下のAgentic AI Foundationが管理しています。仕様はGitHubのagentsmd/agents.mdリポジトリにあり、ライセンスはMITです。同じく複数ツールで共有する手順書の仕様はSKILL.mdの仕様と移植性を保つ実装手順で扱っています。
READMEとAGENTS.mdに書く内容を実行可能なコマンドかどうかで分ける線引き
公式サイトでは、READMEは人間向けの概要や貢献ガイド、AGENTS.mdはエージェントには必要でもREADMEに載せると煩雑になる詳細の置き場とされています。pnpm testのようにそのまま実行できる行はAGENTS.mdへ、設計の経緯や画面の使い方はREADMEへ置くと迷いません。エージェントは記載されたテストを実行し、失敗を直してから作業を終えようとするため、テストコマンドの有無で完了時の品質が変わります。
エージェント別のAGENTS.md読み込み仕様：探索範囲と優先順位の違い
主要ツールのAGENTS.md探索範囲・ネスト対応・優先順位の比較表
| ツール | 既定で読むか | サブディレクトリ | 指示がぶつかったとき |
|---|---|---|---|
| Codex | 読む | ルートから作業位置まで連結 | 近いファイルが後ろに来て上書き |
| Claude Code | CLAUDE.mdが無い場合のみ | 開いたファイルの階層で追加読込 | 既定はCLAUDE.mdだけを採用 |
| GitHub Copilot | 読む | 最も近いファイル | 最も近いAGENTS.mdが優先 |
| VS Code（Copilot Chat） | ルートのみ読む | 実験的設定で有効化 | 加算で一般的な優先順位なし |
| Cursor | 読む | 親ディレクトリと結合 | より具体的な階層が優先 |
| Gemini CLI | 読まない | 設定後は階層的に読込 | ファイル名の設定で指定 |
2026年11月4日時点の各公式ドキュメントで確認した内容です。注意すべきはClaude Codeの行で、既存のCLAUDE.mdがあるリポジトリではAGENTS.mdを置いても何も変わりません。VS Codeは「ファイル間に一般的な優先順位は無い」と明記しており、矛盾した指示のどちらが効くかはツール次第です。
Codexの探索順序：グローバルからカレントまでの連結と32KiB上限
OpenAIのCodexドキュメントによると、Codexはまずホームディレクトリの~/.codex（環境変数CODEX_HOMEで変更可）を見て、AGENTS.override.mdがあればそれを、無ければAGENTS.mdを読みます。次にプロジェクトのルート（通常はGitのルート）から作業ディレクトリまで下りながら、各ディレクトリでAGENTS.override.md、AGENTS.md、代替ファイル名の順に1ファイルだけを採ります。
集めたファイルはルート側から順に空行で区切って連結され、作業ディレクトリに近いものほどプロンプトの後ろに来て上位の指示を上書きします。連結後の合計がproject_doc_max_bytes（既定32KiB）に達すると、それ以降のファイルは足されません。ルートのAGENTS.mdを長く書くほど、深い階層の指示が切り捨てられる順番です。指示はキャッシュされず実行のたびに組み立て直されるため、ファイルを直せば次の実行から反映されます。
Claude Code v2.1.277以降の直接読み込みとCLAUDE.md優先の条件
Claude Codeの公式ドキュメントによると、v2.1.277以降のClaude Codeは、作業ディレクトリとその上位にCLAUDE.md・.claude/CLAUDE.md・CLAUDE.local.mdのどれも無いときに限り、AGENTS.mdをプロジェクトの指示として読みます。ホームの~/.claude/CLAUDE.mdと組織配布のCLAUDE.md、.claude/rules/はこの判定に数えられず、AGENTS.mdと一緒に読み込まれます。
読まないファイルも決まっています。AGENTS.local.md、AGENTS.override.md、.agents/配下はClaude Codeの対象外です。CodexのつもりでAGENTS.override.mdに書いた指示は、Claude Codeには届きません。もう1つの落とし穴は、個人用のCLAUDE.local.mdを足しただけでAGENTS.mdが読まれなくなる点で、併用したいときは後述の設定値を変えます。
GitHub CopilotとVS CodeでAGENTS.mdが選ばれる条件
GitHubのドキュメントでは、AGENTS.mdはリポジトリ内のどこに何本置いてもよく、作業中はディレクトリツリーで最も近いファイルが優先されます。代わりにリポジトリのルートへ単一のCLAUDE.mdかGEMINI.mdを置く方法も認めています。
VS Code側はVS Codeのカスタム指示のドキュメントにある2つの設定で動きます。chat.useAgentsMdFileは既定で有効で、ワークスペースのルートにあるAGENTS.mdをチャットに添付する設定です。サブフォルダのAGENTS.mdは、実験的機能のchat.useNestedAgentsMdFilesも有効にしたときだけ探されます。copilot-instructions.mdとの使い分けや、機能ごとに読まれるファイルの違いはcopilot-instructions.mdの書き方と配置場所の解説で詳しく扱っています。
CursorとGemini CLIでAGENTS.mdを読ませる設定と制約
CursorのRulesドキュメントは、AGENTS.mdを.cursor/rulesの簡易な代替と位置づけています。ルートとサブディレクトリのどちらにも置け、サブディレクトリのファイルは親と結合され、より具体的な指示が優先されます。メタデータを持たないため、.mdcルールのようにglobで適用先を絞る書き方はできません。旧形式からの移行は.cursorrulesから.cursor/rulesへの移行手順にまとめています。
Gemini CLIのドキュメントでは、既定のコンテキストファイルはGEMINI.mdです。.gemini/settings.jsonのcontext.fileNameに"AGENTS.md"を含めると読み込み対象になり、配列で複数のファイル名も指定できます。同ページは、無料枠とGoogle One利用者向けのGemini CLIが2026年6月18日にAntigravity CLIへ置き換わったと告知しており、移行先の使い方はAntigravity CLI（agy）の使い方で解説しています。
AGENTS.mdを作成して配置する手順：ルート1本からモノレポ分割まで
TypeScriptのWebアプリを例に、AGENTS.mdを書いて置き、Claude Codeと共有し、読み込みを確かめるまでを示します。
ルートに置く最小構成のAGENTS.mdサンプルと書く6項目
最初の1本はリポジトリのルートに置きます。書く項目は、プロジェクト概要、セットアップ、テストとビルドのコマンド、コード規約、変更時の決まり、触ってはいけない場所の6つで足ります。
# AGENTS.md
## プロジェクト概要
- 受注管理のWebアプリ。apps/web（Next.js）と packages/api（Hono）のpnpmワークスペース
## セットアップ
- Node.js 22系、pnpm 10系を使う
- 依存関係: pnpm install
- 開発サーバー: pnpm dev
## テストとビルド（作業の最後に必ず実行する）
- 型チェック: pnpm typecheck
- 単体テスト: pnpm test
- Lint: pnpm lint --fix
## コード規約
- TypeScript strict mode。any は使わない
- 日付処理は src/lib/date.ts の関数を使い、Date を直接 new しない
## 変更時の決まり
- コミットメッセージは日本語で、変更内容と目的を1行で書く
- DBスキーマを変えたら packages/api/migrations に移行ファイルを追加する
## 触らないもの
- .env* と infra/ 配下は編集しない行ごとに「エージェントがそのまま実行できるか」を基準に書くと、量が膨らみません。CodexではAGENTS.mdが毎回プロンプトに入り、32KiBの上限を共有します。設計思想の説明や長い手順書は別のMarkdownに置き、必要な場面で読むよう1行で指す方が、下位ディレクトリの指示を押し出しません。
モノレポでサブディレクトリにAGENTS.mdを置く構成と上書き
モノレポでは、ルートに全体の決まり、各パッケージに固有のコマンドを置きます。次の構成なら、packages/apiの中で作業するエージェントは、ルートとapiの2本を読みます。
repo/
├── AGENTS.md # 全体: 規約・コミットの決まり・触らないもの
├── apps/
│ └── web/
│ └── AGENTS.md # web固有: pnpm --filter web test、Playwrightの実行方法
└── packages/
└── api/
├── AGENTS.md # api固有: マイグレーション手順、テスト用DBの起動
└── AGENTS.override.md # Codexだけが読む一時的な指示（Claude Codeは読まない）下位のファイルには上位と矛盾する指示を書かず、上位に無い情報だけを足します。Codexは近いファイルほど後ろに連結して上書きし、Cursorは具体的な指示を優先しますが、VS Codeは加算するだけで優先順位を持ちません。上書きに頼った書き方は、ツールを替えた途端に指示が衝突します。AGENTS.override.mdはCodexでの一時的な差し替え用で、他のツールでは効かないと割り切って使います。
Claude Codeと併用するための@AGENTS.mdインポートと設定値
既にCLAUDE.mdがあるリポジトリでは、CLAUDE.mdの先頭でAGENTS.mdを取り込みます。Claude CodeはインポートしたAGENTS.mdを先に読み、その後にClaude固有の指示を読みます。
# CLAUDE.md
@AGENTS.md
## Claude Code
- 破壊的なgit操作の前に必ず確認を取る
- 長い調査はサブエージェントに任せるこの形はv2.1.277より前のバージョンや、AGENTS.mdを直接読めないセッションでも動きます。インポートを残したまま新しいバージョンにしても、同じAGENTS.mdが2回読まれることはありません。CLAUDE.mdとAGENTS.mdを常に両方読ませたいときは、/configの「Project instructions」をclaude-md-and-agents-mdにするか、settings.jsonに次の設定を書きます。
{
"pluginConfigs": {
"cc-plugin-agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}この設定のIDはv2.1.285より前はagents-md@builtinで、古いバージョンと設定ファイルを共有するならそちらを使います。値はほかに、CLAUDE.mdだけを読むclaude-mdと、組織配布の指示だけを読むmanaged-onlyがあります。CLAUDE.md自体の書き方と権限の初期設定はClaude Codeの使い方とCLAUDE.md設定の手順を参照してください。
Codex・Claude Codeで読み込まれたファイルを確かめるコマンド
置いただけでは読まれているか分かりません。Codexは、作業ディレクトリを指定して読み込んだ指示の出どころを答えさせる方法が公式に案内されています。
# ルートで読み込まれている指示の要約
codex --ask-for-approval never "Summarize the current instructions."
# packages/api で作業したときに読んだファイルの一覧
codex --cd packages/api --ask-for-approval never "List the instruction sources you loaded."
# ログに読み込んだファイルを残す（./.codex-log/codex-tui.log を確認）
codex -c log_dir=./.codex-logClaude Codeでは、セッション内で/memoryを実行し、AGENTS.mdのパスが一覧にあるかを見ます。対話セッションでは、起動時に「no CLAUDE.md found; AGENTS.md loaded」で始まる行も表示される仕様です。ただし/memoryと/contextが直接読んだAGENTS.mdを表示するのはv2.1.280以降で、それより古い版ではプロジェクトの指示の内容をClaudeに尋ねて確かめます。
AGENTS.mdに寄せるかの判断基準：採用する体制と見送る体制
判断を分けるのは、使っているエージェントの数と、指示を強制したい度合いです。
複数のエージェントを併用するチームはAGENTS.mdを正本にする
CodexとCopilot、Claude CodeとCursorのように2種類以上のエージェントを同じリポジトリで使うなら、共通の指示はAGENTS.mdに一本化します。CLAUDE.md、copilot-instructions.md、.cursor/rulesに同じ規約を書き写す運用は、規約を直すたびに書き写し漏れが起き、内容がずれていく原因です。各ツール固有のファイルには、そのツールにしか無い機能の指示だけを残します。
受託開発のように開発者ごとに使うエージェントが違う現場ほど、この効果は大きくなります。社内で複数のエージェントを使い分ける体制づくりや、自社業務に合わせたエージェントの開発を検討している場合は、一創のAIエージェント開発で要件の整理から相談できます。
Claude Code単独で運用するならCLAUDE.mdのままで足りる理由
開発チーム全員がClaude Codeだけを使うなら、AGENTS.mdへ移す理由はありません。CLAUDE.mdは.claude/rules/によるパス別のルールや、指示の読み込み時に発火するInstructionsLoadedフックと組み合わせられますが、設定経由で読んだAGENTS.mdではこのフックが発火しません。移行のためだけにファイルを分けると、管理対象が増えるだけです。
どちらのファイルに書いても、指示はモデルへの文脈であって強制ではない点は同じです。「本番DBに接続しない」のように破られると困る決まりは、Claude CodeならPreToolUseフックで止めます。フックの設定方法はClaude Code Hooksのイベント一覧と設定方法で解説しています。
AGENTS.mdが読み込まれない4つの失敗パターンとシンボリックリンクの落とし穴
実務で起きやすい失敗は、重い順に次の4つです。
- CLAUDE.mdかCLAUDE.local.mdがどこかの上位ディレクトリにあり、Claude CodeがAGENTS.mdを読まない
- CLAUDE.mdに「AGENTS.mdを読むこと」と文章で書いただけで、Claudeがファイルを開くかどうか次第になる
- ルートのAGENTS.mdが長く、Codexの32KiB上限で下位ディレクトリの指示が足されない
- Windowsの開発者がいるのに
ln -s AGENTS.md CLAUDE.mdでシンボリックリンクを作り、その環境では1行のテキストファイルになる
4つ目はClaude Codeの公式ドキュメントも注意している点で、Gitはcore.symlinksが無効だとリンクを通常のテキストとして取り出します。Windowsの利用者が1人でもいるなら、リンクではなく@AGENTS.mdのインポートを選んでください。
AGENTS.mdの導入でよくある質問：CLAUDE.md併用・日本語・強制力
導入時に出やすい疑問に、公式ドキュメントの記載をもとに答えます。
AGENTS.mdとCLAUDE.mdは両方置いても問題ありませんか？
置けます。ただしClaude Codeは既定でCLAUDE.mdだけを読むため、CLAUDE.mdの先頭に@AGENTS.mdを書くか、Project instructionsをclaude-md-and-agents-mdに変えてください。両方入れても二重には読まれません。CopilotやCodexは、CLAUDE.mdの有無に関係なくAGENTS.mdを読みます。
AGENTS.mdは日本語で書いても効きますか？
効きます。仕様は標準のMarkdownであることしか定めておらず、言語の指定はありません。コマンド・ファイルパス・パッケージ名だけは、そのまま実行できるよう原文で書きます。コミットメッセージやコメントの言語もAGENTS.mdで指定しておくと、エージェントの出力が揃います。
AGENTS.mdに書いた指示は必ず守られますか？
保証はありません。Claude Codeの公式ドキュメントも、指示は文脈であって強制される設定ではないと明記しています。チャットで利用者が明示した指示もAGENTS.mdより優先されます。秘密情報を読ませない、特定のコマンドを実行させないといった決まりは、各ツールの権限設定やフックで止めてください。
モノレポで各パッケージにAGENTS.mdを置くと全部読まれますか？
全部は読まれません。どのツールも、ルートから作業中のファイルがある階層までのAGENTS.mdを対象にします。隣のパッケージのファイルは、そこで作業しない限り読み込まれない仕組み。VS Codeはサブフォルダ自体が実験的設定の扱いです。
AGENTS.mdはどうやって作り始めればよいですか？
この記事のサンプルの6項目から始め、エージェントが間違えた箇所を1行ずつ足していくのが早道です。Claude Codeでは/importを実行すると、他のエージェントの設定やAGENTS.mdをCLAUDE.md側へ取り込めます。既存のAGENT.mdなど別名のファイルがある場合、公式サイトはmv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.mdで改名し、互換のためにリンクを残す方法を案内しています。
関連記事
- copilot-instructions.mdとは？書き方とサンプル・配置場所、AGENTS.mdとの違い：Copilotの機能ごとに読まれる指示ファイルと、AGENTS.mdとの使い分けを扱っています。
- Claude Codeの使い方｜インストールから権限・CLAUDE.md設定、初日の進め方まで：CLAUDE.md側の書き方と権限の初期設定です。
- Agent Skillsとは？SKILL.md仕様とAAIF寄贈後も移植性を保つ実装手順：AGENTS.mdと同じく複数のエージェントで共有できる手順書の仕様です。
- .cursorrulesとは？非推奨の現状と.cursor/rules（.mdc）への移行・書き方：Cursor固有のルールとAGENTS.mdを併用するときの参考になります。
- OpenCodeとは？2.0の変更点・インストール・設定・無料モデルを解説：AGENTS.mdを読むオープンソースのコーディングエージェントです。
