なぜ「ファイル名だけ」のAGENTS.mdが勝ったのかAIコーディング設定ファイル戦国時代、18か月の終戦史

1. 結論：AGENTS.mdは仕様を増やしたからではなく、合意点を減らしたから勝った

AIコーディングエージェントの設定ファイル戦国時代は、少なくとも「プロジェクト共通の指示をどこに置くか」という問いについては、ほぼ終わった。

2026年8月現在、AGENTS.mdの公式サイトは6万を超えるオープンソースプロジェクトでの利用を掲げ、Codex、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Zed、Jules、Factoryなど20を大きく超えるツールを互換一覧に載せている。公式GitHubリポジトリは8月30日時点で23,991スター、1,815フォークだった。^[1][2]

しかし、この標準にはJSON Schemaも、必須見出しも、バージョン番号もない。公式FAQは「必須フィールドはない。標準的なMarkdownにすぎない」と明記する。決めたのは、ほとんどファイル名と探索規則だけである。^[1]

普通、標準化は項目を増やす仕事に見える。名前、型、制約、エラー、互換性を細かく定義する。AGENTS.mdが示したのは、その逆だった。

競合各社が合意しなければならない面積を、ファイル名一つまで小さくする。中身は各プロジェクトに返す。

これなら、ツール提供者は自社の思想を捨てずに参加できる。開発者は新しい設定言語を覚えずに済む。既存のMarkdown処理とプロンプト注入機構だけで実装できる。AGENTS.mdは「全員が同じになる標準」ではなく、「全員が同じ入口を見つけられる標準」だった。

それが勝因であり、同時に限界でもある。入口が統一されても、ツール固有のスコープ、権限、フック、サブエージェント、Skillsまでは消えない。本稿では、18か月の収束、例外として残るClaude Code、変換CLIの実態、そして指示ファイルを命令として扱うことのセキュリティリスクまでを一つの歴史としてたどる。

2. 七つのファイルを更新する日々から、18か月で一つの入口へ

2025年前半、AIコーディングツールが一斉に実用段階へ入ると、同じリポジトリに似た役割のファイルが増殖した。

• Cursorには当時の .cursorrules、のちの .cursor/rules/
• GitHub Copilotには .github/copilot-instructions.md
• Claude Codeには CLAUDE.md
• Clineには .clinerules
• Windsurfには .windsurfrules
• Gemini系には GEMINI.md
• さらに各ツール固有のコマンド、MCP、権限設定

コーディング規約を一行変えるたびに、同じ意図を複数の構文へ書き写す。別のツールを使うメンバーが加われば、同期先も増える。バージョン管理は「一つの変更を一つの履歴にする」ための道具なのに、その周辺で手作業の複製が常態化した。

一つの規約変更を七つの入口へ配る。これは設定を書く仕事というより、設定同士の差分を生まないための同期作業だった。

この不毛は、次の順番で収束していく。

2025年5月7日：Ampが単数形のAGENT.mdを提案する

前史は複数形ではない。SourcegraphのAIエージェントAmpは、2025年5月7日にルートの AGENT.md を読む機能を発表した。記事は、設定ファイルの増殖を避けるための命名標準として選び、他のエージェントにも追随してほしいと書いている。現在のページには、後日 AGENTS.md へ切り替えたという追記が残る。^[3]

2025年5月20日〜6月18日：標準を待たず、変換CLIが先に走る

5月20日にRuler、6月18日に日本人開発者dyoshikawa氏のrulesyncがGitHubへ作成された。どちらも「一つの正から複数ツール向け設定を生成する」発想を持つ。業界合意を待てない現場が、変換レイヤーで乱立を束ねようとしたのである。^[4][5]

2025年8月19日〜20日：複数形AGENTS.mdが公の器になる

現在の agentsmd/agents.md リポジトリは8月19日17時22分（UTC）に作成され、翌20日にサイトが公開された。Ampも同日、「OpenAIが複数形を選んだ。標準は一つの方がよい」として AGENTS.md 対応へ切り替えた。単数形を最初に掲げた側が、自案へ固執せず一文字の差を飲み込んだ。この小さな譲歩は、標準化の本質をよく表している。^[6][7]

公式サイトは、AGENTS.mdがCodex、Amp、Google Jules、Cursor、Factoryを含むエコシステムの共同努力から生まれたと説明している。ここは「ある一社が勝ち、他社が従った」というより、競合が同じ入口に価値を見いだした場面として読む方が正確だ。^[1]

