みんなの「AGENTS.md」の内容・メンテナンス状況を実態調査してみた
公開日
AIエージェントが自律的にコーディングタスクをこなす時代が本格化しつつあります。しかし、エージェントがプロジェクトごとの固有のルールや設計思想を正確に理解するためには、人間がプロジェクトに参画する時と同様に、適切な事前情報（コンテキスト）を提供する必要があります。
本記事では、Seyedmoein Mohsenimofidi氏らが発表した論文「Context Engineering for AI Agents in Open-Source Software」に基づき、オープンソースソフトウェア（OSS）開発におけるAIコンテキストファイルの活用状況と、コンテキストエンジニアリングの実態について解説します。
オープンソースにおけるAIコンテキストファイルの導入状況
本調査は、一定の基準を満たしたGitHub上の活発なオープンソースプロジェクト10,000件を対象に、2025年9月から10月にかけてデータの収集および分析を行ったものです。特に、標準フォーマットであるAGENTS.mdの分析においては、ノイズを減らすために2025年1月1日以前に作成されたファイルを除外し、集計を行っています。
調査結果によると、対象リポジトリのうち466件（約5%）が、すでに少なくとも1つのAIコンテキストファイルを採用していました。これは、AIエージェントへの指示を明文化する取り組みが、まだ早期導入の段階にあることを示しています。ファイル形式別の具体的な採用件数は以下の通りです（複数採用しているプロジェクトを含む）。
- copilot-instructions.md: 229件
- CLAUDE.md: 183件
- AGENTS.md: 119件
- GEMINI.md: 29件
特定のAIツールに依存しないオープンな標準規則として提案されているAGENTS.mdも、すでに100件以上のプロジェクトで導入されていることがわかります。
また、主要なプログラミング言語別の導入件数を見ると、以下のようになっています。
- TypeScript: 135件
- Go: 58件
- Python: 58件
- C#: 56件
- Java: 36件
- JavaScript: 34件
- C++: 32件
- Rust: 29件
このデータから、特定の言語エコシステムにおいてAIエージェントの活用が先行している様子がうかがえます。さらに、言語と利用されるAIツールの間には、以下のような興味深い傾向も見られました。
- 特定ツールへの偏り: C#のプロジェクトではCopilot用の指示ファイルが強く支持されている一方で、TypeScriptのプロジェクトではClaude Code（
CLAUDE.md）が非常に人気を集めています。 - 複数ファイルの併用: プロジェクトによっては複数のコンテキストファイルが同時に配置されており、最も一般的な組み合わせは
AGENTS.mdとCLAUDE.mdの併用（25件）でした。
AGENTS.mdに含まれる情報カテゴリと記述スタイル
ツール非依存の標準フォーマットとして注目を集めるAGENTS.mdの内部には、一体どのような情報が書き込まれているのでしょうか。以下の表は、155件のAGENTS.mdファイルから抽出された見出しを分類し、頻出する情報カテゴリをまとめたものです。
| カテゴリ | 説明 | 頻度 |
|---|---|---|
| 規約/慣例 | コーディング規約、命名/フォーマット規約、ベストプラクティス | 50 |
| コントリビューションガイドライン | コントリビューションの手順（ブランチ、コードレビュー、CI要件など） | 48 |
| アーキテクチャ/構成 | プロジェクトの構成（主要ディレクトリ、モジュール、関係性など） | 47 |
| ビルドコマンド | ビルド、実行、デプロイ用のコマンドリスト | 40 |
| 目標/目的 | プロジェクトやエージェントの目的、高度な機能の要約 | 32 |
| テスト実行 | テストスイートや個別テストの実行方法と使用ツール | 32 |
| メタデータ | ファイルのメタデータや設定情報 | 29 |
| テスト戦略 | テストの全体的なアプローチ（ユニット、統合など） | 24 |
| 技術スタック | プロジェクトで使用されるプログラミング言語やライブラリ | 15 |
| セットアップ | インストールの前提条件、環境構築の手順 | 11 |
| リファレンス | 頻出コマンドのリスト、APIリファレンス | 9 |
| トラブルシューティング | 開発中の一般的なエラーや問題の解決ガイダンス | 8 |
| パターン/例 | 再利用可能なパターン、エージェントの設定例 | 8 |
| セキュリティ | セキュリティ関連のアドバイスや注意事項 | 6 |
最も多かったのは、コーディング規約（規約/慣例）に関する記述です。AIエージェントが一貫性のあるコードを出力できるよう、命名規則やフォーマットを明示しています。次いで、コントリビューションのガイドラインや、プロジェクトのアーキテクチャ構造に関する説明が多く見られました。
また、AIに対する指示の「記述スタイル」にも複数のパターンが存在することが判明しました。単に現状を説明する「記述的」なものから、「既存のコードスタイルに従え」と直接命じる「規範的」なもの、「メインブランチには直接コミットするな」と制限をかける「禁止的」なものまで様々です。開発者たちは、AIに期待通りの行動をとらせるため、表現方法を試行錯誤している段階にあります。
AIへの指示はどのようにメンテナンスされているか
AIエージェント向けのコンテキストファイルは、一度作成して終わりではありません。ソースコードと同様に、プロジェクトの進行に合わせてバージョン管理され、継続的に更新されていきます。以下の表は、10回以上のコミット履歴があるAGENTS.mdファイルの変更内容をカテゴリ分けしたものです。
| カテゴリ | 説明 | 頻度 |
|---|---|---|
| 指示の追加 | 既存セクションへの指示行の追加 | 78 |
| 指示の修正 | セクション内の指示行の修正（typo修正等を除く） | 59 |
| セクションの追加 | AGENTS.mdへの新規セクションの追加 | 26 |
| 指示の削除 | 既存セクションからの指示行の削除 | 23 |
| 見出しの修正 | 既存のセクション見出しタイトルやレベルの修正 | 23 |
| テキストの修正 | タイポの修正など、コンテンツの軽微な変更 | 19 |
| 書式変更 | 構造に関係しない視覚的な体裁の変更 | 10 |
| セクションの削除 | セクション全体の削除 | 2 |
| 参照の更新 | URLなど参照元の更新 | 2 |
表から読み取れる通り、「指示の追加」と「指示の修正」が変更理由の大半を占めています。実際のコミットメッセージを確認すると、「AIエージェントが特定のチェックスクリプトを呼び出さないように指示を削除する」といった変更や、テストの不安定な挙動（フレーキーテスト）を回避するためにAIへの指示をアップデートする事例が確認されています。
このように、エージェントの実際の出力結果やエラーを観察しながら、開発者がコンテキストファイルの内容を微調整していくプロセスが日常的に行われています。
まとめ：AIに向けたドキュメント整備の時代へ
ソフトウェア開発において、人間向けのREADMEファイルを用意することは一般的な習慣でした。しかし今後は、それに加えてAIエージェントに向けた専用のドキュメントを記述し、メンテナンスしていくスキルが求められます。
コンテキストエンジニアリングは、プロンプトのテクニックにとどまらず、プロジェクトのルールをAI可読な形で構造化する継続的な取り組みです。AIエージェントの能力を最大限に引き出すために、まずはご自身のプロジェクトにAGENTS.mdを導入し、ルールの明文化から始めてみてはいかがでしょうか。
生成AIの導入や活用にお困りですか？ 弊社のサービス は、開発チームが抱える課題を解決し、生産性と幸福度を向上させるための様々なソリューションを提供しています。ぜひお気軽にご相談ください！
参考資料: