エージェントのコード検索にはトークン予算がある

Sembleは2026年5月17日、GitHubで900スターを超えました。その背景にある主張は明快です。コーディングエージェントは、grepし、ファイル全体を開き、タスクに必要な量を大きく超えてコードを読むことで、コンテキスト予算の大半を浪費している、というものです。¹

この主張が刺さるのは、コード検索を予算の問題として捉え直しているからです。人間なら、ノイズの多いrgの結果をざっと眺めて不要な行を無視できます。エージェントの場合、無関係な行の一つひとつが、コンテキスト、注意、ツール呼び出しの時間としてコストになります。

要点

Sembleはエージェント向けのコード検索ライブラリです。MCPサーバー、AGENTS.mdまたはCLAUDE.md経由のシェル統合、CLI、Python APIを提供しています。¹ 内部では、コードをチャンク化し、BM25と静的なModel2Vecコード埋め込みで検索し、Reciprocal Rank Fusionで順位リストを統合します。その後、シンボルの重み付け、定義の優先、識別子の語幹、ファイル内の一貫性、ノイズへのペナルティといったコード特化のシグナルで再順位付けします。¹ ベンチマークでは、19言語・63リポジトリ・約1,250クエリに対してNDCG@10が0.854と報告されています。CodeRankEmbed Hybridの0.862に近く、ベンチマーク表ではインデックス作成がはるかに速い結果です。² ただし、重要なプロダクト上の教訓は「grepを置き換える」ことではありません。もっと鋭く言えば、エージェント向け検索ツールは、モデルが正しく行動するために必要な最小の証拠パケットを返すべきだ、ということです。

重要なポイント

• コーディングエージェントのユーザーへ: 正確な文字列にはrgを使い続けましょう。ただし、タスクがリテラルなトークンではなく振る舞いを問う場合は、スニペットを順位付けして返す検索が向いています。
• ツール開発者へ: 検索精度だけでなく、取得されるコンテキストを最適化しましょう。有用な単位は、トークンあたりの証拠です。
• CodexとClaude Codeのユーザーへ: サブエージェントには、シェルから使える経路を優先しましょう。トップレベルのMCPツールが、委任されたエージェントから同じように届くとは限らないためです。¹
• ベンチマークを読む人へ: ベンダーのベンチマーク主張と、ローカル実行時の挙動は分けて考える必要があります。私のコールドなuvx実行は、パッケージ、モデル、インデックスの起動が支配的だったため、Sembleのベンチマーク表よりかなり時間がかかりました。
• 公開記事を書く人へ: 検索ツールが引用作業をなくすわけではありません。証拠までの道筋を安く調べられるようにするだけです。

Grepは今でも優秀です。ただ、それだけでは足りません

rgは、正確な文字列を探す最初のツールとして今でも正解です。visible_label_residue、認証情報の変数名、関数名が必要なときは、語彙検索が速度と確実性で勝つべきです。私のローカルテストでは、翻訳の残留語に関するリテラルなrgクエリは約0.1秒で返りました。⁵

問題は、エージェントが正確な文字列を知らないときに始まります。

エージェントはしばしば意図で検索します。「blog i18nのゲートは、表示ラベルの残留語をどこで確認しているのか」「翻訳リリース検証はどう動くのか」といった問いです。リテラル検索でも有用な行が見つかることはあります。しかしエージェントは、検索語を選び、何十件ものヒットを調べ、ファイルを読み、クエリを作り直し、どの行が答えを持っているか判断しなければなりません。すべてのステップがコンテキストを消費し、早すぎる判断で止まる可能性を増やします。

Sembleが狙っているのは、まさにこの失敗パターンです。自然言語で問い合わせると、ファイル全体ではなく、順位付けされたコードスニペットを返します。¹ それによってrgが不要になるわけではありません。デフォルトのやり取りが、「この語に一致する行を全部見せて」から「役に立つ最小のコード断片を渡して」に変わるのです。

この違いは重要です。エージェントは人間のようには読みません。人間なら80行の検索結果を流し見して、重要な3行だけを頭に残せます。モデルは出力全体をトークンとして受け取ります。ノイズの多い検索結果そのものが、タスク環境の一部になってしまうのです。

Sembleが実際にしていること