2025年12月9日：Linux Foundation傘下へ移る

OpenAI、Anthropic、BlockはLinux Foundation傘下にAgentic AI Foundation（AAIF）を共同設立し、AGENTS.md、Model Context Protocol（MCP）、gooseを創設プロジェクトとして寄贈した。AGENTS.mdは一企業の便宜から、中立的な管理主体を持つオープンな基盤へ移った。OpenAIは同日の発表で、8月の公開から6万超のOSSプロジェクトへ採用されたと説明している。^[8][9]

18か月前にはファイルの乱立が当たり前だった。2026年8月には、逆に「なぜAGENTS.mdがないのか」を問う方が自然になった。標準化の速度は、仕様の厚さではなく、導入の軽さに支えられていた。

3. なぜ「何もない仕様」が、競合の詳細仕様に勝てたのか

AGENTS.mdが標準化したのは内容ではなく、発見可能性である。

ルートの予測可能な場所に、誰でも読めるMarkdownがある。大規模なモノレポでは、サブディレクトリへ別のAGENTS.mdを置き、近いファイルの指示を優先できる。公式サイトは、トップレベルを共通事項、内側をサブプロジェクト固有事項に分ける方式を案内している。^[1]

各ツールの内部構造を統一しなくても、差し込み口の場所と名前だけなら合意できる。AGENTS.mdは共通OSではなく、共通の玄関だった。

この薄さは、三者それぞれに利益がある。

1. ツール提供者：Markdownを読み、既存のコンテキストへ加えるだけで最低限の互換性を実装できる。自社独自のルール機構は残せる。
2. リポジトリ管理者：新しいDSL、エディタ、バリデータを導入せず、コードレビュー可能な文章として管理できる。
3. エージェント：ビルド、テスト、禁止事項、ディレクトリ構造を、毎回の会話で再説明されずに受け取れる。

もし必須キー、適用グロブ、権限モデル、フック形式、MCP定義まで一度に標準化していたら、合意は難しくなっただろう。各社には既存ユーザーと互換性があり、製品ごとの強みがある。「どの命令を、いつ、どの優先度で読むか」は競争領域でもある。

AGENTS.mdはそこへ踏み込まなかった。標準が決めすぎないことで、実装は早く、反対理由は少なくなった。

ただし、「スキーマがないから何を書いても同じように効く」という意味ではない。エージェントは文章を確定的な設定値ではなくコンテキストとして読む。長すぎる指示、矛盾、抽象語は遵守率を下げる。AGENTS.mdが薄い標準であるほど、各リポジトリには短く、具体的で、検証可能な文章を書く責任が返ってくる。

標準化の成功とは、判断を全部中央へ集めることではない。中央で決めるべき最小限と、現場へ返すべき自由を正しく切り分けることなのだ。

4. Claude Codeという例外──非対応なのに、二重管理は避けられる

2026年8月現在、Anthropicの公式ドキュメントは明快だ。Claude Codeが直接読むのは CLAUDE.md であり、AGENTS.md ではない。一方で同じページに専用の「AGENTS.md」節があり、既存のAGENTS.mdを次のようにimportする構成を公式に案内している。^[10]

@AGENTS.md

# Claude Code

Claude固有の指示がある場合だけ、ここへ追加する。

相対パスは、作業ディレクトリではなくimportを書いたファイルの位置を基準に解決される。importは再帰でき、現行の英語版公式ドキュメントでは最大4ホップ。コードスパンとコードブロック内の @ はimportとして評価されない。プロジェクト外への外部importは初回承認の対象になる。^[10]

シンボリックリンクでも共有できる。

ln -s AGENTS.md CLAUDE.md

ただし、Windowsでは管理者権限または開発者モードが必要になるため、チームの可搬性を優先するならimport方式の方が扱いやすい。Claude固有の指示を後ろへ足せることも利点である。

ここには重要な注意がある。importはコンテキスト節約ではない。 Anthropicは、importされた内容も起動時に展開され、コンテキストへ入ると明記する。ファイルを分ける利点は整理と所有範囲であり、同じ全文を無料で参照できる魔法ではない。長い手順は、常時読み込む指示ではなく、必要時に呼ぶSkillやパス限定ルールへ移す方がよい。^[10]

