マニュアル対ルールブック：高くつく誤解
多くのチームがAGENTS.mdファイルの役割を誤解しており、それが運用上の大きな死角を生んでいます。Coldteaのエンジニアによる最近の調査では、厳しい現実が明らかになりました。GitHubのトップ1,000リポジトリのうち、AGENTS.mdファイルを持っているのはわずか27%であり、その大部分が誤った方法で活用されています。この広範な見落としが、AIによる貢献を管理する上で重大な欠落を生んでいます。
核心的な問題は、「操作マニュアル」と「ルールブック」を混同していることにあります。既存のAGENTS.mdファイルのほとんどはマニュアルとして機能しており、プロジェクトのアーキテクチャの説明や、ビルドおよびテストのための正確なコマンドの列挙に重点を置いています。それらはAIに「どのように」操作すべきかを伝えていますが、決定的に「何を」すべきか、あるいは「何をすべきでないか」を制限できていません。
真のAGENTS.mdはルールブックとして機能し、AIエージェントに対する厳格なガードレールと明確な禁止事項を確立します。このルールブックがなければ、エージェントは境界線なしで動作し、一貫性のない貢献、予期せぬ動作、潜在的なバグの混入を招きます。例えば、大規模なリポジトリでは「禁止事項」の記述にほぼ2倍のスペースを割いており、この必要性を理解していることが明確に示されています。「しなければならない」「常に」「決して〜してはならない」といった明確な指示がないことは、強力なツールを予測不可能な負債へと変えてしまいます。
「禁止」の力：VercelとBunからの教訓
Coldteaの調査により、主要なリポジトリに見られる重要なパターンが明らかになりました。最も効果的なAGENTS.mdファイルは、明示的な禁止事項を優先しています。トップ100のリポジトリでは、小規模なプロジェクトと比較して「何をすべきでないか」というルールに約2倍のスペースを割いており、暗黙的な「禁止」を意味する文章が784件確認されました。
これらの高パフォーマンスなファイルの90%が、AIエージェントを導くために「must（しなければならない）」「always（常に）」「never（決して〜してはならない）」といった決定的な言葉を使用しています。これは偶然ではなく、意図しないアクションを防ぎ、コードの整合性を維持するための意図的な戦略であり、堅牢なシステムの証です。
具体的な例がこの精度の高さを裏付けています。例えば、VercelのNext.jsリポジトリでは、コミットから「generated with Claude code」というフッターを明示的に禁止しています。このレベルの詳細さが、AIによる貢献をプロジェクトの基準や人間の期待と完全に一致させることを保証しています。
Bunのリポジトリは、「NEVER run bun test directly - it won't include your changes（bun testを直接実行してはならない。変更が含まれないため）」という大文字の警告で、もう一つの強力な例を示しています。このような直接的な禁止は曖昧さを排除し、ビルドやテスト環境を損なう可能性のある有害なコマンドをエージェントが実行することを防ぎます。
AIエージェントは人間の文脈や直感なしに動作するため、明確な境界線が不可欠です。彼らはプロジェクトの歴史、チームの規範、あるいは潜在的な副作用に対する暗黙の理解を欠いています。したがって、デジタルなガードレールとして機能させるために、避けるべきファイル、関数、パターンを正確に伝える必要があります。このプロアクティブなアプローチが、微細なエラーを防ぎ、コードベースを保護します。
33語から14,000語へ：ファイルの適切なサイズを見つける
AGENTS.mdファイルの長さの極端なばらつきは、新たなベストプラクティスが模索されていることを示しています。極端な例を挙げると、VS Codeのファイル全体はわずか33語で、単純なリダイレクトとして機能しています。Neovimのファイルも35語とほとんど変わらず、AI生成コミットに対する単一の開示ルールに焦点を当てています。一方で、OpenHandsリポジトリは14,000語という膨大な指示セットを提示しています。この広大なスペクトルは、最適な設計図を定義することの難しさを浮き彫りにしています。
しかし、Coldteaの研究は実用的な指針を示しています。それは、中央値として約1,200ワードという長さです。この数値は、ほとんどのプロジェクトにとって現実的なスイートスポットであり、AIコントリビューターにとって十分な詳細さと、人間による監視や迅速な反復に必要な明瞭さのバランスを取っています。これは、冗長になりすぎることなく、効果的なエージェントの境界線を設定するための現実的なベンチマークです。
最終的に、AGENTS.mdファイルの複雑さは、プロジェクトの規模と、AI支援によって軽減しようとする特定のリスクに直接合わせる必要があります。小規模で焦点の絞られたユーティリティであれば最小限のガードレールで済むかもしれませんが、複雑で複数のコントリビューターが関与するシステムには、堅牢なルールブックが必要です。コンテキストファイルがコーディングエージェントにどのように役立つかについてのより深い洞察については、Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?のような研究を参照してください。
この記事が気に入ったら、毎朝同じようなものをメールで受け取れます。
1日1通 · 2クリックで解除 · サードパーティのトラッキングなし
エージェント対応リポジトリのための3つのチェックリスト
GitHubの上位1,000リポジトリを分析した結果、Coldteaのエンジニアは効果的なAGENTS.mdファイルの要点を3つのチェックリストにまとめました。これは単なる提案ではなく、AIエージェントに対する正確なコマンドを提供し、ファイルを堅牢なルールブックへと変えるためのものです。
エージェント対応リポジトリにするために、AGENTS.mdに以下を含めてください：
- 少なくとも1つの明示的な「禁止（don't）」ルール。効果的なファイルの86%に含まれるこの重要な指示は、エージェントの行動に対する明確な境界線を設定します。このような否定的な制約がないと、エージェントはしばしば推測に頼ってしまい、VercelのNext.jsで見られたような、望ましくない変更や「生成された」フッターを導入してしまう可能性があります。これには、エージェントが決して触れてはならないものを明確に定義することが含まれます。
- コミットとプルリクエストのフォーマット方法を細かく指定する。成功しているファイルの79%に見られるこのルールは、人間がコードを提出するかAIエージェントが提出するかに関わらず、プロジェクトの履歴と基準が一貫性を保つことを保証します。規定されたフォーマットは、バージョン管理システムにおける混乱を防ぎます。
- テストとコードのLintを実行する方法を正確に記述する。効果的なファイルの約4分の3（75%）がこれらの正確な指示を提供しています。これらはオプションのステップではなく、エージェントが実行すべき直接的なコマンドであり、すべての貢献が統合前に品質ゲートを確実に通過するようにします。
よくある質問（FAQ）
プロジェクトがAGENTS.mdファイルで犯す主な間違いは何ですか？
最も一般的な間違いは、AGENTS.mdを（コマンドを羅列する）操作マニュアルとして扱ってしまうことです。本来は、AIエージェントが何をすべきか、そしてさらに重要なことに、何をすべきでないかを指示する厳格なルールブックとして扱うべきです。
優れたAGENTS.mdファイルの重要な要素は何ですか？
効果的なファイルには、明示的な否定的な制約（「禁止」ルール）、コミットとPRのフォーマットに関する明確な指示、そしてテストとコードのLintを実行する方法に関する正確なガイドラインが含まれています。
大規模プロジェクトと小規模プロジェクトでは、異なるAGENTS.mdファイルが必要ですか？
はい。研究によると、大規模で複雑なプロジェクトほど、より厳格なAGENTS.mdファイルを持っており、コードベースを保護するために否定的な制約（「禁止」ルール）にスペースのほぼ2倍を割いています。
GitHubの上位リポジトリにおいて、AGENTS.mdファイルはどの程度一般的ですか？
まだ比較的まれです。GitHubの上位1,000リポジトリを調査したところ、AGENTS.mdファイルを持っていたのはわずか27%であり、AIエージェントを導くための改善の余地が大きく残されていることを示しています。