AGENTS.mdとは？CLAUDE.mdとの違いと書き方を解説

AGENTS.md は、AI コーディングエージェントにプロジェクト固有の指示を渡すための、リポジトリ直下に置くプレーンな Markdown ファイルです。ビルドコマンド、テストの実行方法、コードの流儀、プルリクエストの作法といった「人間の新メンバーに最初に説明すること」を、エージェントが毎回読める場所に書いておく仕組みで、OpenAI が始めた形式が 2025 年 12 月に Linux Foundation 傘下の Agentic AI Foundation へ移管されました。2026 年 9 月 18 日には Claude Code も AGENTS.md の直接読み込みに対応し、主要なコーディングエージェントが同じファイル名を見に来る状態になっています。この記事では、AGENTS.md の仕様と主要エージェントごとの読まれ方の違い、CLAUDE.md との使い分け、何を書いて何を書かないか、長くなると守られなくなる理由、そして指示ファイルがエージェントの信頼境界の内側にあるという前提を解説します。

AGENTS.mdとは何か：エージェント向けの README

AGENTS.md は「コーディングエージェントを導くためのシンプルでオープンな形式」で、公式サイトは「エージェントのための README」と説明しています。README.md が人間の開発者に向けてプロジェクトの概要や使い方を説明するのに対し、AGENTS.md はエージェントが作業を始める前に知っておくべき、より実務的な情報を置く場所です。

公式サイトによれば、この形式は 6 万を超えるオープンソースプロジェクトで使われています。もともとは OpenAI の Codex が読むファイルとして広まりましたが、2025 年 12 月 9 日に Linux Foundation が Agentic AI Foundation（AAIF）の設立を発表した際、Anthropic の Model Context Protocol（MCP）、Block の goose と並ぶ 3 つの基幹プロジェクトの 1 つとして OpenAI が AGENTS.md を寄贈し、現在は特定ベンダーの所有物ではなくなっています。プレスリリースは AGENTS.md を「AI コーディングエージェントに、リポジトリやツールチェーンをまたいで安定して動作するために必要なプロジェクト固有のガイダンスを一貫して与える、シンプルで普遍的な標準」と位置づけています。

仕様と呼べるほどの決まりはほとんどありません。公式サイトの FAQ は次のように答えています。

• 必須の項目はない。 「AGENTS.md は標準的な Markdown です。好きな見出しを使ってください」
• モノレポでは各パッケージに置く。 「エージェントはディレクトリツリーの中で最も近いファイルを自動的に読みます」
• 衝突したら近いほうが勝ち、チャットの指示が最優先。 「編集対象のファイルに最も近い AGENTS.md が優先され、明示的なユーザーのチャットプロンプトはすべてに優先します」
• 書いたコマンドは実行される。 テストや lint のコマンドを列挙しておくと「エージェントは関連するプログラム的なチェックを実行し、失敗を修正しようとします」

公式サイトの例に載っている見出しは「開発環境のヒント」「テストの手順」「プルリクエストの手順」の 3 つで、内容は「pnpm を使う」「コミット前に必ず lint と型検査を通す」「タイトルは [パッケージ名] 変更内容 の形式にする」といった具体的な指示です。形式が自由なぶん、何を書くかの判断がそのまま品質になります。その判断基準は後の章で扱います。

AGENTS.mdを読むツールと読み方の違い

AGENTS.md が「共通の置き場所」として機能するのは、複数のエージェントが同じファイル名を探しに来るからです。ただし、探す場所、複数ファイルの合成の仕方、サイズの上限は製品ごとに違います。2026 年 9 月時点の各社の公式ドキュメントから、主な 5 つの読み方を整理します。

出典はそれぞれ Codex の AGENTS.md ガイド、Claude Code の CLAUDE.md ドキュメント、GitHub Copilot のリポジトリ指示ドキュメント、Cursor の Rules ドキュメント、Gemini CLI の GEMINI.md ドキュメントです（いずれも 2026 年 9 月 20 日参照）。Gemini CLI のドキュメントには、無償枠と Google One の利用者向けに 2026 年 6 月 18 日で Antigravity CLI に置き換わった旨の注記があり、コンテキストファイルの仕組みは引き継がれています。