Claude Codeの非対応は、標準化の失敗というより、互換層の薄さを証明しているとも言える。たった一行のimportで唯一の正を保てるなら、ネイティブ対応を待つ間も内容を二重管理する必要はない。

5. 標準の後にも残る変換CLI──スター数と実利用が逆転する

AGENTS.mdが普及しても、Rulerやrulesyncの役割は消えていない。なぜなら、標準化されたのは共通指示の入口であり、各ツール固有の機能ではないからだ。

Cursorのスコープ付きルール、Claude Codeの .claude/rules/、Copilotのパス別instructions、MCP、コマンド、サブエージェント、Skills、hooks、permissionsは同じ形式ではない。rulesyncの現行READMEは、ルールだけでなくMCP、コマンド、サブエージェント、Skills、hooks、permissionsなどを多数のツールへ生成・変換する対応表を公開している。^[5]

共通の入口ができても、製品固有の機能までは同じにならない。変換CLIは、標準の外側に残る差分を加工する工房である。

2026年8月30日時点のGitHub APIと、直近30日（7月31日〜8月29日）のnpm Downloads APIを同じ時点で並べると、興味深い逆転が見える。^[11][12]

スターではRulerがrulesyncの2倍を超える。一方、npmの直近30日ダウンロードではrulesyncが約5.5倍で、100万回を超えた。ダウンロード数にはCI、キャッシュのない環境、同一利用者の反復実行が含まれるため、そのまま「利用企業数」にはできない。それでも、スターが関心や評価の一面、ダウンロードが継続的な機械利用の一面を映し、両者が一致しないことは明らかだ。

技術選定でGitHubスターだけを見るのが危うい理由もここにある。必要なのは、更新頻度、対応機能、生成物の差分、破壊的変更への追随、CIでの再現性、そして自分たちが本当に変換層を必要としているかである。

たとえば PanisHandsome/ai-rules-sync は依存ゼロの軽さを掲げ、AGENTS.md、CLAUDE.md、Cursor、Copilotなどの相互同期を狙う。筋はよいが、6月3日を最後にpushが止まっている。変化の速い領域では、軽さだけでなく追随を続けられるかが製品機能になる。^[13]

したがって、判断は単純だ。

• 共通のビルド、テスト、規約、禁止事項を共有するだけなら、まずAGENTS.md一枚で足りる。
• 複数ツール固有のスコープ、MCP、コマンド、Skillsまで同じ正から配りたいなら、変換CLIを検討する。
• 生成物は必ずコミットし、ツール更新で何が変わったかを差分レビューする。

変換CLIは標準化に負けた遺物ではない。標準が意図的に決めなかった領域を埋める、過渡期かつ実務的な互換層である。

6. 指示ファイルは文書ではなく命令である──Rules File Backdoorの教訓

AGENTS.mdを「READMEのエージェント版」と呼ぶと、無害な説明文に見える。しかしエージェントにとって、指示ファイルは単なるデータではない。行動を変える命令としてコンテキストへ入る。

2025年3月18日、Pillar SecurityはCursorとGitHub Copilotを対象にした「Rules File Backdoor」を公開した。不可視のUnicode文字、双方向テキスト制御、ゼロ幅文字などを使い、人間には見えにくい指示をルールファイルへ埋め込む供給網攻撃である。実証では、単純なHTMLページを作る依頼から、攻撃者管理サイトのスクリプトを読み込む変更が生成された。隠れた命令は、その追加を報告しないようエージェントへ指示していた。^[14]

人間の画面に見える文章と、モデルが受け取る命令が同じとは限らない。信頼された入口は、汚染されたときにも強く効く。

Pillarによれば、隠れた文字は当時GitHubのプルリクエスト画面でも見えず、フォーク後も残った。Cursorは自社側の脆弱性ではない、GitHubは生成提案をレビューするのは利用者の責任だと回答した。その後GitHubは2025年5月1日、隠れたUnicodeを含むファイルへ警告を表示する機能を公開した。警告は重要な前進だが、リポジトリ側の検査責任が消えるわけではない。^[14][15]

一元管理は、正しいルールを全プロジェクトへ配る。同じ仕組みは、汚染されたルールも全プロジェクトへ配る。中央化の効率と、供給網の爆発半径は表裏一体である。

現実的な防御は四層に分けられる。

