Copilot のコードレビューがツール変更により悪化した理由と改善策

エージェントにより優れたツールを与えれば、より良い成果を上げるはずだ。それが直感というものだろう。

プルリクエストを開くと、Copilot のコードレビューは差分を読み込み、周囲のコードを検索して、リリース前に重要な問題を見つけ出す。そのために、従来自分のコード探索ツールを使用していた。そこで、Copilot CLI を支えるよりメンテナンス性の高い共有ツールである grep、glob、view に切り替えた際、スムーズなアップグレードになると期待した。

しかし、ベンチマークでは、レビューにかかるコストが増大し、検出される問題の数が減少していることが判明した。

だが、問題はツールにはなかった。指示にこそあったのだ。レビュアーが実際にプルリクエストを読むプロセスに合わせて指示を再構築したところ、後退は勝利へと転じた：平均レビューコストは約 20% 低下し、レビュー品質は維持されたままだった。

これは、ツールの周りにあるワークフローを調整することで解決策に至った物語である。

同じツール、間違った直感

エージェントフレームワークの上に構築したことがあるなら、おそらくそのツールも継承しているはずです。それらは機能しているので、使い続けることになりますが、やがて自分のユースケースが設計時の想定から十分に乖離し、静かに自分自身に逆らうようになる日が訪れます。まさにそれが私たちが直面していた状況でした。

共有 CLI ツールを使用する前に、Copilot code review は独自のコード探索ツールを使用していましたが、そのツールレイヤーは SWE-agent スタイルのリポジトリナビゲーションや GitHub Copilot Autofix などの初期のエージェントシステムから着想を得ていました。具体的には、ディレクトリのリスト表示、ファイル検索、ディレクトリ検索、そしてコードの読み込みといった機能です。

これらのツールは確かに機能していましたが、Copilot code review に特化したものであり、当時のモデルの振る舞い方を想定して設計されていました。初期のエージェント型コーディングモデルは、ツール呼び出し回数が少なく、必要なコンテキストを自動的に取り込む能力も劣っていました。そのため、モデルが行う限られた数のツール呼び出しに、関連する情報をすべて含めることがより重要でした。

一方、Copilot CLI ハーネスには、grep、glob、view という Unix に着想を得たコード探索ツールの共通セットが用意されています。このハーネスは、GitHub Copilot クラウドエージェントを含む、増加する数の Copilot エージェント製品でも利用されており、ハーネスの改善は複数の製品に恩恵をもたらすことができます。私たちは可能な限りインフラを整理して共有したいと考え、Copilot コードレビューにおいて Copilot CLI ハーネスのツールを使用する実験を行いました。その目的は、重複したツールの実装を減らし、コード探索ツールの改善を行うための共通場所を作成し、これらの改善を Copilot 製品間で容易に引き継ぎやすくすることです。

紙面上では、この移行は単純に見えました：

旧 Copilot コードレビュー | GitHub Copilot CLI | 目的

list_dir glob | | コードを開く前に候補となるファイルとディレクトリを発見する。

search_file and search_dir grep | | コード内で一致するテキスト、シンボル、または呼び出し元を検索する。

read_code view | | パスまたは範囲が特定されたら、関連するファイルの内容を一度読み取る。

既存のレビューツールは単なる薄いラッパーではありませんでした。ディレクトリの検索やコード範囲の読み取りを行う際、一致した行や要求された行に加えて、周囲の追加的なコンテキストも返すことができました。これはトークンコストを増加させましたが、同時に、以前のモデルが自動的に近くのコンテキストを含めることで恩恵を受ける傾向があったこととも合致していました。

当初、これは単なる移行になるだろうと期待していました：あるツールのセットを別のツールセットに置き換えるだけだと。しかし、オフラインベンチマークで共有ツールをテストしたところ、レビューエージェントは効率も効果も低下することが判明しました。平均コストが増加し、有用なコメントの数も減少しました。

トレースから閲覧ループが明らかになりました

内部の Copilot コードレビューベンチマークは、単なる最終スコア以上のものを示すため有用でした。エージェントがたどった経路、つまりどのツールを呼び出したか、どれだけの出力が返ってきたか、どこでエラーが発生したか、そして証拠に向かって絞り込んでいたのか、それとも検索範囲を広げていたのかなどを示してくれます。

共有 Copilot CLI ツールをオフラインベンチマークで初めて試した際、エージェントはプルリクエストを検証するのではなく、リポジトリを閲覧しているかのような振る舞いをすることがよくありました。広範に検索し、可能性のあるパスを推測し、広く読み込み、さらに検索すべきものを見つけ、その追加のコンテキストを次のステップへ持ち越すのです。