Sembleの公開READMEでは、4つの統合経路が説明されています。MCPサーバー、Bash / AGENTS.md、CLI、Python APIです。¹ Codexの設定は~/.codex/config.tomlにローカルのMCPサーバー項目を追加する形で、シェル経路ではAGENTS.mdまたはCLAUDE.mdにコード検索セクションを加えます。¹

シェル経路は、最初に見える以上に重要です。READMEでは、Claude CodeとCodex CLIのサブエージェントは、MCPの代わりに、または併用してBash統合を使うべきだと明記されています。その構成では、サブエージェントがMCPツールを直接呼べないためです。¹ これは実践的なエージェントインターフェース上の論点です。検索ツールは、トップレベルの作業回が始まる場所だけでなく、実際に作業が行われる場所に存在している必要があります。

検索の構成も、エージェント検索が向かう方向をよく表しています。

この設計は、私がローカル検索システムで見てきた傾向とも合っています。純粋なベクトル検索は識別子を落としやすく、純粋なキーワード検索は意図を落としやすい。ハイブリッドな順位付けは、エージェントにより良い最初の読みを与えます。⁴

ベンチマークの主張は魔法ではなくコンテキストの話です

SembleのベンチマークREADMEは、2種類の結果を報告しています。

1つ目は、検索品質と速度です。表では、Sembleが0.854 NDCG@10、CodeRankEmbed Hybridが0.862、BM25が0.673、ripgrepが0.126とされています。ベンチマークは19言語・63リポジトリ・約1,250クエリを対象にし、CPUのみで実行されています。²

2つ目は、トークン効率です。ベンチマークは、コーディングエージェントでよくあるワークフローをモデル化しています。クエリをキーワードに分割し、rg --fixed-strings --ignore-caseを実行し、異なるキーワードの一致数でファイルを順位付けし、一致したファイルを丸ごと読む、というものです。このベースラインに対して、ripgrepとファイル全文読みでは平均45,692トークン、Sembleでは566トークンで、98%削減と報告されています。²

興味深いのはこちらの主張です。あらゆる場面で「意味検索がgrepに勝つ」という話ではありません。「エージェントは正確な検索をやめるべきだ」という話でもありません。主張の中心は、タスクが数個のチャンクだけを必要としているときに、grepして読む流れは無関係なコードをモデルへ送り込みすぎる、という点です。

ベンチマークの方法論を見ると、この主張が当てはまる範囲と当てはまらない範囲も分かります。Sembleは、一致したファイルを丸ごと読む場合と比較しています。² すでにrg -n、sed、狭い行範囲を使っているワークフローなら、ベースラインはベンチマークのgrepして読むモデルより締まっているかもしれません。逆に、エージェントが広い検索のあとでファイル全体を日常的に開いているなら、ベンチマークは実際の失敗モードにかなり近いはずです。

ローカルで試したこと

サイトのリポジトリでuvx --from semble sembleを通してSembleを実行し、リテラルなrg検索と比較しました。

最初はリリースプロセスについて問い合わせました。

semble search "blog translation quality gate release verifier D1" . --top-k 5 --include-text-files

Sembleは5つのスニペットを返しました。最上位の結果は、移行記事の表の中にあるブログ翻訳リリースループを要約していました。別の結果は、scripts/i18n-automation/README.mdを直接指しており、そこには品質基準、リリース検証、ネイティブレビュー、コミット、プッシュ、Railway、Cloudflare、本番スモーク確認の各ステップが含まれていました。⁵

対応するrgコマンドは高速に返りましたが、認証情報の変数、blog_release_verify、関連する名前について、スクリプト、テスト、ドキュメントをまたぐ大量のリテラル一致を返しました。⁵ 人間なら絞り込めます。エージェントは同じことをするためにコンテキストを使わなければなりません。

次に、ゲート実装を尋ねました。

semble search "where does the blog i18n gate check visible label residue" . --top-k 5 --include-text-files

Sembleの最上位結果は、visible_label_residueが代入され、エラーに変換され、検出結果の状態に影響する、まさにそのローカルゲートのブロックを指していました。出力には、ファイル全体ではなく、関連する関数本体の行が含まれていました。⁵