この表のうち Claude Code の行は、2026 年 9 月に書き換わったばかりです。長いあいだ CLAUDE.md しか読まなかった Claude Code に、2026 年 9 月 18 日の v2.1.277 で「CLAUDE.md の無いプロジェクトでは代わりに AGENTS.md を読む」挙動が入りました。既定の組み合わせは次のとおりです。

判定に数えるのは作業ディレクトリ以上の CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md の 3 つだけで、~/.claude/CLAUDE.md や .claude/rules/ は数に入らず AGENTS.md と一緒に読み込まれます。AGENTS.local.md、AGENTS.override.md、.agents/ 配下は読みません。自分用のメモとして CLAUDE.local.md を 1 つ置いた瞬間に AGENTS.md が読まれなくなるのもこの判定のためで、公式の回避策は /config の Project instructions を claude-md-and-agents-md にして両方読ませることです。

穴もあります。v2.1.277 より前のバージョン、Amazon Bedrock など機能フラグを取得しない環境、インストール直後の 1 セッション、フックを止めている場合は直接読み込みが働きません。直接読んだ AGENTS.md は /memory と /context の一覧に出ず、InstructionsLoaded フックも発火しないので、読まれたかは起動時の no CLAUDE.md found; AGENTS.md loaded: ... の行で確かめます。CLAUDE.md からインポートする従来の書き方が今も確実なのはこのためで、ドキュメントも既にそうしている場合は「そのままでよい。インポートを残しても二重には読まれない」と述べています。

@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.

Windows 以外の ln -s AGENTS.md CLAUDE.md も、残しても消しても内容は 1 回だけ読まれます。一方で CLAUDE.md に「AGENTS.md を参照すること」と文章で書いているだけの構成は勧められていません。それでは Claude がファイルを開くと判断したときにしか読まれないので、CLAUDE.md を消すか、その一文を @AGENTS.md のインポートに置き換えます。

逆方向の取り込みもあり、Claude Code v2.1.213 以降の /import コマンドは AGENTS.md などの指示ファイルを CLAUDE.md に一度だけコピーし、MCP サーバーやスキルの設定も引き継ぎます。

Codex には project_doc_max_bytes という明示的な上限があり、既定の 32 KiB を超えると「上限に達した時点でファイルの追加をやめる」動作になります。ルートの AGENTS.md が長いと、サブディレクトリの AGENTS.md が読まれないまま作業が始まることがあるので、モノレポでは階層ごとの合計を意識する必要があります。

CLAUDE.mdとは何が違うのか：AGENTS.mdとの使い分け

CLAUDE.md は Claude Code だけが読む指示ファイルで、役割は AGENTS.md とほぼ同じです。違いは「誰が読むか」と「周辺機能の厚さ」にあります。

Claude Code のドキュメントは CLAUDE.md を 4 つのスコープに分けています。

このほかに .claude/rules/ ディレクトリがあり、YAML frontmatter の paths でファイルパターンを指定した規則は、該当するファイルを Claude が読んだときだけコンテキストに入ります。@path/to/file 構文で他のファイルを取り込む機能もあり、再帰は 4 段まで、コードブロック内の @ は無視されます。HTML コメントはコンテキストに入る前に取り除かれるので、人間向けの保守メモを置いても消費トークンになりません。

一方で、CLAUDE.md の中身は「システムプロンプトの後にユーザーメッセージとして渡される」コンテキストであり、強制される設定ではないと明記されています。コミット前に必ず走らせたい処理は CLAUDE.md に書くのではなくフックに、ツールやパスの禁止は permissions.deny に置くのが公式の推奨です。ここは AGENTS.md も同じで、指示ファイルは「お願い」であって「制約」ではないという前提で設計する必要があります。

使い分けの結論は、直接読み込みへの対応後も「AGENTS.md を正本にする」で変わりません。変わったのは、その正本を Claude Code に渡す手数です。Claude Code 固有の指示が無ければ AGENTS.md を 1 枚置くだけで足り、プランモードの使い方のような固有の指示があるなら、CLAUDE.md に @AGENTS.md を書いてその下に足します。直接読み込みが使えない環境を含むチームでは、インポート方式のほうが環境差を受けません。Claude Code しか使わないチームでも、後からエージェントを追加したときにファイルを分裂させないために、正本を AGENTS.md に置く構成から始めて損はありません。