image図 1：以前の状態 — 私たちが観察した汎用的な行動の簡略化されたイラスト：検索範囲を広げ、パスを推測し、コンテキストを蓄積する様子。

このパターンは理解できます。タスクが「このリポジトリを理解すること」である場合、広範な探索は有用になり得ます。しかし、これはレビュアーが通常プルリクエストを検証する方法ではありません。

私がプルリクエストを検証する場合、diff から始めて、焦点を絞った質問を行います：

この関数はどこで呼び出されていますか？

この設定キーは他の場所で使用されていますか？

同じパターンを持つテストやヘルパーはありますか？

この振る舞いを説明する最小限の近傍コード範囲は何ですか？

何を探しているかを知る前に、リポジトリの大きな部分をオープンしたくありません。レビューを無関係なコードで過負荷にすることなく、質問に答えるために必要な最小限のコンテキストだけを欲しいのです。

これは重要です。なぜなら、すべてのツール結果がエージェントの作業コンテキストの一部となるからです。追加のファイル内容は後の推論にも引き継がれ、コストが増加し、場合によってはレビューの焦点がぼやけてしまう可能性があります。ツール結果は使い捨ての印刷物ではありません。エージェントにとっては、コンテキストウィンドウ内に残る追加のトークンなのです。

その痕跡がその違いを可視化しました。共有されたツール自体に問題があったわけではありません。指示が、効率的かつ効果的なレビューを行うためにエージェントに誤った直感を与えていたのです。

ツール自体は機能していましたが、それらの指示は Copilot CLI 内での使用に合わせて調整されており、誤ったワークフローを暗示していました：エージェントは grep、glob、view を、広範なコーディングアシスタントのように使い、レビューアーとして使わなかったからです。コーディングアシスタントは変更を加える前に領域全体をマッピングし、コードの他の隅々を壊さないように確認することがあります。一方、レビューアーは通常、diff から始め、その変更が問題を引き起こしたかどうかを問い、それを確認または却下するために必要な最も狭い近傍のエビデンスを探します。

Copilot CLI や Copilot クラウドエージェントで使用されるような一般的なコーディングアシスタントツールの指示は、対話型アシスタントにとっては理にかなっています。開発者は、リポジトリの理解、変更の計画、ファイル編集、そして複数回のやり取りを継続することを依頼するかもしれません。

Copilot のコードレビューにはより限定的な役割があります：プルリクエストの差分から始め、変更が実際の問題を引き起こすかどうかを判断するために十分な周辺証拠を集め、そのレビュー質問に必要のないコンテキストを読み込まないようにすることです。

したがって、追加のプロンプト作業なしで、以前の Copilot コードレビューツールを Copilot CLI のツールに単純に置き換えることはできないことは明らかでした。課題はこうなりました：これらの共有ツールをコードレビューの文脈で効果的に活用するためのツール指示をどう設計するか。

レビュワーのワークフローのためのツール指示の書き換え

次の反復では、ガイダンスがコードレビューに特化されました。Copilot コードレビューに実行してほしいワークフローは以下の通りです：

差分から始めて、具体的なレビュー質問を形成する。

パスが不確かな場合は glob を使用し、候補となるファイル、シンボル、呼び出し元を検索するために grep を使用する。

ファイルを読み込む前に、安価な発見処理を一括で行う。

エージェントが必要なファイルや行範囲を把握している場合にのみ view を使用する。

1 回の検索と 1 回の読み込みを交互に行うのではなく、焦点を絞った読み込みを一括で行う。

過度に単純化すれば、これが私たちがコード化した振る舞いです：

一般的な姿勢：利用可能なツールを使用して、関連する可能性のあるリポジトリのコンテキストを検査する。

レビューに特化したガイダンス：diff から始める。まず grep と glob で範囲を絞り、view で正確な証拠を読む。grep で関連する文脈が見つからない場合は、エスケープされたより単純な検索で再試行する。パスが間違っている場合は、近くのパスを推測するのではなく、glob に切り替える。

例えば、diff が操作の許可可否を決定する認可ヘルパーを変更した場合を想像してください。関連するレビューの質問は「このヘルパーを呼び出すすべてのファイルの完全な内容を表示してほしい」ではありません。代わりに、より絞り込んだ「旧来の動作に依存しているリクエスト処理の呼び出し元はあるか」という問いが考えられます。

意図された手順は短く以下の通りです：

diff で変更されたヘルパーから始める

そのヘルパーの呼び出し元を grep で検索する

おそらくルート、ハンドラー、またはコントローラーファイルであるものを glob で検索する

