本記事の概要と検証背景
AGENTS.md の書き方の議論は、経験則が中心になりがちな気がする。
- 「長く書くと重要な指示が希釈されるから、短く保つべき」
- 「上位モデルなら勝手にコードベースを理解するから、ほとんど書かなくていい」
- 「禁止事項は明記しておけば守られる」
このような話を耳にしたとき、「確かにそうっぽいけど、根拠はなんだろう？」と思っていた。
果たしてこれらは、いつ/どのようなリポジトリで/何のモデルをどのように使用した場合の話なのか？今の私のプロジェクトにおいてもそのまま当てはまるのか？
私の手元には617行に育った本番リポジトリの AGENTS.md がある。いくらなんでも文字数が多すぎる。記載内容が効いているのかも害をなしているのかもよくわからない。
「じゃあ何を削るべきか？ 何を残すべきか？」
これを判断する材料集めのために、まずはClaudeの公式ドキュメントや各種個人ブログなどをもとに、推奨構成とされる要素を洗い出し、推奨構成の骨子（仮説）を取りまとめた。……①
そして洗い出した要素をAGENTS.mdに記載した場合/しなかった場合での挙動差を、テストベッドにて実際に検証することにした。……②
本記事には①の結果として、AGENTS.md の推奨構成(2026/07/03仮案) を記載する。②の検証結果は次回記事にまとめる。
[追記] ②の記事は以下
推奨骨子案
# AGENTS.md
## プロジェクト概要(3〜5 行: 何のプロダクトか)
## アーキテクチャ・ディレクトリ構成の要約
## セットアップ・コマンド
## タスク管理、仕様の参照先(Source of Truth のルーティング)
## 規約(リンターで強制できないもの)
## 暗黙のルールと禁止事項(なぜ付き)
## 落とし穴
## Definition of Done
Claude Code は AGENTS.md を直接読まない
Claude Code が自動読み込みするのは CLAUDE.md であり、AGENTS.md のネイティブサポートはない(2026年7月時点)。CLAUDE.md に @AGENTS.md と 1 行書いてインポートするか、symlink を張るのが定番の回避策。
参照：Claude があなたのプロジェクトを記憶する方法 - Claude Code Docs
記載すべき内容について
各項目の必要性は、以下 3 つの視点で判断できる。
- (1) 非存在情報……コードのどこにも存在しない情報である
- (2) 探索コスト……自力で到達可能だが、探索・原因究明のコストが高い
- (3) 誤りコスト……誤推測したときの被害が大きい
骨子案の 8 項目と 3 基準の対応は以下のとおり。
| 項目 | (1) 非存在情報 | (2) 探索コスト | (3) 誤りコスト |
|---|---|---|---|
| 1. プロジェクト概要 | − | − | −(※) |
| 2. アーキテクチャ・ディレクトリ構成の要約 | − | ✓ | − |
| 3. セットアップ・コマンド | ✓ | ✓ | ✓ |
| 4. タスク管理、仕様の参照先 | ✓ | − | ✓ |
| 5. 規約(リンターで強制できないもの) | ✓ | − | ✓ |
| 6. 暗黙のルールと禁止事項 | ✓ | − | ✓ |
| 7. 落とし穴 | ✓ | ✓ | ✓ |
| 8. Definition of Done | ✓ | − | ✓ |
※ プロジェクト概要のみ、この 3 基準では正当化できない例外的な項目である(理由は本文で述べる)。
1. プロジェクト概要(3〜5 行)
※必要性基準……なし(後述)
何のプロダクトで、誰が使い、何を最も大事にするか。
「医療機関向け予約管理 SaaS。監査ログと後方互換性を最優先」程度の粒度で十分。
なぜ必要か？
実はこの項目だけ、(1)〜(3) の基準では正当化できない。README を読めば概ね分かるし、無くても即座に事故は起きない。
それでも冒頭に置くのは、概要が単体で効く情報ではなく、以降のすべての指示の解釈精度を上げる前提コンテキストだから。エージェントは実装中に無数の小さなトレードオフ(互換性か速度か、エラーを落とすか握るか)を判断しており、その判断基準はプロダクトの性質に依存する。「社内プロトタイプ」と「決済基盤」では、同じ指示でも正しい判断が変わる。
README がある場合も、あれは人間の新規ユーザー向けの文書であり、「このリポジトリで何を優先すべきか」に 3 行で答えるとは限らない。3〜5 行という上限を守る限り、維持コストもコンテキスト圧迫リスクも無視できる。
2. アーキテクチャ・ディレクトリ構成の要約(短く)
※必要性基準……(2)
主要ディレクトリの役割を数行で。
「認証は src/auth/、ビジネスロジックは src/services/、UI コンポーネントは共有パッケージから import」程度。
エージェントの探索時間を減らすための地図の役割。
なぜ必要か？
エージェントの探索は本質的に検索とファイル読みの繰り返しで、コンテキストウィンドウを消費する。
大きなリポジトリで「認証処理はどこか」を自力で探すと、grep して候補を数ファイル読んで…と数千〜数万トークンかかる。AGENTS.md に地図が 5 行あれば 1 ホップで正解に着く。
またコンテキストが探索ログで埋まると、本来のタスクに使える「思考の余白」が減り、出力品質自体が下がる。
詳細な地図は維持コストと陳腐化リスクがリターンを上回るため、なるべく簡潔に短く、ざっくりとした構成が掴める内容であればOK。
3. セットアップ・コマンド
※必要性基準……(1)、(2)、(3)
ビルド、テスト、リント、型チェックの正確なコマンド。
特に npm test ではなく pnpm test --filter=web のようにモノレポやカスタム設定がある場合は必須。
単一テストの実行方法(pytest tests/test_foo.py::test_bar -x など)も書いておくと、エージェントが全テストを毎回回さなくなる。
なぜ必要か？
エージェントはステートレスで、毎セッション探索をやり直す
人間なら一度覚えれば済むが、エージェントは新しいセッションのたびに package.json を開き、scripts を眺め、どれが正解か推測するところから始める。
AGENTS.md は起動時に自動でコンテキストに入るので、この探索コスト(時間とトークン)を毎回ゼロにできる。
package.json は「何があるか」は示すが「どれを使うべきか」は示さない
実際のリポジトリでは、package.json の scripts に test, test:unit, test:e2e, test:ci, test:watch などと並んでいることが多い。
ある程度意味役割は推測できるものの、変更後の検証にどれを走らせるのが正解か、test:e2e はローカルで動くのか……まで詳細に読み取ることは難しく、AIエージェントが不適切なコマンドを実行しかねない。
推測を間違えたときのコストが高い
人間は yarn test が失敗したら、lockファイルを確認して「あ、yarn じゃなくて pnpm だったか」と切り替えることができる。経験則的な動きである。
一方、エージェントは失敗の原因究明に脱線したり、最悪の場合 package.json を「直そう」としたりする。
4. タスク管理、仕様の参照先(Source of Truth のルーティング)
※必要性基準……(1)、(3)
Backlog や Asana、Notion など、外部ツールでタスクや仕様書を管理している場合、必要に応じてそれらの内容をエージェントが参照できるようにする。
エージェントが情報を読みに行く際の判断軸になるように、それぞれのツールで何を管理しているのかも明記する。
記載ポイント
- 情報の正本(Source of Truth)がどこか: 「タスクの仕様や受け入れ条件は Backlog のチケットが正。リポジトリ内の TODO コメントや docs 配下のメモは古い可能性があるので信用しない」
- いつ参照すべきか: 「実装に着手する前に、必ず対応する Backlog チケットを取得して受け入れ条件を確認する」
- 書き込み側の運用ルール: 「作業完了時にチケットのステータスを変えるのは人間。エージェントはコメント追加まで」「課題の起票は必ず ○○ プロジェクトに」
- ツール間の優先順位: 「進捗は Asana、技術的な議論の経緯は GitHub の PR、両方ある場合は Asana を優先」
なぜ必要か？
タスクや仕様書の在処は「コードに書かれていない」情報だ。どこで管理しているかが分かれば、エージェントは MCP サーバーなどを介して情報を取得できる。
逆にこの情報に辿り着けないと、期待の受け入れ条件に合致しないアウトプットを生成しかねない。
5. コーディング規約のうちリンターで強制できないもの
※必要性基準……(1)、(3)
「エラーは握りつぶさず上に投げる」「新規コードはこのパターンに従う(既存の ○○ を参考に)」など。
フォーマットはリンターに任せ、ここには書かない。
なぜ必要か？
これも「コードに書かれていない判断基準」。ただし補足すると、既存コードから帰納的に学べる規約(命名パターンなど)はエージェントもある程度模倣する。
問題は、リポジトリ内に新旧のパターンが混在している場合。エージェントはどちらが「現在の正」か分からず、たまたま最初に読んだ古い方を真似る。
「新規コードは src/services/user.ts のパターンに従う」などの記載があるだけで、エージェントは従うべき記法を把握できる。
6. 暗黙のルールと禁止事項(なぜ付き)
※必要性基準……(1)、(3)
コードを読んでも分からない制約。
「このディレクトリは自動生成なので編集禁止」「DB マイグレーションは必ず ○○ 経由で作る」「この古い API は互換性のため残しているが新規利用禁止」など。
禁止事項には理由を一言添えると、エージェントが例外判断を誤りにくくなる。
なぜ必要か？
これは純粋にコードのどこにも存在しない情報だから。
例えば、自動生成のファイルだけを見ても「このファイルは自動生成」という事実が読み取れないケースがある。するとエージェントは生成物を直接編集してしまう。そして生成トリガーが発火したタイミングで変更が消え、エージェントは再度生成物を編集してしまう。……こういった失敗ループが発生しかねない。
編集禁止の理由を添えるのは、エージェントが「今回は例外的に触っていいか」を判断する材料になるためだ。理由なしの禁止は、エッジケースで誤った例外判断を招く。
7. よくある落とし穴
※必要性基準……(1)、(2)、(3)
「このテストは Docker が必要」「環境変数 X がないと起動時に分かりにくいエラーが出る」など、エージェントがハマって時間を溶かしがちな点。
なぜ必要か？
理由はセットアップ・コマンドの節と同じ構造で、失敗の原因究明はエージェントが最も時間とトークンを浪費するフェーズだから。「このテストは Docker 必須」を知らないエージェントは、接続エラーを見てコード側のバグを疑い、正常なコードを「修正」し始めることさえある。
8. Definition of Done
※必要性基準……(1)、(3)
「変更後は必ず make check を通す」「型エラーゼロを維持」など、完了の定義。エージェントは検証手段があると自己修正ループが回せる。
なぜ必要か？
エージェントの強みは「書く → 検証 → 失敗を見て直す」の自己修正ループだが、ループを回すには合否判定の手段が明示されている必要がある。これがないと、エージェントはコードを書いた時点で「完了しました」と宣言しがちだ。しかしよく見ると型チェックもテストも通していない。「型チェック通して」などと人間が再度指示を出さないといけなくなる。
「make check が通るまで完了ではない」と書くだけで、AIエージェントは自律的にループを回すようになる。
記載しなくて良い(むしろ書かない方がいい)内容
a. コードを読めば分かること
関数の一覧、詳細なファイル構成、依存パッケージのリスト。エージェントは自分で読めるし、すぐ陳腐化してドキュメントと実態の乖離が起きる。
b. 一般的なベストプラクティス
「クリーンなコードを書く」「テストを書く」「セキュリティに注意」のような指示。モデルは既に知っており、トークンを消費するだけでシグナルが薄まる。
c. リンター/フォーマッターで機械的に強制できるルール
インデント、import 順、命名規則など。ツールに強制させて、AGENTS.md からは省く。「規約は ESLint 設定を参照」の一行で十分。
d. 変化の速い情報
プロジェクトのフェーズやマイルストーン、現在のタスク状況、TODO、担当者、スプリント情報などなど。これらは issue トラッカーの領分で、AGENTS.md に書くと確実に腐る。
e. 長大なドキュメントの全文
詳細が必要なら別ファイルに切り出し、「デプロイ手順の詳細は docs/deploy.md を参照」とリンクする形にする。エージェントは必要時にだけ読みに行ける。
f. 機密情報
多くのエージェントでは、AGENTS.md は、毎セッション全文が LLM プロバイダの API に送信され、かつリポジトリにコミットされる。
個人用や機密の設定はコミットしない別ファイル(例: .gitignore 済みのローカル設定)に分けるのが安全。
運用のコツ
サイズは短く保つ
目安として数百行以内、理想は 100 行前後、長くなるほど個々の指示が守られなくなる(コンテキストの希釈)——と言われている。
実際、Claude公式ドキュメントにも以下のように書かれている。
サイズ: CLAUDE.md ファイルあたり 200 行以下を目標にします。より長いファイルはより多くのコンテキストを消費し、遵守を減らします。
（https://code.claude.com/docs/ja/memory#write-effective-instructions ）
ただし、これ自体まさに冒頭で挙げた「根拠の不明な経験則」とも言える。何行から劣化するのか、どの種類の指示から守られなくなるのかは、②の検証対象とする。
失敗駆動で育てる
エージェントが同じミスを繰り返したときに一行追加する、という「失敗駆動」で育てるのが実践的で、逆に一度も効いていない記述は定期的に削除する。
※チーム開発における運用方法は要検討
階層構成も検討する
モノレポではルートに共通事項、各パッケージ配下にサブの AGENTS.md を置く階層構成も有効。
多くのエージェントはファイルツリーを上に辿って複数の AGENTS.md を読み込み、より近い(深い)ファイルが優先される。作業対象のファイルに最も近い AGENTS.md が、より上位のものを上書き・補完する形になる。
階層が送信・マージされる正確な挙動は、Claude や Copilot などエージェント実装ごとに異なる。「上位も含めて全部読む」ものもあれば「最も近い 1 つだけ」を使うものもあるため、使っているツールの仕様を随時確認しておく方が安全。
小〜中規模ならルート 1 ファイルから始め、必要になった時点で分割するのが無難で確実。
使い分け例
- ルートの AGENTS.md …… リポジトリ全体で共通する事項を置く。モノレポ全体のディレクトリ構成、共通のコーディング規約、コミットメッセージ規則、全体のビルド／テストの流れなど。
- 各パッケージ配下の AGENTS.md …… そのパッケージ固有の事項を置く。使用言語やフレームワーク、そのパッケージ特有のビルド・テストコマンド、依存関係、ローカルな慣習など。
おわりに
本記事では、AGENTS.md に書くべき内容を「(1) 非存在情報」「(2) 探索コスト」「(3) 誤りコスト」の 3 基準で整理し、8 項目の推奨骨子案としてまとめた。
ただし、これはあくまで文献調査(①)に基づく仮案だ。各要素が実際にエージェントの挙動を変えるのか、変えるとしてどの程度なのかは、まだ何も確認できていない。次回はテストベッド上での検証(②)として、特に以下の仮説を確かめる。
- AGENTS.md の記載の有無によって、エージェントのパフォーマンスは変わるのか
- AGENTS.md の最適な記載粒度にモデル差はあるのか
- AGENTS.md が長くなるほど、個々の指示は本当に守られなくなるのか。何行あたりが分岐点か
- 禁止事項は明記すれば守られるのか