Claude Code の意味的コード検索ベンチマーク - Turbopuffer

Claude Code の検索精度を劇的に変える「意味的コード検索」の実証データ

AI エージェントが複雑なコードベースを扱う際、従来のファイルシステム探索（グレッピング）に代わり、「意味的コード検索（ベクトル検索）」を導入することで、検索精度が 65% から 87% へ劇的に向上することが実証されました。Turbopuffer の Kuba Rogut 氏による本ベンチマークは、単なるキーワードマッチングの限界を打破し、大規模なコードベースにおける開発効率とコスト削減の新たな指針を示す重要なデータです。

デフォルトの「グレッピング」から意味的検索への転換

Claude Code のデフォルト動作は、ファイルシステムを探索する「エージェント型検索」、つまり grep によるキーワードマッチングに依存しています。創始者の Boris が示唆するように、初期のバージョンではローカルベクトル DB を試すも、シンプルなタスクではグレッピングの方が優れていると判断されました。

しかし、これは「すべてのケースで有効」という意味ではありません。Turbopuffer の顧客である Cursor は、コードベースを事前にインデックス化し、ベクトル検索を活用することで、Composer モデルにおける回答精度を約 24% 向上させました。オンライン AB テストでも、セマンティック検索の導入によりコード保持率が 2.6% 増加し、大規模コードベースでのユーザーの不満が 2.2% 減少しています。

「すべてのクエリでセマンティック検索が使われるわけではありません。非常にシンプルなツール呼び出しや単純なクエリでは不要です。」

このデータは、検索手法をタスクの複雑さに応じて使い分ける必要性を示唆しています。

ベンチマークが示す「精度」と「コスト」の劇的改善

Kuba 氏は、Claude Code のデフォルト設定、50 行ごとのウィンドウ付きグレッピング、そして Turbopuffer を活用した意味的検索の 3 つを比較するベンチマークを実施しました。その結果、意味的検索の導入が「不要なファイル読み込み」を大幅に削減し、精度を劇的に高めることが明らかになりました。

1. 検索精度（Precision）の向上

精度は、「実際に読み込んだファイルのうち、本当に必要なファイルが含まれていた割合」を示します。デフォルトの Claude Code ではこの値が 65% に留まっていましたが、意味的検索を導入すると87%まで上昇しました。

これは具体的には以下のような改善を意味します：

• デフォルト（グレッピング）: ファイル読み込みの3 件に 1 件が無駄なファイルである。
• ウィンドウ付きグレッピング: 5 件に 1 件が不要。
• 意味的検索: 8 件に 1 件のみが不要なファイルとなる。

「Claude Code では、ファイル読み込みの 3 件に 1 件が完全に無駄です。しかしセマンティック検索では、8 件に 1 件のみが無関係となります。」

2. トークンコストと計算リソースの削減

意味的検索は、初期にコードベースをチャンク化して埋め込み（エンベディング）するコストがかかりますが、一度インデックス化すれば、その後の検索で「意味のキャッシュ」を活用できます。

• グレッピング: 毎回ファイルシステムを走査し、同じ質問に対しても毎回同じ計算を繰り返すため、トークン消費と時間がかかる。
• 意味的検索: 埋め込みベクトルを検索するだけで、必要なコンテキストを素早く取得できる。一度の処理では大きな節約に見えなくても、複数回のセッションや大規模コードベースにおいて、長期的には計算リソースとトークン数を大幅に削減します。

タスク固有の適応性：グレッピングが勝つケースも存在する

重要なのは、「意味的検索が常に最強」というわけではないという点です。ベンチマークでは、タスクの種類によって最適な手法が異なることが浮き彫りになりました。

• 意味的検索が圧倒的に有利なケース:
• キーワードに一致しない「行動」や「文脈」を必要とするタスク。
• 複数の ORM やライブラリを跨ぐ複雑な処理の理解。
• コード内のコメントやドキュメントから意味を読み取る必要があるケース。

例えば、「異なるライブラリ間でどう処理すべきか」という問いに対し、キーワード検索では関連ファイルが見つからない場合でも、ベクトル検索は「文脈的に近い」ファイルを発見できます。

• グレッピングが有利なケース:
• キーワードの一致が明確な単純なタスク（例：特定のインポートを追跡する、特定の関数名を探す）。

この場合、キーワード検索の方が高速かつ確実です。つまり、「検索ツールを単一に固定せず、タスクに応じて使い分ける」ことが、AI エージェントの性能を最大化する鍵となります。

実装と今後の展望：埋め込みモデルの工夫

今回のベンチマークでは、Voyage Code モデルを用いてコードを埋め込み、Turbopuffer にアップロードするというシンプルなアプローチが採用されました。しかし、業界の最前線ではさらに高度な工夫が行われています。

Cursor は独自のエンベディングモデルを持っており、「コードの上に疑似コメント（インジェクション）を作成し、そのコメント付きでコードを埋め込む」手法を採用しています。これにより、コードの意味をより人間レベルのクエリに近い形で理解させ、検索精度をさらに高めています。

「コードにコメントが多く含まれている場合や、ドキュメントがコード内に直接記述されているケースでは、意味的検索の効果は特に大きくなります。」

また、ベクトルデータベースは、ファイル名のみで検索する grep では不可能な「マルチモーダルデータ（動画、音声、画像）」の理解にも応用可能です。大規模かつ複雑なデータ環境において、意味的な文脈を保存・検索できる仕組みこそが、長期的な勝者となるでしょう。

まとめ

このベンチマークは、AI エージェント開発における「キーワードマッチングから意味的理解への移行」が不可欠であることを明確に示しました。初期の埋め込みコストはかかりますが、複雑なタスクや大規模コードベースにおいては、検索精度の向上とトークンコストの削減という二つのメリットを同時に実現できます。

開発者やツール提供者は、単一の検索手法に依存するのではなく、タスクの性質に応じてグレッピングと意味的検索を使い分けるハイブリッドなアプローチを採用することで、より賢く効率的な AI エージェントを実現できるはずです。