AGENTS.md標準に関する分析レポート：ツール間の互換性と実装のニュアンスに関する詳細な考察

Part 1: AGENTS.mdの起源と仕様

AIを活用した開発が主流となる中で、AIコーディングエージェントにプロジェクトの文脈を正確に伝えるための標準化された手法の必要性が急速に高まりました。AGENTS.mdは、この課題に対する業界全体の回答として登場しました。このセクションでは、AGENTS.mdが必要とされた背景、その基本的な設計思想とアーキテクチャ、そして標準化の過程で生じた命名に関する分岐とその収束について詳述します。

1.1 設定の断片化という問題

AGENTS.mdの標準化が推進される以前、複数のAIコーディングエージェントを併用する開発者は、設定ファイルの断片化という深刻な問題に直面していました。各ツールはそれぞれ独自の命令ファイル形式を採用しており、その結果、リポジトリ内は無秩序な状態に陥っていました 1。

具体的には、Cursorは.cursor/rules、Clineは.clinerules、GitHub Copilotは.github/copilot-instructions.md、Claudeはclaude.md、Geminiはgemini.mdといった、それぞれ異なる名前と場所を持つ設定ファイルを要求しました 1。驚くべきことに、同じ系統から派生したツールでさえ、異なるディレクトリ名を使用するケースがありました 1。この状況は、開発者にとって大きな負担となっていました。プロジェクトのビルド方法やコーディング規約といった本質的に同じ内容を、ツールごとに異なるファイルに重複して記述し、維持管理する必要があったのです。コードベースが変更されるたびに、5つもの異なるファイルを更新する手間は、「すべてを更新し続けるのが苦痛」と表現されるほどの非効率性を生み出しました 2。

この混乱を乗り切るため、開発者はシンボリックリンクを作成して一つのマスターファイルを複数の場所にリンクさせたり、intellectronica/rulerのような専用ツールを使って一つの命令ファイルを各ツール形式に配布したりといった、場当たり的な回避策を講じざるを得ませんでした 1。しかし、これらの手法は根本的な解決にはならず、プロジェクトのディレクトリ構造をさらに複雑化させる一因となっていました。この状況は、業界内で「ファイル名の混乱（mess of filenames）」と広く認識されており 3、相互運用可能な標準の不在が開発者の生産性を著しく阻害していることは明らかでした。

AGENTS.mdは、このような背景から生まれました。これは単なる新しいファイル形式の提案ではなく、開発者が直面していた現実的かつ具体的な問題点を解決するための、業界横断的な取り組みでした。Google、OpenAI、Factory、Sourcegraph、Cursorといった主要なプレーヤーが協力し、この標準化を推進したという事実は、問題の深刻さと解決への強い意志を物語っています 1。

1.2 AGENTS.mdの基本原則とアーキテクチャ

AGENTS.mdの設計思想は、意図的なシンプルさにあります。その核心は、リポジトリのルートディレクトリに配置される、ごく普通のMarkdownファイルであるという点です 4。これは、人間開発者向けにプロジェクトの概要や貢献方法を記すREADME.mdを補完する、「エージェントのためのREADME」として機能します 6。README.mdが人間にとって読みやすいように最適化されているのに対し、AGENTS.mdはAIエージェントがプログラム的に解釈しやすい、機械可読な指示を提供することに特化しています 8。

この標準の最も重要な特徴の一つは、複雑なスキーマや専用のツールを一切要求しないことです 6。AIエージェントは、Markdownの標準的な構造、すなわち見出し（#、##など）や箇条書き（-）、コードブロック（```）を意味的な手がかりとしてテキストを解析します 5。これにより、開発者は特別な学習コストなしに、自然な形でエージェントへの指示を記述できます。ファイルに含めるべき内容として推奨されているのは、セットアップ、ビルド、テストコマンド、コーディングスタイルガイドライン、アーキテクチャパターン、セキュリティに関する考慮事項など、エージェントが自律的に作業を進める上で不可欠な情報です 4。

このスキーマレスなアプローチは、導入の障壁を劇的に下げ、柔軟性を確保するための意図的な設計判断です 8。しかし、この設計は諸刃の剣でもあります。厳格な仕様が存在しないため、各ツールベンダーがパーサーの実装、命令の解釈、エッジケースの処理を独自に行うことになり、結果としてツール間の微妙な動作の違い、すなわち本レポートで詳述する互換性の問題を生み出す主要な原因となっています。

さらに、AGENTS.mdは大規模プロジェクトの複雑性に対応するため、階層構造をサポートしています。モノリポ（monorepo）のような大規模なリポジトリでは、ルートディレクトリに単一のAGENTS.mdファイルを置くだけでなく、各サブプロジェクトやパッケージ内にネストされたAGENTS.mdファイルを配置することが可能です 4。AIエージェントは、作業対象のコードに最も近いディレクトリツリー上のAGENTS.mdファイルを読み込むように設計されています。この際、より内側（ローカル）のファイルが外側（ルート）のファイルを上書きする（オーバーライドする）ルールが適用されます 6。この仕組みにより、例えばレガシーなパッケージには古いフレームワーク用のルールを適用しつつ、新しいパッケージには最新の規約を適用するなど、コンテキストに応じた詳細な指示を与えることができます。実際に、主要なOpenAIのリポジトリでは、この機能を活用して88個ものAGENTS.mdファイルが管理されています 8。この階層的な読み込みメカニズムは、AGENTS.mdが単純な小規模プロジェクトだけでなく、エンタープライズ規模の複雑なソフトウェア開発においても実用的な標準であることを保証する、極めて重要な機能です。