最も関連性の高い呼び出し元の範囲を view で確認する

どの呼び出し元がリスクを変化させるかを判断する

このガイダンスは、エージェントが失敗した検索から回復する方法も変更しました。入力が grep の失敗を引き起こした場合、より良い次のステップは、修正されたより単純な検索です。パスが間違っている場合、より良い次のステップは隣接するパスを推測して存在するものを何でも読むことではなく、glob を使用することです。これにより、小さなツールの失敗が大きな探索ループに発展することを防ぐよう、エージェントを誘導しました。

image図 2：後 — プロンプトが指向したレビューに特化した動作の簡略化されたイラスト：diff にアンカーを留め、grep と glob で絞り込み、view で焦点を絞った範囲を読む。

言葉の表現はさほど大きく変わらなかったものの、その効果は絶大でした。エージェントのリズムを「閲覧、読解、再検索」から「質問、絞り込み、読解、判断」という流れに変えたのです。

ベンチマークはスコアだけでなく、動作のデバッグも可能にする

共有されたハーン（枠組み）がツールを提供し、内部の Copilot コードレビュー用ベンチマークフィードバックループをもたらしました。

同じレビュー例を実行し、ツールのトレースを比較し、指示を更新して再実行することができました。これにより、具体的な質問が可能になりました：

エージェントはまず絞り込みを行ったのか、それとも広く読解したのか？

独立した検索をバッチ処理したか？

理由がある場合にのみ view（表示）ツールを呼び出したか？

ツールの指示変更はツールのエラーを減らしたのか、単に別の場所へ移しただけなのか？

トレースは diff（差分）からの証拠に焦点を維持していたか？

レビューは私たちが重視する品質指標を依然として保持していたか？

最も有用なシグナルは「指示が改善された」というものではなく、より具体的なものでした。エージェントが行うツールの呼び出し回数はほぼ同じでしたが、検索を繰り返し拡大するのではなく、関連性の高い証拠に時間を割くようになったのです。

これにより、製品レベルの成果と理解可能なエンジニアリングの動作が結びつきました。スコアが変動した理由を推測する代わりに、それを生み出したワークフローを検証できるようになりました。

その結果：平均レビューコストが約 20% 低下

本番環境では、調整された動作により、対照群と比較して平均レビューコストが約 20% 低下しました。重要なのは、出荷を阻止する品質上の問題を示すシグナルは現れなかったことです。

この削減はツール自体によるものではなく、それを取り巻くワークフローによるものでした。共有コード探索ツール、Copilot コードレビューのカスタムツール指示、および内部ベンチマークにより、エージェントの振る舞いを十分に可視化し、調整できるようになりました。

これはエージェントで構築する際に重要な枠組みです。ツールを実装の詳細として扱い、あるツールを別のツールに置き換えて最終的な回答を比較するという誘惑に駆られることがあります。しかし、エージェントにとってツールのインターフェースは製品体験の一部です。それはエージェントが何に注意を向けるか、どのように検索するか、どの程度のコンテキストを次へ引き継ぐか、そして十分な証拠があると感じるタイミングを変化させます。

ツール説明やシステム指示は API ドキュメントに近いものです。不明確な API ドキュメントは開発者を混乱させ、非効率または誤った決定につながります。同様に、不明確なツールのプロンプトは LLM に対しても同じ影響を及ぼします。わずかな言葉遣いの変更が、エージェントの注意の向け方を変えることで、コスト、品質、調査の形状に影響を与える可能性があります。

同じツールでも異なる役割

私たちは CLI においても同様の焦点を当てたツール指示を適用しようと試みましたが、そこでは同じような成果は得られませんでした。これは有用な反例であり、この教訓に対する重要なガードレールです。

Copilot のコードレビューは、差分（diff）とレビュー質問に紐付けられています。一方、Copilot CLI はより広範な対話型コーディングタスクを扱い、探索が業務の一部となる場合もあります。単一の差分アンカーが存在しないこともあり、ユーザーは複数のやり取りを通じて方向性を変更することもあり、初期段階では適切なコンテキストが明確でないこともあります。同じ grep、glob、ビューツールが両製品で利用可能ですが、それらのツールを取り巻くワークフローは各製品の特性に合わせる必要があります。

重要な点は、共有ツールのスケーラビリティは、指示とベンチマークが実際の業務内容と一致している場合に発揮されるということです。

GitHub Copilot のコードレビュー機能を使って、ぜひご自身でお試しください。

「より良いツールが Copilot のコードレビューを悪化させた。実際に改善した方法」という記事は、もともと The GitHub Blog で公開されました。