AIコーディングエージェント（Claude Code、GitHub Copilot、Cursorなど）を日常的に使い始めたエンジニアは増えているが、「思ったより出力がよくない」と感じた経験はないだろうか。その原因の一つが、リポジトリに置くAGENTS.mdの品質にある。
Augment Codeが公開したベンチマークレポートでは、適切に書かれたAGENTS.mdがコーディングエージェントの出力を10〜15%改善すると報告されている。モデルをアップグレードしなくても、ドキュメントの書き方を見直すだけで実質的な改善が得られる可能性がある。
本記事では、その背景にある仕組みと、実際に効果が出やすいAGENTS.mdの書き方を整理する。
目次
[:contents]
AGENTS.mdとは（概要）
AGENTS.mdは、AIコーディングエージェントがリポジトリを操作する際の「行動指針」を記したMarkdownファイルだ。テスト実行のコマンド、コーディング規約、コミットメッセージのフォーマット、禁止事項といった情報を記述しておくと、エージェントはそれを参照しながら作業を進める。
AIコーディングエージェントの普及とともに慣習として広まったフォーマットで、現在はClaude Codeも類似の仕組みとしてCLAUDE.mdを採用している。ファイル名こそ違うが、「エージェントへの指示書」という役割は共通だ。
従来のREADMEとの違いは読み手にある。READMEは人間向けの概要説明が主な目的だが、AGENTS.mdはエージェントが実際に作業を行うときに参照することを前提に設計される。そのため、内容の粒度や構造の最適解が異なる。
なぜ品質が重要なのか
Augment Codeのベンチマーク結果の中で特に注目すべきは、品質の低いAGENTS.mdがない状態より悪い結果をもたらす可能性があることだ。「とりあえず書いておけばよい」という発想で作成したAGENTS.mdが、むしろエージェントの判断を歪める。
Augment Codeが報告した例では、80Kトークン規模の冗長なアーキテクチャドキュメントをエージェントに読み込ませたところ、タスク完了率が25%低下したとされている。エージェントはコンテキストウィンドウに収まる情報をもとに動作するため、不要な情報が多いとノイズとして機能してしまう。適切な情報密度の維持が、出力品質に直接つながる。
エージェントがドキュメントをどのように探すか
AGENTS.mdを書いても、エージェントがそれを参照しなければ意味がない。ドキュメントの置き場所による発見率の差は大きい。
| ドキュメントの置き場所 | 発見率 |
|---|---|
| AGENTS.md（リポジトリルート） | 100% |
| ネストされたREADME | 40% |
| サイドフォルダのドキュメント | ほぼ0% |
(出典: Augment Code ベンチマーク)
エージェントはリポジトリルートにあるAGENTS.mdをほぼ確実に参照するのに対し、深い階層に置かれたドキュメントはほとんど読まれない。ネストされたREADMEでも発見率は40%にとどまる。
いくら詳しい内容を書いていても、置く場所が悪ければ読まれない。プロジェクトの重要なルールはAGENTS.mdに集約し、リポジトリルートに置くことが基本だ。
効果的なAGENTS.mdの書き方
Augment Codeのベンチマーク結果をもとに、効果的な書き方を解説する。
150行以内に収める
長いドキュメントはトークン負荷を増やし、エージェントの処理精度を下げる。150行以内を目安に、本当に必要な情報だけを残す。アーキテクチャの詳細説明や背景説明は削除対象の筆頭だ。
「書くべきことがたくさんある」と感じるときは、エージェントが実際に意思決定を迫られる場面を想定して絞り込む。「どのコマンドを使うか」「どのフォーマットで書くか」「何をしてはいけないか」という問いに答えられる情報に限定すると、自然に短くなる。
番号付きワークフローを使う
散文（長い文章の段落）ではなく、番号付きのステップで手順を記述すると、エージェントは各ステップを正確にトレースしやすくなる。
散文形式では意図が曖昧になりやすい。
テストを実行する前に依存関係を確認し、環境変数が設定済みであることを確かめてから実行してください。
番号付きワークフロー形式なら、エージェントが各ステップを確実に実行できる。
1. `npm install` で依存関係を更新する
2. `.env.test` に必要な環境変数を設定する
3. `npm test` でテストを実行する
禁止事項には代替案を対にする
「〜をするな」という指示だけでは、エージェントが代替手段を持てず判断が止まることがある。禁止する際は必ず「代わりに何をすべきか」をセットで記載する。
具体例で比較してみよう。
# 禁止のみ（曖昧）
直接DBにSQLを実行しないこと
# 代替案つき（明確）
直接DBにSQLを実行しないこと
→ 代わりに src/db/queries/ 配下のクエリ関数を使う
禁止と代替の対応関係を明示することで、エージェントは正しい実装パスに進める。
複数の選択肢がある場合は決定テーブルを使う
「状況によってやり方が変わる」ケースでは、条件分岐を文章で書くと読みにくくなりがちだ。決定テーブルを使うと、エージェントは条件に応じた正しい選択肢を素早く参照できる。
| 条件 | 採用するアプローチ |
|--------------------|--------------------------|
| 新規APIエンドポイント | OpenAPIスキーマから生成 |
| 既存エンドポイントの修正 | 既存コードを直接編集 |
| バグ修正 | テストを先に書いてから修正 |
表形式にすることで情報密度が上がり、散文で書くよりトークンを節約できる利点もある。
AGENTS.mdとCLAUDE.mdの関係
Claude Codeを使っている場合、CLAUDE.mdが同等の役割を担う。ファイル名がツールによって異なるものの、「エージェントが作業開始時に参照する指示書」という役割は共通だ。そのため、ここで紹介した書き方のポリシーはそのままCLAUDE.mdにも適用できる。
サブディレクトリにAGENTS.mdを置くことで、特定のモジュールやサービスに対してスコープを絞った指示を与えることも可能だ。ただし、発見率のデータからも分かるとおり、ルートのAGENTS.mdが最も確実に参照される。サブディレクトリへの配置は補助的な役割と捉えるのが適切だ。
エンジニアリングスキルとしてのエージェント向けドキュメント作成
Claude Code、GitHub Copilot、Cursorなどがリポジトリレベルの指示への依存を強めるにつれ、エージェント向けのドキュメント作成は新しいエンジニアリングスキルとして位置づけられつつある。
従来のコードレビューやCIの設定と同様に、「エージェントが正しく動くための環境整備」という視点が重要になる。チームでAIコーディングツールを活用するなら、AGENTS.mdの品質管理をコードベースのメンテナンスと同列に扱うことが、アウトプット品質の安定化につながる。
ドキュメントを一度書いたら終わりではなく、コードの変更に合わせて内容を定期的に更新することが、長期的な効果を維持する鍵になる。新規メンバーのオンボーディング時や大きなリファクタリングの節目が、AGENTS.mdを見直す自然なタイミングだ。
まとめ
Augment Codeのベンチマークが示しているのは、AGENTS.mdの品質がエージェント出力に直接影響するという点だ。10〜15%という改善幅はドキュメントの整備だけで得られる実質的な効果であり、投資対効果は高い。
効果的なAGENTS.mdを作るうえで押さえておきたいポイントは次のとおりだ。
- 150行以内に絞り、情報密度を保つ
- 手順は番号付きワークフローで記述する
- 禁止事項には必ず代替案をセットで示す
- 選択肢が複数ある場合は決定テーブルを活用する
- ファイルはリポジトリルートに置く（発見率100%）
品質の低いAGENTS.mdはむしろ逆効果になる可能性があることも念頭に置き、定期的に内容を見直す習慣をつけると長期的な効果が期待できる。AIコーディングエージェントを本格的に活用するチームにとって、エージェント向けドキュメントの整備は今後ますます重要な実践になるだろう。
既存リポジトリへの導入を検討するなら、まず現在のREADMEやwikiからエージェントが実際に参照すべき情報（テスト手順・コーディング規約・禁止事項）を抜き出し、150行以内の構造化ドキュメントとして書き直すのが現実的な第一歩だ。チームで運用する場合は、コードと同様にAGENTS.mdの変更もプルリクエスト経由でレビューする仕組みを設けることで、品質の劣化を継続的に防ぎやすくなる。
モデルのアップグレードを待つより、ドキュメントの整備から始める方が即効性は高い。自分のリポジトリのAGENTS.mdを今一度見直してみることが、改善への最短ルートだ。