コーディングを支援するAIエージェントに、丁寧なドキュメント（説明文書）を読ませればバグ修正の精度が上がるはずだ——多くの開発者が抱くこの直感を検証した論文が、arXivで公開されました。著者らはまず、コードの説明文からどれだけ元のコードを再現できるかを採点する新しいベンチマーク（評価基準）を作り、説明文の質を高める方法を見つけました。ところが、その質の高い説明文を実際のバグ修正タスクに使わせたところ、issue（不具合報告）の文章だけを渡した場合と比べて、精度はまったく向上しなかったといいます。
背景と文脈
AIコーディングエージェントにリポジトリの構造や設計意図を説明したドキュメントを与えれば、issueの内容を正確に理解し的確な修正案を出せるようになる——この考え方は、RAG（Retrieval-Augmented Generation、検索で関連情報を取り出してから回答を生成する仕組み）を使った開発支援ツールの多くが前提にしてきたものです。実際、コードベースの説明文を自動生成し、AIエージェントに読み込ませる機能をうたう製品も増えています。
著者のCompact Documentation for Coding Agents: A Benchmark, an Optimizer, and Why It Does Not Transferという論文でMd Shohel Arman氏とIgor Molybog氏は、この前提そのものを検証するため二段構えの実験を設計しました。まず説明文の「質」を客観的に測る方法を確立し、次にその質の高い説明文が実際のタスクで役立つかを確かめる、という手順です。この順序が重要なのは、もし最初の実験で質の高い説明文を用意できていなければ、後半の実験で効果が出なくても、それが説明文自体の限界なのか、説明文の質が単に低かっただけなのかを区別できないためです。著者らはこの切り分けを丁寧に行った上で、ドキュメントの効果について踏み込んだ結論を出しています。
技術/ビジネス面
まず著者らが作ったのは、「ラウンドトリップ・ベンチマーク」と呼ぶ評価手法です。あるコードの説明文をAIに渡し、その説明文だけから元のコードを再現させ、再現したコードが元のコードと同じテストに合格するかどうかで、説明文の「忠実度」を採点します。この手法で様々な説明文を比較した結果、文章の長さではなく、必要な情報を漏れなく含んでいるかどうか、つまり「完全性」が忠実度を左右することが分かりました。この発見を使い、著者らは忠実度が最大になる説明文の書き方（プロンプト）を見つけ出し、学習に使っていない未知のファイルに対しても同じ書き方が通用することを確認しています。
ここまでは、説明文の質を高める方法が確立されたことを意味します。問題は次の実験です。著者らは、この質の高い説明文を使えばAIエージェントが実際のリポジトリのissueをより正確に解決できるようになるはずだ、という仮説を検証しました。2つの異なるモデル群と10個のリポジトリを使って比較した結果、コードの原文がすでに手元にある状況では、コンパクトな説明文を追加しても、検索で関連コードを取り出す従来のRAG的な手法を追加しても、issueの文章だけを渡した場合を上回る成績は出ませんでした。
これからどうなるか
この結果は、コードベースの説明文を自動生成してAIエージェントに読み込ませる機能を実装しようとしている開発者にとって、立ち止まって考える材料になります。少なくとも、ソースコード自体をAIエージェントが直接参照できる環境では、追加のドキュメント生成にかけるコストや処理時間が、期待したほどの効果を生まない可能性が示されたためです。自社の開発ツールにドキュメント生成機能を組み込む前に、まずissue文とソースコードだけを渡した場合との比較実験を行い、本当に効果があるかを確かめる価値がありそうです。
一方でこの論文はソースコードが手元にある場合の話であり、ソースコードへのアクセスが制限された環境や、非常に大規模なコードベースで関連ファイルを探す手間が大きい場面では、事情が異なる可能性も残ります。今後は、どのような条件下でドキュメントや検索拡張が効果を発揮するのか、境界線を明らかにする追加研究が期待されます。
まとめ
AIコーディングエージェントに与えるドキュメントの効果を検証したarXiv論文は、ソースコードが手元にある状況では、issue文だけの場合と比べて精度が向上しないという結果を示しました。ドキュメント生成機能への投資判断に、実証的な視点を加える研究といえます。
参考リンク
アイキャッチ画像: Photo by Jantine Doornbos on Unsplash