AGENTS.mdに何を書き、何を書かないか

形式に決まりがないので、内容の取捨選択が AGENTS.md の品質を決めます。各社のドキュメントの推奨は驚くほど一致しており、要約すると「エージェントがコードを読んでも分からないことだけを書く」です。

Claude Code のベストプラクティスは、含めるものと除くものを表にしています。

同じドキュメントには「1 行ごとに、これを消したら Claude が間違えるかを問い、そうでなければ切る」という基準と、「膨れ上がった CLAUDE.md は本当に守ってほしい指示を無視させる」という警告があります。Codex のガイドは、書くべきものとして「作業上の取り決めとリポジトリの規範」「専用セクションに置くコードレビューのルール」「ツールの好みとテストの要件」を挙げています。

もう 1 つの基準が、OpenAI が 2026 年 2 月に公開したハーネスエンジニアリングの記事にある「約 100 行の AGENTS.md を目次にして、知識の本体は docs/ ディレクトリに置く」構成です。1 つの大きな AGENTS.md にすべてを書く方法は、コンテキストを圧迫して重要な制約が落ちる、すべてが重要だと何も重要でなくなる、マニュアルはすぐ腐る、機械的に検証できない、という 4 つの理由で失敗したと報告されています。AGENTS.md には「何がどこにあるか」だけを書き、設計方針やドメイン知識は別ファイルにしてリンターと CI で鮮度を検証する、という分業です。

書かないほうがよいものは、上の表に加えてもう 1 種類あります。リポジトリが公開される可能性があるなら、内部情報を書かないことです。gaipack でもデザインシステム用の AGENTS.md を https://www.gaipack.ai/AGENTS.md としてそのまま Web に公開しているため、Issue 番号、顧客名、未公開の料金をファイルに書かないルールにしています。エージェント向けのファイルは人間向けのドキュメントより監視の目が緩くなりがちで、そこに書いた情報はコードと同じ経路で外に出ます。

AGENTS.mdの階層と読み込み順序：モノレポでの配置

複数の AGENTS.md がある場合の解決順序は、公式サイトの「最も近いファイルが勝つ」という原則を各製品が実装で解釈しています。Codex と Claude Code の実装を並べると、次のような流れになります。

Codex は Git ルートから作業ディレクトリまでを上から順に連結し、「作業ディレクトリに近いファイルは結合後のプロンプトで後ろに現れるため、先のものを上書きする」と説明しています。Claude Code も作業ディレクトリと上位階層のファイルを連結し、ファイルシステムのルート側から作業ディレクトリ側へ並べるので、起動した場所に近い指示が最後に読まれます。違いは、Claude Code がサブディレクトリの CLAUDE.md を起動時には読まず、そのディレクトリのファイルを読んだ時点で追加する点です。AGENTS.md を直接読む構成でも同じで、サブディレクトリの AGENTS.md は、Claude がそのディレクトリのファイルを開いたときに、かつそのディレクトリに CLAUDE.md 系のファイルが無いときに追加されます。

モノレポで実務上の差が出るのは次の 3 点です。

• ルートには全パッケージ共通のことだけを書く。 パッケージ固有のテストコマンドやフレームワークの流儀は各パッケージの AGENTS.md に置く
• 他チームの指示を除外する手段を知っておく。 Claude Code には claudeMdExcludes 設定があり、上位階層の関係ないファイルをパターンで読み飛ばせる
• 合計サイズを見る。 Codex の 32 KiB は連結後の合計に対する上限なので、ルートが肥大化すると下位のファイルが読まれない

AGENTS.mdが長くなると守られなくなる理由

指示ファイルで最も多い失敗は「書いたのに守られない」で、その原因の大半は書きすぎです。Claude Code のドキュメントは「200 行以内を目標にする。長いファイルはコンテキストを消費し、遵守率を下げる」と数字で示し、ベストプラクティスでは「ルールがあるのに同じことを繰り返すなら、ファイルが長すぎてそのルールが埋もれている可能性が高い」「多くの行を強調すると、どれも目立たなくなる」と述べています。

