1,866件のGitHubプロジェクトの分析、AIエージェント向け指示ファイルに課題

現在、人気のあるGitHubプロジェクトの3分の1に、AIコーディングエージェント向けの具体的な指示ファイルが含まれており、AGENTS.mdが標準フォーマットとして浮上しています。アクティブな1,866のリポジトリに関する最近の分析では、特にTypeScriptプロジェクトにおいて採用が広まっているものの、これらの指示の品質と強制力には大きなばらつきがあることが判明しました。

何が起きたか

研究者たちは、チームがAIアシスタントをどのようにガイドしているかを理解するために、GitHubで最もスターを集めているリポジトリを分析しました。彼らは今年中にコミットを受けた1,866のプロジェクトを調査し、エージェントの挙動を制御するために設計されたAGENTS.mdやCLAUDE.mdなどのファイルを探しました。その結果、これらのプロジェクトのうち627件（34%）が少なくとも1つの指示ファイルを同梱していることが分かりました。

データからは、エージェント指示を持つプロジェクトの78%に表示されるAGENTS.mdへの明確な好みが見て取れます。CLAUDE.mdもまた一般的で、該当するプロジェクトの52%に存在しますが、AGENTS.mdを置き換えるのではなく、通常は共存しています。プログラミング言語による採用率には大きな差があります。TypeScriptは73%のプロジェクトがエージェントファイルを含んでおり、Go（58%）、Rust（52%）が続きます。対照的に、Perlプロジェクトではほとんど含まれておらず、採用率はわずか4%です。

この研究では、ファイルの長さと冗長性に関する問題も強調されました。主要な指示ファイルの半分は100行を超えており、中央値は106行です。約30のプロジェクトでは、異なる内容のAGENTS.mdとCLAUDE.mdなど、2つの別々のルールブックを維持しており、異なるツールを使用するエージェントにとって潜在的な競合を生み出しています。

仕組み

この分析は、自動化スクリプトとAIレビュアーによる人間のような判断を組み合わせたものです。まずスクリプトが、ファイルの存在、長さ、見出しに関するデータを収集しました。次に、別のAIレビュアーがランダムに抽出したルールのサンプルを分類し、それらが本物の指示であるかどうか、そしてコードによって強制可能かどうかを判定しました。

研究者たちは、5つのルールのうち3つが、少なくとも部分的にはスクリプト、リンター、またはテストによってチェックできることを発見しました。しかし、20個のルールに1個未満しか、それらを強制するチェックを明示的に名指ししていませんでした。ほとんどのルールは、エージェントが単に指示を記憶することに依存しており、これは自動的な強制よりも信頼性が低いです。例えば、「空の分割代入パターンを使用しない」というルールは、リンターによって容易に検出できますが、ファイルにはどのリンタールールが適用されるかは指定されていません。

この研究では、これらのファイルがどこにあるかも調べられました。多くはリポジトリのルートにありますが、30%のプロジェクトは指示ファイルをサブフォルダに置いています。これにより、ルールをコードベースの特定の部分に限定でき、エージェントが他の領域で作業する際に無関係なコンテキストを読み込むのを防ぐことができます。

主要な詳細

• 採用率: 人気のあるアクティブなプロジェクトの34%がエージェント指示ファイルを持っており、TypeScriptでは73%に上昇します。
• ファイルの長さ: 主要なファイルの中央値は106行で、52%が100行を超えています。
• 強制可能性: ルールの61%はスクリプトによって部分的または完全にチェック可能ですが、具体的なチェックを名指ししているのはわずか3.7%です。
• 冗長性: 約30のプロジェクトが、同一ではないAGENTS.mdとCLAUDE.mdファイルを個別に維持しています。
• 陳腐化: ファイルの2%のみが存在しなくなったパスやスクリプトを参照しています。
• コンテンツの焦点: コードスタイル、エージェントの挙動、プロジェクト固有の正確さが最も一般的なトピックであり、セキュリティとパフォーマンスは稀です。

なぜ重要なのか

エンジニアリングチームにとって、このデータは指示を書くことと、それが守られることを保証することの間のギャップを浮き彫りにしています。長い指示ファイルはトークンコストを増加させ、エージェントの集中力を希薄にする可能性があります。記事で引用されているチューリッヒ工科大学（ETH Zurich）の研究は、開発者が作成したファイルはわずかに役立つものの、エージェントのコストを最大19%増加させる可能性があることを指摘しています。ファイルを短く保ち、外部ドキュメントを参照する方が効率的です。

さらに重要なことに、重要なルールについてエージェントの記憶に頼るのはリスクがあります。ルールがそれを強制するメカニズム（特定のリンターやCIチェックなど）を名指しする場合、それは安全網を作成します。エージェントが忘れた場合でも、ツールがエラーを検出します。このリンクがない場合、チームはエージェントの一貫性に依存することになりますが、コンテキストウィンドウが埋まるにつれて一貫性は低下します。強制されていないルールの蔓延は、多くのチームがこれらのファイルを運用上の制約ではなく、願望リストとして扱っていることを示唆しています。

あなたができること

• ファイル長の監査: 詳細な説明をリンクされたドキュメントに移すことで、主要なAGENTS.mdを100行以下に抑えてください。
• チェックの名指し: すべてのルールについて、それを強制するリンター、テスト、またはスクリプト（例：「Sorbet/ForbidTMustによって強制」）を指定してください。
• パスの検証: 指示内で参照されているすべてのコマンドとファイルパスがまだ存在することを定期的に確認してください。
• ファイルの統合: 複数の指示ファイルを使用している場合は、二次ファイルがプライマリファイルを指すようにして、ルール間の競合を避けてください。
• 強制可能なルールの優先: 自動化できるルールに焦点を当て、エージェントの記憶だけに依存するルールは、重要でない限り削除してください。
• サブフォルダルールの使用: ルールを特定のディレクトリに配置することで、エージェントが無関係なコンテキストを読み込むのを防ぎます。