grepを使うAIエージェントにコード構造の注記を渡すと探索のブレが半減する
公開日
開発生産性
ソフトウェア開発において、大規模言語モデル（LLM）を活用した自律型のコードAIエージェントの導入が進んでいます。しかし、多くのエージェントはキーワード検索（grepなど）を中心にコードベースを探索するため、関数間の呼び出し関係やクラスの継承関係といったプログラムの「構造的繋がり」を直接捉えることができず、検索や移動の経路が実行ごとに変動しやすい課題を抱えています。
本記事では、中国の北京航空航天大学の研究チームが発表した論文「How Much Static Structure Do Code Agents Need? A Study of Deterministic Anchoring」を紹介します。この研究では、ソースコード内に軽量な静的解析結果を注記コメントとして挿入するアプローチを提案し、AIエージェントのファイル・関数特定精度、ナビゲーション効率、および実行ごとの挙動の安定性に与える影響を系統的に評価しています。
grepベースのコードAIエージェントが直面する「繋がりの欠如」
現在主流となっているコードAIエージェントの多くは、自然言語の指示を受けてキーワード検索（grepやripgrep）を実行し、一致したコード領域を読み込みながら次の探索先を決めるアプローチを採用しています。この方式は高速で言語に依存せず、構文エラーを含む不完全なコードに対しても動作する利点があります。
一方で、テキストの文字一致に頼る検索は、コード同士の関連性や繋がり（関数の呼び出し元と呼び出し先、クラスの継承、設定値の伝播など）を直接表現できません。そのため、エージェントは何度も手動の検索を繰り返して構造関係を再発見しなければならず、文脈が断片化しやすい問題が生じます。
さらに、LLMの確率的な推論特性とテキスト検索が組み合わさることで、同じ課題を与えても実行ごとに全く異なるファイル群を探索し、ステップ数や出力される修正コードが乱れる「挙動の不確実性」が発生します。開発現場でAIエージェントを運用する上では、集計上の成功率だけでなく、探索プロセスの再現性や予測可能性が重要な観点となります。
表1：grepベースエージェントにおける構造情報不保持の課題
| 課題項目 | 内容 | 影響 |
|---|---|---|
| 構造的繋がりの欠如 | 検索結果が独立したテキスト断片として返され、呼び出し関係や継承関係が隠蔽される | 多段階の再検索が必要になり、コンテキストが断片化する |
| 挙動の不確実性 | 初期検索のわずかな違いがその後の探索経路へ波及する | 同一タスク・同一設定でも試行ごとに探索ファイルやステップ数が変動する |
| ハブ関数によるノイズ | 多数の箇所から呼び出される共通ヘルパー関数が検索上位を占有する | 本当に変更が必要な内部実装に到達する前に迷走する |
CodeAnchorの仕組み：ソースコードへの構造注記の直接埋め込み
研究チームは、エージェントの制御ループやツール群を複雑化させることなく構造情報を提供するため、「CodeAnchor」と呼ばれるフレームワークを提案しました。
CodeAnchorでは、オフラインの静的解析（PyCGによる呼び出しグラフ抽出やAST解析）を利用して、リポジトリ内の関数、クラス、ファイル間の関係性をあらかじめ解析します。抽出された構造的ファクトは、平文コメント（CodeAnchorタグ）として、ソースコードの定義元付近に挿入されます。
実行時、エージェントは既存のテキスト検索ツールを用いてコードを閲覧します。検索結果にはソースコードとともに近隣のCodeAnchorタグが含まれるため、エージェントは明示的なグラフ操作ツールを意識的に呼び出すことなく、タグ内に記述された「呼び出し元」「呼び出し先」「継承元/先」などの情報を直接読み取ることができます。
研究チームは、この仕組みによってエージェントが構造的リンクを辿って直接移動できるようになり、無駄な再検索を削減する効果が生じると説明しています。
図1：CodeAnchorのフレームワーク構成とタグ挿入のイメージ
実証実験：軽量なトポロジー注記による精度向上とステップ数削減
研究チームは、OpenAIのモデル（GPT-5.1-codex）を用いたCodexベースのエージェントを構築し、Pythonのバグ修正ベンチマークであるSWE-bench Lite（274タスク）およびSWE-bench Verified（500タスク）上で効果を検証しました。
基本的な呼び出し関係と継承関係のみを注記した「Anchor-Topo」と、通常のソースコードのみを検索対象とした「Baseline」を比較したところ、明確な改善が確認されました。
- 目的の関数を素早く特定可能に: 対象関数を上位5件以内に特定できる精度（Func@5）が、Liteで83.2%から85.4%へ（+2.2ポイント）、Verifiedで61.9%から63.1%へ（+1.2ポイント）向上しました。
- 無駄な探索の削減: タスク完了までに要したツール呼び出しの平均ラウンド数が、Liteで35.3回から33.7回へ（1.6回削減）、Verifiedで42.4回から40.9回へ（1.5回削減）減少し、より少ないステップで目的地へ到達できるようになりました。
一方で、最初に開いたファイルの一致率（File@1）にはわずかな低下が見られました（Liteで91.2%から89.8%へ）。これは、エージェントが構造タグに導かれて最初に関連するクラス定義やハブファイルを探索し、そこから真のバグ発生関数へ移動するという「構造的迂回」が発生しているためだと分析されています。最初からピンポイントで当てる代わりに、構造的な繋がりを順に追う堅実なルートを辿っていると言えます。
さらに、特定精度の向上が実際のバグ修正に貢献するか調べるため、結果が分かれた80件のタスクで比較実験を行ったところ、注記を追加したエージェントは60.0%（48/80）の修正に成功し、元のエージェントの47.5%（38/80）に対して+12.5ポイント高い成功率を示しました。
リポジトリ規模とハブ関数が左右する注記の粒度と方向性
研究チームはさらに、注入する情報の「粒度」と「方向性」を変えた複数の設定を用意し、どのような構造情報が有効かを検証しました。
具体的には、基本的な呼び出し関係を扱う「Anchor-Topo」に加え、データフローや設定値の利用も埋め込む高密度な「Anchor-Dense」、および「誰が自分を呼び出しているか」という逆方向の参照だけに絞った「Anchor-Inv」の3種類を比較しています。
実験から明らかになった主なポイントは次の2点です。
1. 情報を詰め込みすぎるとコストが増えて効果は頭打ちになる
基本トポロジーにデータフロー等の詳細を加えた「Anchor-Dense」は、バグの特定精度自体は「Anchor-Topo」とほぼ変わりませんでした。しかし、探索ラウンド数が平均で4.9回増加し、入力トークン数も約30%増加しました。
一部の高度なデータ伝播が絡む複雑なバグ（Liteの3件、Verifiedの15件）には有効だったものの、通常のバグ特定においては過剰な情報がかえってノイズとなり、トークンコストに見合う効果を得にくい「情報の飽和効果」が確認されました。
2. コードベースの規模とハブ関数で「向き」の最適解が変わる
中規模なプロジェクトを中心とするSWE-bench Liteでは、呼び出し先と呼び出し元の両方を載せた双方向タグ（Anchor-Topo）が最も効果的で、逆方向だけに絞るとかえって探索効率が低下しました。
しかし、共通ヘルパー関数などのハブノード（多数から呼ばれる中心的な関数）が多い大規模なSWE-bench Verified（平均120k行）では傾向が反転しました。逆方向リンクのみに絞った「Anchor-Inv」の方が、精度指標（Func@5で63.29%）でわずかに上回る結果となりました。大規模コードで呼び出し先のタグを大量に埋め込むと、検索結果がハブ関数で埋め尽くされ、エージェントが注意を削がれてしまう「ハブの誘惑問題」が生じるためです。
実行ごとの振る舞いの安定化と運用のポイント
AIエージェントを実際の開発現場で使う際に大きな懸念となるのが、「同じ指示を出しても実行ごとに探索経路や結果がブレる」という点です。研究チームはこの点について、50個のタスクに対して各10回（計500回）の繰り返し実験を行い、挙動の安定性を測定しました。
実験の結果、構造注記（CodeAnchor）を追加することで、特定精度の標準偏差が0.043から0.022へと半減し、試行ごとの挙動のばらつきが大幅に低減しました。また、エージェントを1回だけ実行した際の成功率（Pass@1）も74.2%から77.6%へ+3.4ポイント向上しました。
コード内に記述された明確な関係性が「決定論的な道しるべ（アンカー）」として機能することで、LLMの確率的な揺らぎによる迷走が抑えられ、毎回再現性の高いルートでコードを探索できるようになります。
静的解析の不完全さとLLMの許容力
本研究で用いられたPyCGなどの静的解析ツールは完全ではなく、動的呼び出しやリフレクションなどを拾いきれない「不完全さ」を含んでいます。しかし分析によると、バグ箇所のうち動的な呼び出しに依存する関数は3%未満であり、可視化できる依存関係の94.2%をカバーできていました。
さらに重要な点として、厳密なコンパイラとは異なり、LLMエージェントは注記タグを絶対的なルールではなく「確率的なヒント」として柔軟に扱います。そのため、静的解析のグラフに一部欠落があってもテキスト検索で補うことができ、不完全な構造注記であっても大きな効果を発揮できることが分かっています。
開発チームや運用でのポイント
本研究の結果から、AIエージェントを活用する開発チームやマネージャーは以下のポイントを参考にできます。
- 軽量トポロジーをデフォルトにする: 関数の呼び出し関係とクラスの継承関係だけに絞った軽量な注記を標準とすることで、トークン消費を抑えながら精度と速度を最大化できます。
- 大規模コードでは逆方向参照を活用する: 100k行を超える規模や共通モジュールの多いリポジトリでは、「誰から呼ばれているか」の逆方向参照を中心に整理することでノイズを減らせます。
- 完璧な解析インフラは不要: 厳密で完璧な解析ツールを用意しなくても、軽量なAST抽出等による「大まかな構造注記」でエージェントの迷走を十分に防ぐことができます。
なお、本研究はPythonおよびSWE-bench（1〜2ホップで到達可能なバグ）での検証が中心となっており、他言語やより深い階層のリファクタリングにおける効果検証が今後の課題とされています。
まとめ
本研究は、grepベースのコードAIエージェントに対して、軽量な静的解析結果をソースコード内のコメントとして提示するアプローチの有効性を実証しました。
呼び出し関係や継承関係などの基本的な構造情報をテキスト内に埋め込むことで、関数の特定精度が向上し、探索の無駄なラウンド数が削減されるとともに、実行間の挙動のブレが約半分に抑えられます。高密度すぎる注記はかえってノイズになるため、プロジェクトの規模に合わせて適切な情報量と方向性を選択することが成功のポイントとなります。
開発生産性やチームビルディングにお困りですか？ 弊社のサービス は、開発チームが抱える課題を解決し、生産性と幸福度を向上させるためのさまざまなソリューションを提供しています。ぜひお気軽にご相談ください！
参考資料：