対応するrgクエリもやはり高速でしたが、テスト、翻訳プロンプト、修復スクリプト、README、ゲート実装をまたいで多くのヒットを返しました。⁵

このテストは、Sembleのベンチマークを証明するものではありません。私の呼び出しはuvxを使い、パッケージとモデル資産をダウンロードし、大きな混在リポジトリをインデックスし、MarkdownとJSONファイルも含め、コールドな経路から実行しました。最初のSembleクエリは約54秒、2つ目は約31秒かかりました。⁵ これらの数値はプロジェクトのベンチマーク表とは一致せず、Sembleの性能データとして引用するつもりはありません。

ただし、このテストはプロダクトの形を示しています。Sembleは、より小さく、答えに近い証拠パケットを返しました。2回検索したあと、semble savings --verboseは、独自のファイル対スニペットの節約方法に基づいて、推定約38,100トークン、94%の節約を報告しました。⁵ これは独立した測定ではなくツール報告の推定値として扱うべきですが、見えている出力の方向性とは一致していました。

正しい捉え方: 証拠パケット

エージェント検索が生み出すべきものは、証拠パケットです。

証拠パケットには4つの性質があります。

生のrgは場所と速度を与えます。ファイル全体を読むと文脈は得られますが、多すぎます。ベクトル検索は意図を拾えますが、正確な名前を落とすことがあります。良いエージェント検索ワークフローは、それらを組み合わせます。

1. タスクがシンボル、エラー、設定キー、ファイル、リテラル文字列を名指ししているときは、正確な検索を使う。
2. タスクが振る舞いを説明しているときは、意味検索またはハイブリッド検索でスニペットを順位付けする。
3. スニペットが関連性を証明してから、ファイル全体を開く。
4. 最終回答では、ファイルと行範囲を引用する。
5. スニペットが具体的な識別子を示したら、正確な検索で再確認する。

Sembleは、このワークフローの多くをツールとして組み込んでいます。それでもエージェントには判断が必要ですし、証拠ゲートには検査できる実行経路が必要です。

SembleがCodexとClaude Codeのワークフローをどう変えるか

実務上の問いは、新しい検索ツールをすべてインストールすべきかどうかではありません。コード検索をエージェントの動作契約のどこに置くかです。

トップレベルの作業回では、MCPがうまく機能します。エージェントがツールスキーマを見て、サーバーを直接呼べるからです。SembleのREADMEには、Claude Code、Codex、OpenCode、Cursor、その他のMCP互換クライアント向けのMCP設定例があります。¹

委任された作業では、シェルアクセスのほうが重要になるかもしれません。SembleのREADMEは、Claude CodeとCodex CLIのサブエージェントに対してBash統合を明示的に挙げています。¹ トップレベルのMCPツールに届かないサブエージェントでも、ワークフローがいつ、どう使うかを教えていれば、シェルコマンドは実行できます。

つまり、最良の統合は地味に見えるかもしれません。

## Code Search

Use `semble search` when looking for behavior or related implementation.
Use `rg` when looking for an exact string, symbol, file name, or config key.
Open full files only after the search result proves relevance.
Report file path and line range when citing evidence.

この種の指示は、漠然とした「意味検索を使う」というルールより強いです。振り分けの判断を明示しているからです。エージェントは、どの問いにどのツールが合うかを学べます。

私ならやらないこと

rgを置き換えることはしません。

ローカルテストで、それは明らかでした。rgはリテラルなクエリに約0.1秒で答えました。Sembleは振る舞いに基づくクエリに対してより良いパケットを返しましたが、私のコールドなシェル呼び出しには、実際に起動とインデックスのコストがありました。⁵

Sembleの98%トークン削減の主張を普遍的なものとしては扱いません。ベンチマークは、grepしてファイル全体を読む流れと比較しています。そのベースラインがエージェントの挙動に似ているなら、主張は妥当です。すでに狭い行範囲だけを読む規律あるワークフローでは、得られる改善幅は誇張されます。

振り分けの判断をブラックボックスに隠すこともしません。エージェントは、自分が正確な検索をしているのか、意味的な探索をしているのか、関連コードを調べているのか、証拠確認をしているのかを知る必要があります。振り分けルールのないツール利用は、もっともらしい失敗の別の源になります。これは、チャット主導のエージェント作業の背後にあるインターフェース問題と同じです。

