核心的な主張
- AIコーディングエージェント向けのコンテキストファイル（AGENTS.md）を**
/initコマンドで自動生成すると、エージェントの性能はむしろ低下し、コストは20%以上**増加する
- エージェントが自力で発見できる情報を重複して与えてしまうことが、問題の核心
- AGENTS.mdにはエージェントがコードを読んでも分からない情報だけを入れるべき
研究結果: AGENTS.mdは役に立つのか、それとも害になるのか
- Lulla et al. (ICSE JAWs 2026): GitHub PR 124件を対象に、AGENTS.mdの有無だけを変えて比較するペア実験
- AGENTS.mdがあると、実行時間は28.64%減少、出力トークンは16.58%減少
- この研究で使われたファイルは、開発者が実際に保守していたもので、プロジェクト固有の知識が含まれていた
- ETH Zurichの研究: 4つのエージェントをSWE-benchなどでテストし、LLM自動生成ファイルと開発者作成ファイルを区別
- LLMが自動生成したコンテキスト: タスク成功率は2〜3%低下し、コストは20%+増加
- READMEなど既存ドキュメントをすべて除去した環境では、LLM生成ファイルがむしろ性能を2.7%向上させた
- 開発者が直接書いたファイル: 成功率は約4%向上し、コストは最大19%増加
- 結論: 自動生成の内容そのものが悪いのではなく、重複が問題
- 同じ情報を2回与えるとノイズが増えるだけで、開発者が書いた発見不可能な知識だけが実質的に役立つ
なぜ自動生成が有害なのか
- 自動生成されたAGENTS.mdの大半は、エージェントがすでに自力で見つけられる情報を含んでいる
- コードベース概要（Sonnet 4.5の出力の100%、GPT-5.2の出力の99%がこれを含む）
- ディレクトリ構造、技術スタック、モジュール説明
- すでに分かっている情報を再び与えても、トークンを消費するだけで価値がない
- アンカリング効果: レガシーパターンに言及すると、より良い代替案があってもエージェントがそのパターンに固定される
- 「Lost in the Middle」の研究（Liu et al., 2024）とも一致 — 長いコンテキストは注意を分散させ、性能を落とす
AGENTS.mdに入れるべきこと vs 入れてはいけないこと
- 入れるべきこと（エージェントが発見できない情報）
- ツール指定: 「パッケージ管理には
uvを使うこと」
- 非直感的なルール: 「テストは必ず
--no-cacheで実行すること。そうしないとfixtureでfalse positiveが出る」
- システム制約: 「authモジュールではカスタムミドルウェアを使っているため、標準のExpressへリファクタリングしてはいけない」
- ツールがドキュメントに記載されていると、エージェントはタスクあたり1.6〜2.5回使用するが、文書化されていない場合は0.05回未満まで急減する
- 入れてはいけないこと（エージェントが自力で発見可能）
- ディレクトリ構造、モノレポのレイアウト
- 技術スタックの概要、標準的なアーキテクチャパターン
静的ファイルの構造的限界
- よく書かれたAGENTS.mdであっても根本的な弱点がある — ファイルは静的だが、タスクは動的だから
- 単一ファイルの指示は、タスクの種類に応じた条件分岐ができない
- ドキュメント修正タスクにも「コミット前に全テストを実行」という指示が適用され、トークンと時間が無駄になる
- CSSリファクタリングでDBマイグレーション警告が読み込まれ、セキュリティ修正では性能最適化のヒントまで付いてくる
- ACEフレームワーク（ICLR 2026）: 静的ファイルの代わりにgenerator/reflector/curatorパイプラインでコンテキストを動的に進化させるAgentic Context Engineeringの手法が、静的方法より**12.3%**高い性能を記録
より良い構造、まだ作られていないもの
- AGENTS.mdについて、複数の人が独立に同じ結論へ到達している
- 単一ファイルではなく、ルーティング層 + 必要時にロードされる集中的なコンテキストが正しい構造
- Layer 1 - プロトコルファイル: コードベース概要やスタイルガイドではなく、ルーティング文書
- 利用可能なペルソナと呼び出し条件、スキルと担当タスク種別、MCP接続とその用途を定義する
- エージェントが発見できない最小限のレポジトリ情報だけを含め、それ以外は何も入れない
- Layer 2 - ペルソナ/スキルファイル: タスク種別に応じて選択的にロードされる
- UXエージェントとバックエンドエージェントは異なるコンテキストを読み込み、相手側のコンテキストは読み込まない
- Layer 3 - 保守サブエージェント: プロトコルファイルの正確性を維持する専任エージェント
- 文書は劣化する — ETH Zurichの研究でも、生成直後のファイルを使ってなお性能低下が見られた
- 6か月放置されたAGENTS.mdが、すでに置き換えられた依存関係や変更済みのディレクトリ構造を記述しているなら、さらに深刻
- 現在の主要なコーディングエージェントで、このアーキテクチャを簡単に実装できるライフサイクルフックを提供しているものはない — サブエージェントやスコープ付きコンテキストで近似はできるが、まだ埋まっていないツール上の空白である
自動最適化
- Arize AIはCLAUDE.mdの指示文を手作業で書く代わりに、自動最適化ループを使っている
- エージェントを学習用タスクで実行 → 結果を評価 → 失敗原因についてLLMフィードバックを生成 → メタプロンプティングで指示文を改善 → 反復
- cross-repoテストで**+5.19%、in-repoテストで+10.87%**精度が向上
- オプティマイザが明らかにした不都合な事実: 人がコードベースを理解するのに役立つものと、LLMが探索に必要とするものは異なる
- 「このサービスはrepositoryパターンを使っている」といった情報は、開発者には当然有用に見えても、モデルにとってはノイズかもしれない
- 逆に、モデルが実際に必要とするもの（特定のimportパスの区別、非直感的なファイル命名規則など）は、開発者が内面化していて、そもそも書こうとすら思わない
- AGENTS.mdを手で書くことは、開発者がエージェントに必要なものを分かっていると仮定している
- 実証的な証拠は、おそらくそうではないことを示している
- オプティマイザは「重要だと思っていること」と「実際に結果を変えること」の差を見つけ出す
- だからといって作成をやめろという意味ではない — 5%は意味があるが、変革的ではない。直感を緩く持ち、実際にテストせよという意味だ
AGENTS.mdを見る正しいマインドセット
- AGENTS.mdはまだ修正できていないプロセスの記録として捉えるべき
- 追加するすべての行は、コードベースにAIエージェントを混乱させるほど曖昧な部分があるというシグナルであり、新しい人間のコントリビューターも同様に迷う可能性が高いことを示す
- 正しい対応はコンテキストファイルを大きくすることではなく、根本原因を修正すること
- エージェントがユーティリティを見当違いのディレクトリに置く → ディレクトリ構造そのものが分かりにくいので再編する
- エージェントが廃止された依存関係を使い続ける → import構造が誤ったものをあまりに簡単に拾えてしまうので修正する
- エージェントが型チェックを見落とす → 指示に頼らず、ビルドパイプラインで自動的に検出する
- AGENTS.mdは恒久設定ではなく診断ツールである — 行を追加し、なぜエージェントがこのミスを繰り返すのかを調査し、根本原因を直したら、その行を削除する
- 試してみる価値のある手法: AGENTS.mdをほぼ空にした状態で始め、「このプロジェクトで驚いたこと、または混乱したことを見つけたらコメントで残してほしい」という指示を1つだけ入れる。エージェントが提案する追加事項の大半は、恒久保存すべきものではなく、コードベースが不明瞭な箇所の標識である
実用的な推奨事項
/initの実行をやめること — レポジトリに文書がまったくない場合でない限り、自動生成された成果物は既存文書と重複する- AGENTS.mdに1行追加する前に、「エージェントはコードを読めば分かるか？」と自問すること。分かるなら書かない
- エージェントが繰り返し失敗する場合、コンテキストファイルを増やす前にまずコードベース自体を修正すること
- コード構造を改善し、リンタールールを追加し、テストカバレッジを広げたうえで — それでもだめなときだけAGENTS.mdを触る
- CI/CDや自動レビューのパイプラインでエージェントを大規模運用するなら、15〜20%のコストオーバーヘッドが数千回の実行を通じて複利的に積み上がることを認識すべき
- エージェントを新入社員のようにオンボーディングしたくなる本能（オフィスツアー、組織図、アーキテクチャ説明）は自然だが、コーディングエージェントは新入社員ではない — プロンプトを打ち終える前にコードベース全体をgrepできる。エージェントに必要なのは地図ではなく、地雷の位置だ
9件のコメント
結局はコンテキストの勝負だという話もありましたが…
agent向けのmdとユーザー向けのmdは別々に作るようにしたほうがいいのでは、と思います。
全面的に同意します。人間が読みやすい構造（README）と、LLMが解析しやすい構造（AGENTS.md）はまったく別物ですからね。全体のコンテキストをやみくもに自動生成して渡すと、APIトークンのコストを無駄にするだけでなく、かえってハルシネーションがひどくなることをよく経験しました。結局、面倒でもエージェント向けの指示書は人が直接圧縮して整理するのが、いちばん効率的だと思います。
太初にREADMEがあり、エージェントのためのREADMEとして作られたのがAGENTS.mdなのですから。
でも、それならすでにREADMEがあるのではないですか？
でも、モデル自体が数カ月で変わってしまうし、
モデルに合わせて agents を修正しなければならないのに……。
適切な agents の構造を作る時間より、モデルの変化のほうが速いのではないでしょうか。
人がツールに慣れる前に、そのツールのほうが変わってしまうわけですから……
結局のところ、context を pure に、かつ少ないトークンで維持するのが重要な気がしますが……そういう観点では漢字がかなり有用なんじゃないかと思ったりもします。笑
モデルにとって英語はすでにほぼ1単語が1文字（トークン）みたいなもので、実質的に漢字みたいなものではありませんか
おお、こういうアプローチは思いつきませんでしたが、一理ある気がします！
おお..