1.3 標準の分岐: AGENTS.md vs AGENT.md

AGENTS.mdの標準化が進む初期段階において、エコシステムはAGENTS.md（複数形）とAGENT.md（単数形）という、二つのわずかに異なる命名規則の間で分裂するという、小規模ながらも注目すべき事態に直面しました。これらは機能的には同一でしたが、その背景には異なる思想と戦略が存在しました。

AGENT.md（単数形）は、主にSourcegraph社によって提唱されました。彼らはagent.mdというドメイン名を所有しており、この標準が特定のベンダーに依存しない中立的なものであるべきだと主張しました 3。彼らの視点では、単一のドメインに紐づけられた中立的なサイトが存在することが、標準の信頼性を担保する上で重要であるとされていました 3。

一方で、AGENTS.md（複数形）は、OpenAI、Google、Cursorなどを含む、より広範な企業連合によって立ち上げられました 1。この陣営はagents.mdという公式サイトを拠点とし、より多くの主要ツールがこの複数形の命名規則を採用したことで、事実上の標準としての地位を確立していきました 8。

最終的に、エコシステムはこの「標準戦争」を経て、AGENTS.md（複数形）へと大きく収束しました 11。現在では、かつてAGENT.mdを推進していた陣営の移行ガイドでさえ、既存のファイルをAGENTS.mdにリネームし、後方互換性を確保するためにシンボリックリンクを作成することを推奨しています 6。具体的なコマンドとしては、mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.mdのように、古い名前から新しい標準ファイルへのリンクを張る手法がベストプラクティスとして共有されています 2。

この命名を巡る論争は些細なことに見えるかもしれませんが、黎明期のAIエージェントエコシステムにおける主導権争いや思想の違いを象徴する出来事でした。技術的な意思決定者にとっての現実的な結論は明確です。現在、そして将来にわたって標準化を進める上では、クリティカルマスを達成したAGENTS.md（複数形）を組織の標準として採用すべきです。ただし、移行期間中や、まだ新しい標準に完全に対応していない古いツールをサポートする必要がある場合には、シンボリックリンクを活用して後方互換性を確保するという、柔軟かつ実用的なアプローチが求められます 3。

Part 2: ツール実装と互換性の比較分析

AGENTS.mdが標準として広く受け入れられつつある一方で、その「サポート」の内実はツールごとに大きく異なります。単にファイルが存在を認識するだけでなく、どのように解釈し、既存の独自設定とどう共存させ、どの命令を優先するかという実装の細部が、実際の互換性を決定づけまます。このセクションでは、主要なAIコーディングエージェントであるGitHub Copilot、Devin、Cursor、Google Gemini CLIを対象に、AGENTS.mdのサポートレベル、仕様の解釈、そして命令の優先順位付けに関する詳細な比較分析を行います。これにより、各ツールの実装のニュアンスと、それがもたらす互換性の課題を明らかにします。

2.1 GitHub Copilot

GitHub Copilotは、その自律的な「コーディングエージェント」機能において、2025年8月28日の更新でAGENTS.mdを公式にサポートしました 12。このサポートは、リポジトリのルートディレクトリだけでなく、ネストされたサブディレクトリ内のAGENTS.mdファイルにも及び、モノリポ構造に対応しています 12。