理由は仕組みにあります。指示ファイルはセッション開始時にコンテキストウィンドウへそのまま入るので、長いほど会話やコードを読む余地を圧迫します。そして指示は強制ではなく文脈なので、モデルは膨大な文脈の中から「今の作業に関係する行」を拾う必要があり、量が増えるほど拾い損ねが増えます。OpenAI の記事が挙げた「すべてが重要だと何も重要でなくなる」という失敗は、この構造をそのまま言い表しています。

対策は 4 つあり、それぞれ置き場所が違います。

Claude Code の /doctor コマンドは、チェックインされた CLAUDE.md からコードベースを読めば分かる内容（ディレクトリ構成、依存一覧、アーキテクチャ概要）を削る提案を出します。書いた指示が実際に読まれているかは、Claude Code なら /context の Memory files の一覧、Gemini CLI なら /memory show で確認できます。「守られない」と感じたときは、まず読まれているかを確かめ、次に長さを疑う順番が近道です。スキルの仕組みはAgent Skills の記事で、コンテキスト全体の設計はコンテキストエンジニアリングの記事で扱っています。

短く保ったうえで、もう 1 つ必要なものがあります。指示が守られたかどうかを外から検証する仕組みです。AI に自己申告させるだけでは足りず、申告を検証する主体を別に置いて初めて、書いた指示が結果に結びつきます。この検証側の設計はAI エージェントにルールを破らせない仕組みの記事に書いています。

AGENTS.mdのセキュリティ：指示ファイルは信頼境界の内側にある

AGENTS.md はエージェントが無条件に従う前提のファイルです。つまり、リポジトリをクローンした時点で、そこに書かれた指示がエージェントの行動に入り込みます。この性質は便利さと表裏一体で、他人が書いた AGENTS.md や、プルリクエストで書き換えられた AGENTS.md を読む場面では、コードと同じ警戒が必要です。

この経路は研究でも確認されています。2026 年 2 月に公開された論文 Skill-Inject は、スキルファイル（AGENTS.md と同じく、エージェントが指示として読み込む第三者提供のファイル）に仕込まれた指示に対する耐性を 202 件の攻撃とタスクの組み合わせで測り、最前線のモデルでも最大 80% の攻撃成功率だったと報告しています。著者らは、この問題はモデルの大規模化や単純な入力フィルタでは解決せず、文脈を踏まえた認可の仕組みが要ると結論づけています。OWASP が 2025 年 12 月に公開した Top 10 for Agentic Applications でも、エージェントが後で自分の知識として扱う内容に偽情報を植え付ける「メモリとコンテキストの汚染」（ASI06）と、エージェントの部品や設定の来歴に関わる「エージェント型サプライチェーンの脆弱性」（ASI04）が独立した項目になっています。

各製品もこの前提で防御を入れています。Claude Code は初めて開くコードベースと新しい MCP サーバーに対して信頼の確認を求め、プロジェクトの CLAUDE.md が作業ディレクトリの外のファイルを @ で取り込もうとすると、初回に承認ダイアログを出します。ドキュメントには「共有プロジェクトに他人がコミットしたファイルからあなたを守るため」と理由が書かれています。ただし AGENTS.md を直接読む構成では、作業ディレクトリの外を @ で取り込む記述に対してこのダイアログが出ません。そのプロジェクトで外部インポートを承認済みなら確認なしで読み込まれ、未承認なら読み込まれない、という二択になります。

運用側でできることは 4 つあります。

• AGENTS.md の差分をコードと同じ基準でレビューする。 CODEOWNERS に指示ファイルを含め、レビューなしのマージを防ぐ
• 他人のリポジトリは信頼しない環境で開く。 出所が不確かなリポジトリを初めて開くときは、サンドボックスやコンテナで動かし、ネットワークとファイルの権限を絞る
• 「必ず守らせたいこと」を指示ファイルに頼らない。 禁止コマンドや書き込み禁止パスは設定側で強制する。指示ファイルは書き換えられても、設定は書き換えられにくい
• エージェントが読むすべての入力を同じ目で見る。 指示ファイルは入口の 1 つにすぎず、Issue の本文、PR コメント、取得した Web ページも同じ経路で指示になりうる

権限の絞り方と人間の確認を挟む設計はコーディングエージェントの権限設計の記事で扱っています。

AGENTS.mdとは何かに関するよくある質問

AGENTS.md を導入するときに実際に受ける質問をまとめました。

