コーディングAIへの指示ファイル、実は逆効果という研究結果

何が明らかになったのか
1. 実験内容と結果
なぜこんなことが起きるのか
フリーランスエンジニアへの影響
1. どんな人に特に関係があるか
今後どうすればいいのか
まとめ

何が明らかになったのか

arXivという学術論文サイトに、コーディングAIの使い方に関する興味深い研究結果が公開されました。タイトルは「Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?」。直訳すると「AGENTS.mdを評価する：リポジトリレベルのコンテキストファイルはコーディングエージェントに役立つのか？」です。

研究チームは、CursorやGitHub Copilotのようなコーディング支援AIに対して、プロジェクトの構造や方針を説明した文書ファイルを与えると、作業の質がどう変わるかを調べました。結果は予想外のものでした。

実験内容と結果

実験では、実際のソフトウェア開発タスクを使って、複数のAIエージェントとLLM（大規模言語モデル）をテストしています。一つは「SWE-bench」という、実在するGitHubプロジェクトの課題を解決させるベンチマークです。もう一つは、実際の開発者が作成したコンテキストファイルを使った課題です。

驚くべきことに、コンテキストファイルを与えた場合、与えなかった場合に比べてタスクの成功率が低下しました。さらに悪いことに、AIが使用するトークン数（処理する文字数のようなもの）が増えるため、推論コストが20%以上も増加してしまいました。

たとえば、あるプロジェクトで「このフォルダ構造を守ってください」「テストはこの形式で書いてください」といった詳しい指示を書いたファイルを用意したとします。すると、AIはその指示に忠実に従おうとして、必要のないファイルまで探索したり、本来シンプルに解決できる問題を複雑にしてしまうのです。

なぜこんなことが起きるのか

研究者たちは、その原因を分析しています。一つ目の理由は、コンテキストファイルに書かれた情報が、AIに「広範な探索」をさせてしまうことです。AIは指示に忠実なので、ファイルに「プロジェクト全体の構造を理解してください」と書いてあれば、関係のないファイルまで読み込もうとします。

二つ目の理由は、不要な要件が追加されてしまうことです。たとえば、開発者が「将来的にはこうしたい」という理想を書いてしまうと、AIは今すぐそれを実現しようとして、タスクを難しくしてしまいます。

興味深いのは、LLMが自動生成したコンテキストファイルも、人間が書いたものも、どちらも同じように逆効果だったという点です。つまり、誰が書いたかではなく、情報量が多すぎることが問題なのです。

フリーランスエンジニアへの影響

この研究結果は、特にCursorやGitHub Copilot、Windsurf、Claude Codeといったコーディング支援ツールを日常的に使っているフリーランスのエンジニアにとって、実務的な意味を持ちます。

まず、作業時間への影響です。多くの人は「AIに詳しい説明を与えれば与えるほど、良い結果が出る」と考えがちですが、実際には逆かもしれません。必要最小限の指示だけを与えた方が、AIは的確に動いてくれる可能性があります。これは、長々とした指示書を書く時間を節約できるということです。

次に、コストの問題です。APIベースでClaude CodeやGPT-4を使っている場合、トークン数が増えれば料金も増えます。20%のコスト増は、月に数万円使っている人なら数千円の差になります。年間で考えれば無視できない金額です。

さらに、成功率の低下も重要です。フリーランスの場合、納期が厳しい案件も多いでしょう。AIのサポートを期待していたのに、逆に手戻りが増えてしまったら本末転倒です。シンプルな指示で済ませた方が、結果的に早く終わるかもしれません。

どんな人に特に関係があるか

この研究結果が特に役立つのは、以下のような人たちです。複数のプロジェクトを抱えているフリーランスエンジニアで、それぞれのプロジェクトに詳細なコンテキストファイルを用意している人。AIツールの料金が気になっていて、コストを下げたい人。AIの出力結果が期待外れで、もっと的確な指示の出し方を模索している人。

逆に、この研究結果があまり関係ないのは、AIツールをほとんど使っていない人や、コンテキストファイルを使わずに毎回プロンプトで指示を出している人です。