しかし、CopilotにおけるAGENTS.mdのサポートは、既存の独自設定を置き換えるものではなく、あくまで「追加的」なものであるという点が極めて重要です。Copilotは以前から、.github/copilot-instructions.mdというリポジトリ全体に適用されるファイルや、.github/instructions/**.instructions.mdというパス固有の命令ファイルといった、独自の強力な設定体系を持っていました 12。AGENTS.mdの導入後も、これらのファイルは引き続きサポートされています 12。

Copilotの命令解釈には、明確に文書化された階層構造が存在します。特にCopilot Chatにおいては、個人設定の命令 > リポジトリ設定の命令 > 組織設定の命令という優先順位が適用されます 14。競合が発生した場合は、より優先度の高い設定が採用されますが、基本的には関連するすべての命令が結合されてモデルに渡される仕組みです 14。

ここでの重大な問題点は、公式のドキュメントや変更履歴において、AGENTS.mdがこの確立された階層構造のどこに位置づけられるかが一切明記されていないことです。AGENTS.mdは「リポジトリ設定の命令」の一種であることは間違いありませんが、同じリポジトリレベルの.github/copilot-instructions.mdファイルと同時に存在した場合、どちらが優先されるのか、あるいは両者の内容がマージされるのか、その挙動は定義されていません。GitHub上のコミュニティの議論では、開発者たちが両方のファイルの内容が結合されるべきだと提案していますが、これはあくまで希望的観測であり、公式な仕様ではありません 15。

この優先順位の曖昧さは、AGENTS.mdによる標準化を目指すチームにとって、無視できない大きなリスクとなります。チームが多大な労力をかけてAGENTS.mdにプロジェクトの規約を整備したとしても、リポジトリ内に残存している古い.github/copilot-instructions.mdファイルによって、その指示が意図せず上書きされたり、無視されたりする可能性があります。これにより、エージェントの挙動が予測不能になり、標準化の努力が無に帰す恐れがあります。したがって、GitHub Copilotは、現時点ではAGENTS.mdを最も複雑で、信頼性の高い設定が難しい環境の一つと言わざるを得ません。

2.2 Devin

Cognition AIが開発したDevinは、AGENTS.mdをネイティブでサポートしており、リポジトリにエージェントをオンボーディングするための主要な手段として位置づけています 7。ドキュメントでは、プロジェクトのルートディレクトリやその他の場所にAGENTS.mdファイルを配置するだけで、Devinがコーディングを開始する前にその内容を読み込むと、シンプルに説明されています 7。

しかし、Devinの実装におけるニュアンスは、その背後にあるより広範な「知識（Knowledge）」システムとの相互作用にあります。この「知識」システムは、セッションを越えて維持される永続的なコンテキストストアであり、Devinが作業を行う上での組織的な知見として機能します 16。Devinは、リポジトリ内のREADMEファイルやディレクトリ構造を分析し、一部の「知識」を自動的に生成する能力を持っています 16。

ここで最も注意すべき点は、Devinが.rules、.mdc、.cursorrules、.windsurfといった他のツールに由来する特殊な設定ファイルを自動的にスキャンし、その内容を「知識」ベースに能動的に取り込む仕様になっていることです 16。

この仕様が引き起こす重大な曖昧さは、ドキュメントに「Devinは.mdのような、より一般的なファイルタイプを自動的に取り込むことはない」と明記されている点に起因します 16。これは、AGENTS.mdのサポートを謳う公式な立場と明確に矛盾しています。AGENTS.mdがこの「.mdファイルを無視する」というルールの例外として特別扱いされるのか、それとも自動取り込みの対象となる他の特殊ファイルとは異なる、より優先度の低い扱いを受けるのか、その挙動は全く文書化されていません。したがって、もしプロジェクト内にAGENTS.mdと、例えば.cursorrulesファイルが共存していた場合、どちらの指示が優先されるのか、あるいはどのようにマージされるのかは完全に不明です 16。

この実装は、DevinのAGENTS.mdサポートが見かけほど単純ではないことを示唆しています。強力な自動知識取り込みシステムとの相互作用がブラックボックス化しているため、リポジトリの状態に極めて脆弱な挙動を示す可能性があります。例えば、過去にCursorを使用していたプロジェクトをDevinで扱う場合、リポジトリ内に残存している.cursorrulesファイルが、開発者の意図に反してAGENTS.mdの指示を静かに上書きしてしまうかもしれません。このような予期せぬ挙動は、安定した運用を著しく困難にします。したがって、DevinでAGENTS.mdを確実に機能させるためには、他のツール固有の設定ファイルが存在しない、クリーンなリポジトリ環境を維持することが不可欠となります。

2.3 Cursor

Cursorは、AGENTS.mdをサポートしていますが、その位置づけは同社のより強力で高機能な独自システムである「プロジェクトルール（Project Rules）」の「シンプルな代替手段」というものです 17。この独自システムは、.cursor/rulesディレクトリ内に.mdc（Markdown Component）という特殊な形式のファイルでルールを管理します 17。

Cursorの.mdc形式は、単なるMarkdownファイルではありません。globsを用いて特定のファイルパターンにのみルールを適用したり、Always（常に適用）、Auto Attached（関連ファイルが参照された際に自動適用）、Manual（@で明示的に呼び出された場合のみ適用）といった適用条件をメタデータとして指定できる、高度に構造化されたシステムです 17。AGENTS.mdは、これらの高度な機能を一切サポートしておらず、あくまでプレーンなMarkdownファイルとして扱われます 17。AGENTS.mdは、このような複雑な設定のオーバーヘッドなしに、直接的な指示を書きたい「単純なユースケース」向けとされています 17。

Cursorのルール適用には、明確な優先順位が定められています。それは、チームルール → プロジェクトルール（.cursor/rules）→ ユーザー個人ルール の順です 17。

ここでの重大な曖昧さは、AGENTS.mdと.cursor/rulesが同じプロジェクト内に共存した場合の優先順位が、公式ドキュメントで明記されていない点です 17。AGENTS.mdが「シンプルな代替手段」と位置づけられていることを考慮すると、両者はプロジェクトレベルで排他的に使用されることが意図されているか、あるいは共存した場合には機能が豊富な.cursor/rulesが優先される可能性が高いと推測されます。しかし、これはあくまで推測であり、保証された挙動ではありません。

この状況は、Cursorユーザーにとって、単に標準規格を採用するか否かという単純な問題ではないことを示しています。AGENTS.mdが提供するツール間の移植性と、Cursor独自の.cursor/rulesシステムが提供する高度な機能との間で、明確なトレードオフの判断を迫られるのです。特に、ファイルパスに応じたルールの動的な適用など、Cursorの高度なスコープ指定機能に依存しているチームにとっては、AGENTS.mdでは機能が不十分であり、移行は現実的ではありません。これは、AGENTS.mdの標準化における中心的な課題を浮き彫りにしています。すなわち、ツールベンダーは基本的なユースケースにおいては標準をサポートする意向を示しつつも、ユーザーを自社エコシステムに留めるための強力な独自機能を維持しようとする、という構造的な緊張関係です。

2.4 Google Gemini CLI

GoogleのGemini CLI（Visual Studio Codeにおけるエージェントモードのバックエンド）は、他のツールとは一線を画す、非常に透明性の高いアプローチを採用しています。デフォルトでは、Gemini CLIはコンテキストファイルとしてGEMINI.mdという名前のファイルを使用します 19。

Gemini CLIのコンテキスト読み込みメカニズムは、詳細に文書化されており、予測可能性が非常に高いです。それは以下の階層構造に従って、複数の場所からコンテキストを結合します：

1. コンポーネントレベル: 作業ディレクトリ内のサブディレクトリにあるGEMINI.md
2. プロジェクトレベル: 作業ディレクトリ、または.gitフォルダのあるプロジェクトルートまでの親ディレクトリにあるGEMINI.md
3. グローバルレベル: ユーザーのホームディレクトリ配下にある~/.gemini/GEMINI.md

これらのファイルが存在する場合、その内容は結合され、より具体的（内側）なファイルの指示が、より一般的（外側）なファイルの指示を補足、または上書きします 19。

Gemini CLIの最大の特徴は、AIエージェントが参照するコンテキストファイルの名前をユーザーが明示的に設定変更できる点にあります。ユーザーは、ホームディレクトリにある設定ファイル~/.gemini/settings.json内のcontextFileNameプロパティを編集することで、デフォルトのGEMINI.mdから”AGENTS.md”に変更したり、さらには複数のファイル名を配列で指定したりすることが可能です 22。

この実装において、曖昧さは一切存在しません。挙動は完全にユーザーの手に委ねられています。裏を返せば、Gemini CLIはAGENTS.mdというファイル名を自動的に認識したり、フォールバックとして読み込んだりすることは一切ありません。ユーザーがsettings.jsonで明示的に設定しない限り、リポジトリ内にAGENTS.mdファイルが存在していても、それは完全に無視されます 22。

Geminiのこのアプローチは、最も決定論的で予測しやすい一方で、互換性を確保するための負担を完全にエンドユーザーに課しています。チームがリポジトリにAGENTS.mdを配置しただけでは、Gemini CLIを使用している開発者には何の効果もありません。チームメンバー一人ひとりが、各自のローカル環境でsettings.jsonファイルを正しく設定する必要があります。これは、設定不要でシームレスな相互運用性を目指すAGENTS.mdの理念とは相容れない側面があり、デフォルトの標準としてのAGENTS.mdに対するコミットメントが他のツールと比較して弱いことを示しています。

---

比較分析の要約

各ツールのAGENTS.mdサポート状況を分析した結果、「サポートしている」という一言では到底表現できない、多様な実装レベルとニュアンスが存在することが明らかになりました。技術リーダーがツール選定や標準化方針を決定する上で、これらの差異を正確に理解することは不可欠です。以下の表は、本分析で得られた主要な知見をまとめたものです。

ツール名	デフォルト命令ファイル	AGENTS.mdサポートレベル	命令読み込み階層と優先順位	主要な実装のニュアンスと逸脱
GitHub Copilot	.github/copilot-instructions.md, .github/instructions/**.instructions.md	追加的・曖昧	文書化された階層: 個人 > リポジトリ > 組織 14。 未定義: リポジトリレベルでのAGENTS.mdと独自ファイルの優先順位は不明。マージされるか、一方が他方を上書きするかの挙動が定義されていない。	AGENTS.mdは既存の強力な独自設定システムに追加される形でサポートされる。レガシーファイルとの共存時の挙動がブラックボックスであり、予測不能な結果を招くリスクが最も高い。
Devin	なし (ただし、他ツールの設定ファイルを自動で「知識」として取り込む)	ネイティブ・一次的	不明確: AGENTS.mdと、自動的に取り込まれる他の設定ファイル（例: .cursorrules, .mdc）との間の優先順位は文書化されていない 16。	AGENTS.mdを主要な設定手段としながらも、他のツール固有の設定ファイルを警告なく自動で読み込む「知識」システムを持つ 16。リポジトリ内にレガシーファイルが残存していると、意図しない上書きが発生する可能性がある。
Cursor	.cursor/rules/*.mdc	代替的・下位互換	文書化された階層: チーム > プロジェクト (.cursor/rules) > ユーザー 17。 未定義: AGENTS.mdと.cursor/rulesが共存した場合の優先順位は不明 17。	AGENTS.mdは、より高機能な独自システム.cursor/rulesの「シンプルな代替手段」と位置づけられている 17。高度なスコープ指定など、独自システムの強力な機能は利用できない。標準化と機能性のトレードオフをユーザーに強いる。
Google Gemini CLI	GEMINI.md	オプトイン・設定必須	明確な階層: コンポーネント (./sub/GEMINI.md) > プロジェクト (./GEMINI.md) > グローバル (~/.gemini/GEMINI.md) 19。より具体的なファイルが優先される。	デフォルトではAGENTS.mdを一切認識しない。ユーザーが~/.gemini/settings.jsonでcontextFileNameを”AGENTS.md”に明示的に設定した場合にのみ読み込む 22。透明性は最も高いが、互換性の実現はユーザーの個別設定に依存する。

この比較から導き出される最も重要な結論は、「AGENTS.mdをサポートしているか」という問いは、もはや意味をなさないということです。真に問われるべきは、「どのようにサポートしているか」です。GitHub Copilotの「追加的・曖昧」なサポートや、Gemini CLIの「オプトイン」モデルは、チーム全体でのシームレスな標準化に対して大きな障壁となります。また、DevinとCursorのケースは、AGENTS.mdと独自設定ファイルとの共存が、標準化の取り組みを静かに、しかし確実に蝕む最大の脅威であることを示しています。成功裏にAGENTS.mdを導入するためには、単に新しいファイルを作成するだけでなく、リポジトリからこれらのレガシーファイルを意図的に排除し、クリーンな状態を作り出すという、より積極的なガバナンスが不可欠です。

Part 3: 命令の優先順位と競合解決という重大な課題

AGENTS.mdの導入が複雑化する最大の要因は、異なるソースからの命令がどのように組み合わされ、競合した場合にどれが優先されるかという問題です。Part 2で明らかになったツールごとの実装のばらつきを統合し、このセクションでは、命令の競合解決を支配する普遍的な原則を抽出し、開発者がエージェントの挙動を予測するための統一的なメンタルモデルを提示します。

3.1 ルール階層の統一モデル

多様なツールの実装を横断的に分析すると、命令の優先順位を決定する上で共通する、いくつかの基本原則が見えてきます。これらの原則を理解することは、特定のツールのドキュメントが不完全な場合でも、エージェントの挙動を論理的に推測する上で極めて有効です。

1. 近接性優先の原則（”最も近いファイルが勝つ”）
   これは、モノリポのような階層的なファイル構造において、最も広く採用されている原則です。あるサブディレクトリ内でタスクを実行する場合、そのディレクトリ内に存在するAGENTS.mdファイルの指示が、リポジトリのルートディレクトリにあるAGENTS.mdの指示よりも優先されます 6。この原則により、各コンポーネントやパッケージは、プロジェクト全体の汎用的なルールを継承しつつ、自身の特定の要件に合わせて指示を特化させることが可能になります。これは、大規模で複雑なコードベースにおいて、コンテキストに応じた適切な指示をエージェントに与えるための根幹をなすメカニズムです。
2. 具体性優先の原則（ユーザー > プロジェクト > グローバル）
   多くのツールは、ユーザー個人の設定、プロジェクト全体の設定、そしてより広範な（例えばチームや組織全体の）グローバルな設定といった、複数のスコープでルールを定義する機能を提供します。これらのスコープ間で指示が競合した場合、一般的には最も具体的で範囲の狭いスコープが、より広範なスコープを上書きします。例えば、Cursorでは、プロジェクトルール（.cursor/rules）よりもユーザー個人のルールが優先されることがあります 17。この原則は、開発者がプロジェクト全体の規約に従いつつも、自身の作業スタイルや特定のタスクに合わせてエージェントの挙動を微調整することを可能にします。
3. 明示的プロンプトの絶対的優位性
   これは、すべてのルール階層における最終的な「切り札」です。開発者がチャットのプロンプトを通じてエージェントに直接与えた指示は、AGENTS.mdやその他の設定ファイルに記述された、いかなる既存の指示よりも常に優先されます 8。例えば、AGENTS.mdに「テストはJestを使用すること」と書かれていたとしても、プロンプトで「この機能のテストをVitestで書いてください」と指示すれば、エージェントはその場限りの指示に従います。これは、タスクごとの微調整や、確立されたルールから意図的に逸脱する必要がある場合の、不可欠なエスケープハッチとして機能します。

これらの3つの原則（近接性、具体性、明示性）を組み合わせることで、開発者は複雑な設定環境下でも、AIエージェントがどの指示に従う可能性が高いかを予測するための、強力なフレームワークを手にすることができます。

3.2 ツール横断の優先順位マトリックス：暗黙のルール

統一モデルが一般的な指針を提供する一方で、現実の互換性の問題は、AGENTS.mdと各ツール固有のファイルがどのように相互作用するかに集約されます。Part 2の分析結果を基に、各ツールの優先順位チェーン（文書化されているもの、推測されるもの、そして完全に不明なもの）を以下にまとめます。これは、クロスツール互換性における「暗黙のルール」を可視化する試みです。

• GitHub Copilot:
  • 優先順位チェーン: 個人設定 > リポジトリ設定 (?) > 組織設定 14
  • 分析: 最大の問題は「リポジトリ設定」の内部にあります。AGENTS.mdと.github/copilot-instructions.mdが共存した場合、どちらが優先されるのか、あるいは内容がマージされるのかは公式に定義されていません。この不透明性が、Copilot環境におけるAGENTS.mdの信頼性を著しく損なっています。
• Devin:
  • 優先順位チェーン: 不明
  • 分析: Devinの挙動における最大のブラックボックスは、AGENTS.mdの指示と、.cursorrulesなどのファイルから自動的に取り込まれた「知識」との間の優先順位です 16。この関係性が文書化されていないため、開発者はどの指示が最終的に有効になるかを予測することができません。これは、Devinの実装における最も深刻な欠陥と言えます。
• Cursor:
  • 優先順位チェーン: チームルール > プロジェクトルール (.cursor/rules) > ユーザー個人ルール 17
  • 分析: この明確な階層にAGENTS.mdがどう組み込まれるかは曖昧です 17。しかし、AGENTS.mdが「シンプルな代替手段」と位置づけられ、.cursor/rulesがより豊富な機能を持つことから、共存した場合は.cursor/rulesが優先されると考えるのが合理的です。ユーザーは、標準規格の移植性と独自機能のパワーとの間で選択を迫られます。
• Google Gemini CLI:
  • 優先順位チェーン: コンポーネント > プロジェクト > グローバル（指定されたコンテキストファイル内での階層） 19
  • 分析: Gemini CLIは、settings.jsonで指定された単一の（または複数の）コンテキストファイル名のみを参照するため、AGENTS.mdと他のプロジェクトレベルファイルとの競合という問題が構造的に発生しません。これにより、挙動は完全に決定論的になりますが、その代償として、AGENTS.mdをデフォルトで認識しないという互換性の低さにつながっています。

このマトリックスは、AGENTS.mdを巡る「互換性」という言葉の曖昧さを、各ツールにおける具体的なリスクと予測可能性のレベルにまで分解して示しています。技術リーダーは、この分析を通じて、単に「サポートしている」というマーケティング上の言説に惑わされることなく、自社の開発環境においてどのツールが最も安定してAGENTS.mdを運用できるかを、データに基づいて判断することが可能になります。

Part 4: 戦略的実装とベストプラクティス

AGENTS.mdを組織的に導入し、その効果を最大化するためには、単にファイルを作成するだけでなく、戦略的な移行計画、効果的な作成ガイドライン、そして継続的なメンテナンス体制が必要です。このセクションでは、AGENTS.mdの導入を成功に導くための、実践的かつ具体的なアドバイスを提供します。

4.1 移行戦略：シンボリックリンクによる統一

多くの開発チームが直面する現実は、すべてのAIツールが即座にAGENTS.mdに完全対応するわけではない、ということです。この過渡期において、後方互換性を維持しながら標準化を進めるための最も効果的かつ広く推奨されている戦略が、シンボリックリンク（symlink）の活用です 1。

この移行プロセスは、以下の手順で実行します：

1. 指示内容の集約: まず、プロジェクト内に散在するすべてのツール固有の設定ファイル（例: .cursorrules, CLAUDE.md, .github/copilot-instructions.md）の内容をレビューし、一つのマスターファイルとしてのAGENTS.mdに集約します。
2. 旧ファイルの移行: 既存の設定ファイルをリネームするか、安全な場所に移動させます。
3. シンボリックリンクの作成: 古い設定ファイルがあった場所に、新しいAGENTS.mdファイルを指すシンボリックリンクを作成します。

以下に、主要なツールに対する具体的なコマンド例を示します 2：

• Cursorからの移行:
  mv.cursorrules AGENTS.md && ln -s AGENTS.md.cursorrules
• Claude Codeからの移行:
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
• AGENT.md（単数形）からの移行:
  mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md 8

このアプローチにより、開発チームはAGENTS.mdを唯一の「信頼できる情報源（Single Source of Truth）」としてメンテナンスに集中できる一方で、まだ古いファイル名を参照するツールも、シンボリックリンクを通じて同じ情報を読み込むため、シームレスに動作し続けます。これは、多様なツールが混在する環境において、混乱を最小限に抑えながら標準化を推進するための、極めて実用的な技術的プレイブックです。

4.2 効果的なAGENTS.mdファイルの作成

AGENTS.mdの価値は、その存在自体ではなく、記述される内容の質によって決まります。AIエージェントから高品質な出力を引き出すためには、人間が新人の開発者に指示を出す際と同様の、明確さと具体性が求められます。複数の情報源から集約されたベストプラクティスは以下の通りです。

• 行動可能、集中的、かつ正確であること: 「コードをきれいにする」といった曖昧なガイダンスは避け、「すべての関数にJSDocコメントを追加する」のように、エージェントが具体的な行動に移せるレベルで指示を記述します。ルールは、明確な社内ドキュメントのように書くべきです 4。
• 具体的なコマンドを使用すること: シェルコマンドやビルドコマンドは、バッククォート（``）で囲んでインラインコードとして記述します。これにより、エージェントがコマンドを推測したり、誤って解釈したりすることなく、そのままコピー＆ペーストして実行できる確率が高まります 5。
• 簡潔さを保つこと: ファイルの長さは150行から500行程度に収めることを目指します。長大なファイルは、エージェントの処理速度を低下させ、重要な指示がノイズに埋もれてしまう原因となります 4。もしルールが長くなる場合は、関連する内容ごとにファイルを分割し、階層構造を活用することを検討します 4。
• 実例を提供すること: 抽象的なルールだけでなく、優れたパターンの具体例を示すことが非常に効果的です。「フォームコンポーネントを作成する際は、app/components/DashForm.tsxをコピーして参考にすること」のように、参照すべき特定のファイル名を挙げることで、エージェントの理解を助け、一貫性を促進します 4。
• リンクを活用し、重複を避けること: READMEや設計ドキュメントに既に詳細な説明が存在する場合、その内容をAGENTS.mdにコピー＆ペーストするべきではありません。これは、ドキュメントの二重管理による不整合のリスクを生むだけでなく、AIエージェントの貴重なコンテキストウィンドウ（一度に処理できる情報量）を無駄に消費します。代わりに、「プロジェクトの全体像については(README.md)を参照」のように、Markdownのリンク機能を使って既存のドキュメントを指し示すのが賢明です 5。

これらのガイドラインに従うことで、AGENTS.mdは単なる設定ファイルから、AIエージェントのパフォーマンスと出力品質を飛躍的に向上させるための、強力なツールへと昇華します。

4.3 セキュリティとメンテナンス

AGENTS.mdの導入は、開発効率を向上させる一方で、新たなセキュリティリスクとメンテナンスの責務をもたらします。これらを軽視することは、組織に深刻な問題を引き起こす可能性があります。

セキュリティに関する考慮事項:
AGENTS.mdファイルの内容は、多くの場合、AIエージェントのシステムプロンプトに直接注入されます。これは、AGENTS.mdがプロンプトインジェクション攻撃の新たなベクトルとなり得ることを意味します 25。悪意のある、あるいは単に不注意に書かれた指示がリポジトリにコミットされた場合、エージェントが意図しないコマンドを実行したり、機密情報を漏洩させたりする可能性があります。このリスクは、特定のツールに限定されず、AGENTS.mdをサポートするすべてのAIアシスタントに共通するものです 25。
このリスクを軽減するためには、AGENTS.mdを単なるドキュメントファイルとしてではなく、ソースコードと同等の注意を払って扱う必要があります。具体的には、以下の対策が不可欠です。

• コードレビューの徹底: AGENTS.mdへのすべての変更は、他のソースコードと同様に、プルリクエストを通じてチームメンバーによるレビューを受けるべきです 5。
• セキュリティスキャンの対象に含める: 可能であれば、自動化されたセキュリティスキャンツールで、AGENTS.md内に危険なコマンドやパターンが含まれていないかをチェックします。

メンテナンスに関する考慮事項:
AGENTS.mdは、一度作成したら終わり、という静的なドキュメントではありません。プロジェクトの進化と共に陳腐化し、誤った情報源となってしまう危険性を常に孕んでいます。古いビルドコマンドや廃止されたコーディング規約が残っていると、エージェントはそれに従って誤ったコードを生成し、結果的に手戻りを増やすことになります。
したがって、AGENTS.mdは**「生きたドキュメント（living documentation）」として扱われるべきです 8。ビルドプロセス、依存関係、テスト手順、あるいはアーキテクチャ上の規約に変更があった場合は、それに関連するソースコードの変更と同じコミットでAGENTS.mdを更新する**ことをチームの規律として徹底する必要があります 5。これにより、AGENTS.mdは常にコードベースの現状を正確に反映した、信頼性の高い情報源であり続けることができます。

Part 5: 結論：エージェント設定の現状と未来

本レポートでは、AGENTS.mdという新たな標準を、その起源から各ツールの具体的な実装、そして戦略的な導入方法に至るまで、多角的に分析してきました。この最終セクションでは、これまでの調査結果を統合し、AIエージェント設定の現状を総括するとともに、この標準が今後どのような道を辿るかについての専門的な見解を述べます。

5.1 互換性と優先順位に関する調査結果の要約

AGENTS.mdは、AIコーディングエージェントが乱立する中で発生した設定ファイルの断片化という現実的な問題を解決するため、事実上の業界標準（デファクトスタンダード）として見事に台頭しました。そのシンプルさと柔軟性により、多くの主要ツールに採用され、開発者がAIエージェントに指示を与えるための共通言語としての地位を確立しつつあります。

しかしながら、本分析が明らかにしたように、その実装はツール間で均一とは程遠いのが現状です。「一度書けば、どこでも（同じように）動く」という理想的な互換性は、今日においては神話に過ぎません。

互換性を阻む根本的な課題は、AGENTS.mdというファイル形式そのものにあるのではありません。真の問題は、各ツールが持つ独自の機能やレガシーな設定ファイルとAGENTS.mdがどのように相互作用するかを規定する、複雑で、多くの場合文書化されていない優先順位ルールにあります。GitHub Copilotにおける独自設定との曖昧な関係、Devinの予測不能な自動知識取り込み、Cursorの機能豊富な独自システムとのトレードオフ、そしてGemini CLIのユーザー設定に依存するオプトイン方式は、それぞれが標準化への異なるアプローチと課題を示しています。

したがって、技術リーダーは、「AGENTS.mdをサポートしているか」という表面的な問いを超え、「どのようにサポートしているか」という実装の深層を理解しなければ、ツールの挙動を予測し、安定した開発環境を構築することはできません。

5.2 将来の展望：慣習から仕様へ

AGENTS.mdが現在、厳格なスキーマを持たない緩やかな「社会契約」として機能している状態は、急速に進化する技術分野の初期段階では典型的な現象です。しかし、エコシステムが成熟するにつれて、より高い予測可能性と信頼性への要求が高まることは避けられません。

今後12ヶ月から24ヶ月の間に、AGENTS.mdは現在の非公式な慣習から、より形式的な仕様へと進化していくと予測されます。これは、コミュニティ主導で「Agent Rules v1.0」のような仕様策定の動きとして具体化する可能性があります 15。この仕様には、標準化された見出し（例: ## Setup, ## Testing）、Markdownのフロントマターのようなメタデータ（例: ルールの適用範囲を指定するscope）、そして最も重要な点として、異なる命令ソース間の優先順位に関する明確なガイドラインが含まれるかもしれません。また、AGENTS.mdとAGENT.mdの分裂は、完全に複数形に収束するでしょう。

しかし、この形式化が進んだとしても、普遍的な標準のシンプルさと、各ツールベンダーが提供したい革新的な独自機能との間の緊張関係が完全になくなることはないでしょう。最も現実的な未来の姿は、ハイブリッドモデルです。すなわち、プロジェクトの基本的なセットアップや規約といった全体の80%を占める共通の指示はAGENTS.mdで標準化し、特定のツールに依存する高度なワークフローやスコープ指定といった残りの20%は、引き続き独自の設定ファイルで管理するという形です。

最終勧告

今日のエンジニアリングリーダーが取るべき戦略的な道筋は明確です。

1. AGENTS.mdをベースラインとして採用する: すべての新規および既存プロジェクトにおいて、AIエージェントへの指示の第一の場所としてAGENTS.mdを導入します。
2. レガシー設定をクリーンアップする: 予測不能な挙動の最大の原因である、ツール固有の古い設定ファイル（.cursorrules, .github/copilot-instructions.mdなど）をリポジトリから意図的に、かつ徹底的に削除する方針を強制します。これにより、AGENTS.mdが唯一の信頼できる情報源として機能する、クリーンな環境を構築します。
3. 開発者トレーニングに投資する: チームメンバーに対し、本レポートで概説したような、明確で、簡潔で、行動可能なルールを作成するためのベストプラクティスに関するトレーニングを実施します。
4. ツールごとの挙動を内部で文書化する: 組織として採用する各AIツールについて、公式ドキュメントの不足を補うための内部監査を実施します。特に、AGENTS.mdと他の命令ソースとの優先順位に関する挙動を実験的に検証し、その結果をチーム内のナレッジベースに文書化します。

この体系的なアプローチによってのみ、組織はAGENTS.mdという標準の真の価値を引き出し、AI開発エージェントから予測可能で、信頼性が高く、一貫した成果を得ることができるでしょう。

引用文献

1. AGENTS.md: A New Standard for Unified Coding Agent Instructions - Addo Zhang - Medium, 10月 14, 2025にアクセス、 https://addozhang.medium.com/agents-md-a-new-standard-for-unified-coding-agent-instructions-0635fc5cb759
2. AGENTS.md: The New Standard for AI Coding Assistants by proflead Aug, 2025 - Medium, 10月 14, 2025にアクセス、 https://medium.com/@proflead/agents-md-the-new-standard-for-ai-coding-assistants-af72910928b6
3. This repository defines AGENT.md, a standardized format that lets your codebase speak directly to any agentic coding tool. - GitHub, 10月 14, 2025にアクセス、 https://github.com/agentmd/agent.md
4. AGENTS.md - Builder.io, 10月 14, 2025にアクセス、 https://www.builder.io/c/docs/agents-md
5. Agents.md: A Comprehensive Guide to Agentic AI Collaboration by DhanushKumar Sep, 2025 Artificial Intelligence in Plain English, 10月 14, 2025にアクセス、 https://ai.plainenglish.io/agents-md-a-comprehensive-guide-to-agentic-ai-collaboration-571df0e78ccc
6. Agents.md: The README for Your AI Coding Agents - Research AIMultiple, 10月 14, 2025にアクセス、 https://research.aimultiple.com/agents-md/
7. AGENTS.md - Devin Docs, 10月 14, 2025にアクセス、 https://docs.devin.ai/onboard-devin/agents-md
8. AGENTS.md, 10月 14, 2025にアクセス、 https://agents.md/
9. AGENTS.md - Factory Documentation, 10月 14, 2025にアクセス、 https://docs.factory.ai/cli/configuration/agents-md
10. openai/agents.md: AGENTS.md — a simple, open format for guiding coding agents - GitHub, 10月 14, 2025にアクセス、 https://github.com/openai/agents.md
11. Keep your AGENTS.md in sync - One Source of Truth for AI Instructions - Kaushik Gopal, 10月 14, 2025にアクセス、 https://kau.sh/blog/agents-md/
12. Copilot coding agent now supports AGENTS.md custom instructions …, 10月 14, 2025にアクセス、 https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
13. Adding repository custom instructions for GitHub Copilot, 10月 14, 2025にアクセス、 https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot
14. Adding personal custom instructions for GitHub Copilot, 10月 14, 2025にアクセス、 https://docs.github.com/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot
15. Feature Request: Add Support for AGENTS.md in GitHub Copilot Chat for Interoperability with Agent Rules Standard · Issue #256828 · microsoft/vscode, 10月 14, 2025にアクセス、 https://github.com/microsoft/vscode/issues/256828
16. Knowledge Onboarding - Devin Docs, 10月 14, 2025にアクセス、 https://docs.devin.ai/onboard-devin/knowledge-onboarding
17. Rules Cursor Docs, 10月 14, 2025にアクセス、 https://cursor.com/docs/context/rules
18. My Best Practices for MDC rules and troubleshooting - How To - Cursor - Community Forum, 10月 14, 2025にアクセス、 https://forum.cursor.com/t/my-best-practices-for-mdc-rules-and-troubleshooting/50526
19. Use agentic chat as a pair programmer Gemini Code Assist - Google for Developers, 10月 14, 2025にアクセス、 https://developers.google.com/gemini-code-assist/docs/use-agentic-chat-pair-programmer
20. Hands-on with Gemini CLI - Google Codelabs, 10月 14, 2025にアクセス、 https://codelabs.developers.google.com/gemini-cli-hands-on
21. Advanced Gemini CLI: Part 1 — What’s the Context? by Prashanth Subrahmanyam Google Cloud - Community Oct, 2025 Medium, 10月 14, 2025にアクセス、 https://medium.com/google-cloud/advanced-gemini-cli-part-1-whats-the-context-6fd91326979b
22. Proactiveness considered harmful? A guide to customise the Gemini CLI to suit your coding style by Daniela Petruzalek Google Cloud - Medium, 10月 14, 2025にアクセス、 https://medium.com/google-cloud/proactiveness-considered-harmful-a-guide-to-customise-the-gemini-cli-to-suit-your-coding-style-b23c9b605058
23. Letting CC use Gemini CLI? This is how to let Gemini use CLAUDE.md files as instruction files : r/ClaudeAI - Reddit, 10月 14, 2025にアクセス、 https://www.reddit.com/r/ClaudeAI/comments/1lsdyge/letting_cc_use_gemini_cli_this_is_how_to_let/
24. Improve your AI code output with AGENTS.md (+ my best tips) - Builder.io, 10月 14, 2025にアクセス、 https://www.builder.io/blog/agents-md
25. AGENTS.md: Why your README matters more than AI configuration files, 10月 14, 2025にアクセス、 https://devcenter.upsun.com/posts/why-your-readme-matters-more-than-ai-configuration-files/