AGENTS.mdは必須ですか？

必須ではありません。公式サイトの FAQ は「AGENTS.md は単なる標準的な Markdown」と答えており、無くてもエージェントは動きます。ただし、ビルドやテストのコマンドをエージェントが毎回推測して間違えるなら、それを 1 行書くだけで繰り返しの修正が減ります。「同じ指摘を 2 回したら書く」が始めどきの目安です。

Claude Code は AGENTS.md を読みますか？

読みます。2026 年 9 月 18 日の v2.1.277 から、作業ディレクトリと上位階層に CLAUDE.md も CLAUDE.local.md も無いプロジェクトでは、代わりに AGENTS.md を読みます。既定で有効で、設定もインポートも要りません。CLAUDE.md がある場合は従来どおり CLAUDE.md だけを読み、両方を読ませたいときは /config の Project instructions を claude-md-and-agents-md に変えます。

AGENTS.mdとCLAUDE.mdは両方置くべきですか？

両方置く必要はなくなりました。Claude Code 固有の指示が無いなら AGENTS.md を 1 枚置くのがいちばん短い構成です。CLAUDE.md を併せて置くのは、固有の指示を足したいとき、直接読み込みが使えない環境がチームに混ざるとき、InstructionsLoaded フックを使っているときで、その場合も中身は @AGENTS.md の 1 行と固有の指示だけにします。

AGENTS.mdは何行くらいが適切ですか？

Claude Code は 200 行以内、Cursor は 500 行以内、GitHub Copilot は 2 ページ以内、Codex は連結後 32 KiB を上限にしています。OpenAI の実験では約 100 行の目次に抑え、本体を docs/ に分けています。数字より「消したら間違えるか」を 1 行ずつ問うほうが判断を誤りにくく、それでも長いなら本文ではなく置き場所を変えます。

AGENTS.override.mdとは何ですか？

OpenAI Codex が AGENTS.md より先に探すファイル名です。Codex はグローバルでは ~/.codex/AGENTS.override.md を、プロジェクトでは各階層で AGENTS.override.md → AGENTS.md → 設定した代替名の順に探し、最初に見つかった空でないファイルを使います。Codex 以外のエージェントは読まないので、Codex 固有の上書きを置きたいときだけ使います。

.cursorrulesやcopilot-instructions.mdから移行するには？

Claude Code の /init は .cursor/rules/、.cursorrules、.github/copilot-instructions.md を読んで CLAUDE.md の生成に反映し、新しい対話式の /init は AGENTS.md、.windsurf/rules/、.clinerules も読みます。逆に他のツールへ寄せるなら、AGENTS.md に内容を集約し、各ツールの指示ファイルを AGENTS.md への参照にするのが移行後の保守を最も軽くします。

まとめ

• AGENTS.md は AI コーディングエージェント向けの指示ファイルで、必須項目のない標準的な Markdown です。OpenAI が始め、2025 年 12 月に Linux Foundation 傘下の Agentic AI Foundation へ寄贈されました
• Codex、GitHub Copilot、Cursor、Gemini CLI に加え、Claude Code も 2026 年 9 月 18 日の v2.1.277 から AGENTS.md を読みます。ただし直接読むのは CLAUDE.md が無いときだけで、使えない環境も残るため、@AGENTS.md のインポートは引き続き確実な手段です
• 書くのは「コードを読んでも分からないこと」だけで、Claude Code は 200 行以内、Codex は連結後 32 KiB を上限にしています。長くなったらスキル、パス指定の規則、フック、docs/ に移します
• モノレポでは階層ごとに置き、ルートには全パッケージ共通のことだけを書きます。近いファイルが優先されますが、Codex は連結後の合計に上限があるので、ルートが肥大化すると下位のファイルが読まれません
• 指示ファイルは信頼境界の内側にあるので、差分レビュー、隔離環境、設定側での強制、入力全体への警戒をセットで運用します

gaipack では、AGENTS.md と SKILL.md を骨格にした AI 駆動開発の環境を実案件で運用しています。この環境を貴社のリポジトリに構築するAIDD 環境構築や、貴社チームに伴走して定着させる AIDD インハウスをご用意しています。AI 駆動開発の全体像は AI駆動開発の記事にまとめていますので、あわせてご覧ください。