1. 指示ファイルをコードとしてレビューする：AGENTS.md、CLAUDE.md、Skills、rules、生成済み設定をCODEOWNERSや必須レビューの対象にする。
2. 生成物をコミットする：実行時に外部から最新ルールを無条件取得せず、変換後の差分を人間が確認できる状態にする。
3. 不可視UnicodeをCIで検査する：少なくとも双方向制御、ゼロ幅文字、Unicode Tagsブロックを機械的に検出する。
4. 外部importを承認制にする：作業ディレクトリ外やネットワーク上の指示を、信頼済みのローカル文書と同じ扱いにしない。

たとえば、リポジトリ内の指示Markdownへ代表的な不可視制御文字が入っていないかを、ripgrepで補助検査できる。

rg -n --pcre2 '[\x{200B}-\x{200F}\x{202A}-\x{202E}\x{2060}-\x{2069}\x{E0000}-\x{E007F}]' \
  AGENTS.md CLAUDE.md .github/skills .claude 2>/dev/null

これはUnicodeセキュリティの完全な検査ではない。正当な多言語テキストを含むファイルで「ASCII以外を全部禁止する」のも乱暴だ。目的は、通常は不要な制御文字を検出し、必要なら理由をレビューできるようにすることにある。

7. 2026年の実践構成──一枚に全部詰めず、役割で三層に分ける

AGENTS.mdが唯一の正であることと、一枚に全手順を書くことは同義ではない。むしろ、どの作業でも必要な短い指示と、特定の場所・作業だけに必要な詳細を分ける方がよい。

この分け方なら、ルートは「憲法」、内側のAGENTS.mdは「地域条例」、Skillは「作業手順書」として機能する。VS CodeとGitHub Copilotの現行ドキュメントも、常時適用する単純な規約にはinstructions、複数手順やスクリプトを伴う反復作業にはAgent Skillsを使い分ける考え方を示している。^[16]

最小構成は次でよい。

repository/
├── AGENTS.md
├── CLAUDE.md              # 先頭に @AGENTS.md
├── frontend/
│   └── AGENTS.md          # フロント固有の指示
└── .github/
    └── skills/
        └── deploy/
            ├── SKILL.md
            └── scripts/

運用では、次の順番が壊れにくい。

1. ルートのAGENTS.mdを唯一の共通方針にする。
2. Claude Codeには CLAUDE.md からimportさせ、本文を複製しない。
3. 変更対象が限定される規約は、近いディレクトリまたはパス限定ruleへ移す。
4. 長い反復手順はSkillへ移し、必要時だけ読み込む。
5. 変換CLIを使うなら、入力と生成物の両方を版管理し、CIで再生成差分がゼロか確認する。
6. 指示ファイルの変更をセキュリティレビュー対象にする。

AGENTS.mdの薄さを「何でも一枚へ書ける」と解釈すると、数千行の巨大プロンプトができる。勝因だった最小性を、利用側が再び複雑さで埋めないことが重要である。

8. 結び：最強の標準は、最も多く決めた標準ではない

AGENTS.mdの歴史には、技術標準が定着する条件が凝縮されている。

Ampは単数形を先に掲げたが、複数形へ譲った。OpenAI、Google、Cursor、Factoryなどの競合は、自社機能を捨てずに共通の入口を選んだ。Linux Foundation傘下のAAIFへ移ることで、所有の中立性も補強された。変換CLIは消えず、標準の外側に残る差分を扱う道具へ進化した。

そして、成功した標準は安全とは限らない。読む主体が人間からエージェントへ変わると、Markdownは文書であると同時に実行環境へ影響する命令になる。便利な入口ほど、レビュー、Unicode検査、外部importの信頼境界が必要になる。

2026年に新しいリポジトリを始めるなら、実践的な答えは簡素だ。

• ルートに短い AGENTS.md を置き、共通方針の唯一の正とする。
• Claude Code向けの CLAUDE.md は @AGENTS.md から始め、固有差分だけを足す。
• ローカルな規約はネスト、長い反復手順はSkillへ分ける。
• 変換ツールは、複数製品の固有機能を本当に同期したいときだけ導入する。
• 指示ファイルと生成物をコミットし、コードと同じ厳しさで差分をレビューする。

AGENTS.mdは、詳細仕様の王座を奪ったのではない。詳細仕様同士が争う場所の一段上に、「まずここを見ればよい」という小さな公共空間を作った。

戦国時代を終わらせたのは、最も強い設定言語ではなかった。誰もが譲れるほど小さく、誰もが使えるほど普通の、たった一つのファイル名だった。