AIに渡す「説明書」が長すぎると混乱する
AIコーディングエージェントを使っていると、プロジェクトの構造や方針を説明するためにAGENTS.mdやREADME.mdといったファイルを用意することがあります。特に最近は、Cursor AIやGitHub Copilot Workspaceのように、リポジトリ全体のコンテキストを読み込んでコードを生成するツールが増えています。
ETHチューリッヒの研究チームは、こうしたコンテキストファイルが本当にAIの性能を向上させるのか、138のタスクと5694件のプルリクエストを元にしたAGENTBENCHとSWE-bench Liteというベンチマークで検証しました。対象となったのは、Claude Sonnet-4.5、GPT-5.2、Qwen3-30Bなど、実務でよく使われるモデルです。
結果は予想外でした。LLMが自動生成したAGENTS.mdファイルを使うと、タスクの成功率が平均で2〜3%低下し、推論コストは20%以上増加したのです。つまり、AIに詳しい説明を与えようとして自動生成ツールを使うと、かえって精度が下がり、API利用料も高くなってしまうわけです。
人間が書いても大幅改善は難しい
それなら人間が丁寧に書けば良いのでは、と思いますよね。研究チームは人間が作成したコンテキストファイルも評価しました。こちらは平均4%の性能向上が見られたものの、一貫性がなく、一部のモデルではむしろ悪化するケースもありました。
特に問題だったのは、詳細すぎるコードベースの概要やディレクトリの一覧です。こうした情報は一見親切に見えますが、AIにとってはノイズになってしまいます。しかも、情報が古いとさらに性能が落ちる傾向がありました。
研究チームは、AIエージェントが指示に過度に従順で、不要な詳細情報に引っ張られてタスクが複雑化してしまうと分析しています。例えば、単純なバグ修正なのに、説明書に書かれた設計方針を律儀に全部守ろうとして、余計なコードを書いてしまうイメージです。
効果的なのは「必要最小限」の人間記述
では、どうすれば良いのでしょうか。研究の結論は「必要最小限の人間による記述」でした。プロジェクトの核心部分だけをシンプルに書いたファイルなら、4%程度の向上が見込めます。
さらに興味深いのは、Arize AIなどが提案する「自動最適化ループ」の手法です。これはAIの出力を評価しながらコンテキストファイルを段階的に改善していく方法で、5〜11%の性能向上が報告されています。つまり、一度書いて終わりではなく、実際の成果を見ながら調整していくアプローチが有効だということです。
具体的には、例えばTypeScriptのバックエンドプロジェクトなら、「認証にJWTを使用」「データベースはPrisma経由でPostgreSQL」といった技術選択と、「/api/v1以下がエンドポイント」程度の構造情報があれば十分です。各ファイルの詳細説明やディレクトリツリーの全容は不要ということです。
今すぐ見直せる3つのポイント
この研究結果を踏まえると、自分のリポジトリで見直すべきポイントが見えてきます。まず、LLMの自動生成機能で作ったAGENTS.mdやREADME.mdがあるなら、思い切って削除するか大幅に削ってみる価値があります。特にCursor AIの/initコマンドで生成したファイルは要注意です。
次に、自分で書いた説明ファイルがある場合、情報が古くなっていないか確認してください。3ヶ月前の構造説明が残っていると、AIが古いアーキテクチャに引きずられる可能性があります。
最後に、コンテキストファイルは「このプロジェクトで絶対に知っておくべきこと」だけに絞り込みましょう。技術スタック、認証方式、API設計の基本方針など、コアな情報を3〜5項目程度にまとめるイメージです。
フリーランスエンジニアへの影響
この発見は、AIコーディングツールを日常的に使うフリーランスエンジニアにとって、コスト面でも時間面でも重要です。推論コストが20%増えるということは、月額のAPI利用料がその分高くなるということです。月5万円使っているなら、1万円の無駄が出ている計算になります。
また、成功率が2〜3%下がるということは、AIが生成したコードの修正作業が増えるということです。10回に1回余計にデバッグが必要になると考えると、時間のロスも無視できません。特に納期が厳しい案件では、この差が響いてきます。
逆に言えば、コンテキストファイルを最適化するだけで、追加投資なしで精度が上がりコストが下がる可能性があるわけです。新しいツールを導入するよりも、今使っているツールの使い方を見直す方が効果的かもしれません。
特に恩恵を受けるのは、複数のクライアント案件を並行して進めているフリーランスや、リポジトリの数が多いエンジニアです。各プロジェクトのコンテキストファイルを整理するだけで、全体の作業効率が底上げされます。
まとめ：まずは既存ファイルの見直しから
ETHチューリッヒの研究は、「親切すぎる説明」がAIの足を引っ張ることを科学的に証明しました。すぐに試せるアクションとしては、自分のリポジトリにあるAGENTS.mdやREADME.mdを開いて、本当に必要な情報だけに削ることです。特にLLMが自動生成したファイルは、一度削除してみて性能がどう変わるか確かめる価値があります。
新しい案件を始めるときも、詳細な説明書を作り込むのではなく、技術選択と基本方針だけをシンプルに記述するスタイルに切り替えてみてください。AIが混乱しなければ、あなたの作業時間も減り、コストも下がります。
研究の詳細は、MarkTechPostの記事で確認できます。
コメント