AGENTS.mdを正しく使う：正確性が25%向上するか、30%低下するか

Augment Codeは、モノレポ全体でAGENTS.mdファイルに関する体系的な調査を実施しました。最高のファイルは、コーディングエージェントの品質をHaikuからOpusへのアップグレードに相当するほど向上させましたが、最悪のものはAGENTS.mdがない場合よりも出力を悪化させました。同じファイルが、ルーチンのバグ修正ではbest_practicesを25%向上させた一方、同じモジュール内の複雑な機能タスクではcompletenessを30%低下させました。以下が効果的な方法です。

測定方法

内部評価スイートであるAuggieBenchを使用しました。大規模リポジトリから、日常的なエージェントタスクを反映した高品質のPRを選び、環境とプロンプトを設定し、エージェントにPRを再現させました。出力は、複数のシニアエンジニアによるレビューを経てマージされたゴールデンPRと比較しました。PRは単一のモジュールまたはアプリ内に収まり、AGENTS.mdが役立つ可能性がある範囲である必要がありました。各タスクはファイルありとなしの2回実行されました。

効果的な方法

1. 段階的開示 > 包括的なカバレッジ

一般的なケースやワークフローを高レベルでカバーし、詳細はエージェントが必要に応じてロードできる参照ファイルに押し込みます。各参照の範囲を明確にします。100〜150行のファイルと、焦点を絞った参照ドキュメントをいくつか用意することで、中規模モジュール（約100のコアファイル）でメトリクス全体で10〜15%の改善が見られました。それ以上の長さでは改善効果が逆転しました。

2. 手続き的ワークフロー

番号付きのマルチステップワークフローにより、エージェントが失敗から完了へと導かれます。例：新しいインテグレーションをデプロイするための6ステップのワークフロー。配線ファイルの欠落が40%から10%に減少し、エージェントの完了が速くなり、正確性が25%向上、完全性が20%向上しました。メインファイルは簡潔に保ち、分岐ケースには参照ファイルを使用します。

3. 決定表

2つまたは3つの合理的な方法がある場合（例：状態管理におけるReact Query vs Zustand）、決定表を使って事前に選択を強制します。例：

質問 → React Query → Zustand
サーバーが唯一のデータソース？ ✅
複数のコードパスがこの状態を変更する？ ✅
楽観的更新とローカル状態の混在が必要？ ✅

その領域のPRでは、best_practicesが25%向上しました。

4. 短いプロダクションの例

実際のプロダクションコードからの3〜10行のスニペットにより、再利用性とパターンの遵守が向上しました。例：Redux Toolkitのプリミティブ（型付き初期状態のcreateSlice、エラーハンドリング付きcreateAsyncThunk、型付きuseAppSelector）のコピペテンプレート。code_reuseが20%向上しました。

5. ドメイン固有ルール

これらは依然として重要です。多くの人がすでにAGENTS.mdと関連付けているパターンです。