SembleがGrep論文の隣に置かれるべき理由

最近の「Is Grep All You Need?」論文は、長期記憶の会話型QAにおいて、Chronos、Claude Code、Codex CLI、Gemini CLIを横断して、grepとベクトル検索を検証しました。その設定ではインラインgrepがインラインベクトル検索を上回りましたが、より深い教訓のほうが重要です。検索手法そのものと同じくらい、実行環境が結果を変えたのです。³

Sembleは、コード側から同じ運用層を指しています。検索品質は検索器だけに宿るものではありません。次の要素に宿ります。

• クエリがどう作られるか。
• 正確な経路と意味的な経路が両方あるか。
• ツールがどれだけのコンテキストを返すか。
• スニペットにファイルと行の証拠が含まれているか。
• エージェントが必要なときだけファイル全体を開くか。
• 委任されたエージェントがツールに到達できるか。
• 最終回答が検索で実際に見つけたものを引用しているか。

ラッパーこそがプロダクトです。検索が有用になるのは、実行環境が検索結果を証拠に変えるときだけです。だからこそ、エージェント型デザインの制御面は検索アルゴリズムと同じくらい重要になります。

望ましい標準

エージェント検索ツールは、一致結果以上のものを報告するべきです。

報告すべき内容は次の通りです。

• 実行したクエリ。
• 使った検索経路。
• ファイルと行範囲。
• スニペット。
• 返されたトークンの推定量。
• 結果が正確検索、意味検索、ハイブリッド検索のどれから来たか。
• エージェントがスニペットからファイル全文読みへ進んだタイミング。

この出力があれば、コード検索は監査可能になります。レビュー担当者は、エージェントが正しいコードを見つけたか、十分な文脈を読んだか、無関係なファイルに埋もれるのを避けたかを確認できます。同じ原則は、エージェント実行トレースにも通じます。証明は答えだけでなく、そこに至る経路にあります。

Sembleは、スニペットサイズとトークン節約をプロダクト上の第一級の関心事として扱うことで、すでにその方向へ進んでいます。エージェント実行環境の次の一歩は、その証拠経路をレビューパケットと最終回答で見えるようにすることです。

目的は、検索を見栄えよくすることではありません。目的は、トークンあたりの根拠なき主張を減らすことです。

FAQ

Sembleはgrepを置き換えますか？

いいえ。正確な文字列、シンボル、設定キー、ファイル名、高速な確認にはrgを使いましょう。タスクが振る舞いや関連実装を説明しており、エージェントが正確な識別子を知らない場合は、Semble型のスニペット検索が向いています。

ローカルテストでSembleの速度主張は確認できましたか？

いいえ。私のローカルuvx呼び出しでは、最初のクエリに約54秒、2つ目に約31秒かかりました。主な理由は、パッケージ、モデルの起動、インデックス作成がその場の実行を支配したためです。Sembleのベンチマーク表は、管理された測定でははるかに速い値を報告しています。ただし、私のローカル実行は性能ベンチマークではなく、ワークフロー上の証拠として扱うべきです。²⁵

ローカルテストでトークン節約の方向性は確認できましたか？

はい、ワークフローのレベルでは確認できました。Sembleは、広いリテラルrg出力よりもはるかに小さいスニペットを返し、savingsコマンドは2回の検索後に推定約38,100トークンの節約を報告しました。この節約値はSemble自身の会計方法に基づくため、独立した証明ではなくツールのテレメトリとして扱ってください。⁵

エージェントのコード検索は、なぜCodexとClaude Codeに重要なのですか？

検索が多すぎるコンテキストを流し込んだり、証拠を隠しすぎたりすると、エージェントの品質は落ちます。良いワークフローは、いつ正確検索を使うか、いつスニペット順位付き検索を使うか、いつファイル全体を開くか、結果をどう引用するかをエージェントに教えます。

チームはSembleをAGENTS.mdに追加すべきですか？

自分たちのコードベースで試してからにしましょう。最初の指示は1つで十分です。振る舞いに関する質問にはスニペット順位付き検索を使い、正確な文字列にはrgを使う、というものです。エージェントがより速く正しいファイルを見つけ、無関係な行を読む量が減るかを測定してください。

参照