codebase_search

ⓘ 事前設定が必要

codebase_search ツールはコードベースインデクシング機能モジュールに属し、使用前に埋め込みサービスプロバイダーとベクトルデータベースのデプロイなどの追加設定が必要です。

codebase_search ツールはAI埋め込み技術に基づき、コードベース全体に対して意味検索を実行します。従来のテキスト検索とは異なり、このツールは検索クエリの意味的内容を理解し、正確なキーワードの一致がなくても関連するコードを特定できます。

パラメータの説明

このツールは次の入力パラメータをサポートしています：

• query（必須）：検索要件を説明する自然言語クエリステートメント
• path（オプション）：コードベース内の特定のディレクトリに検索範囲を限定するためのディレクトリパス

機能の説明

このツールは正確なテキストマッチングではなく、意味的類似性に基づいてインデックス化されたコードベースを検索します。検索で使用された正確な単語が含まれていなくても、クエリステートメントに概念的に関連するコードブロックを発見できます。検索結果は、ファイルパス、行番号、類似度スコアを含む関連コードスニペットを返します。

適用シナリオ

• インテリジェントコードアシスタントがプロジェクト内で特定の機能に関連するコードを特定する必要がある場合
• コード実装パターンまたは類似のコード構造を見つける場合
• 例外処理、認証などの概念的なコードパターンを検索する場合
• 機能実装ロジックを理解するために未知のコードベースを探索する場合
• コードの変更やリファクタリングの影響を受ける可能性のある関連コードを特定する場合

コア機能

• 意味理解能力：正確なキーワードマッチングに依存するのではなく、意味的内容に基づいてコードを検索
• クロスプロジェクト検索：検索範囲は開いているファイルだけでなく、インデックス化されたコードベース全体をカバー
• コンテキスト付き結果：返されるコードスニペットにはファイルパスと行番号が含まれ、迅速なナビゲーションと位置決めが可能
• 類似度スコア：結果は関連性によってソートされ、0-1 の範囲の類似度スコアが付与されます
• 範囲フィルタリング：オプションの path パラメータを介して特定のディレクトリに検索を限定するサポート
• インテリジェントランキング：結果はクエリステートメントとの意味的関連性によってソート
• インターフェース統合：検索結果は構文のハイライトをサポートし、ナビゲーションリンクが含まれます
• パフォーマンス最適化：高速なベクトルベースの検索で、設定可能な結果数の制限をサポート

使用前提条件

このツールは、コードベースインデクシング機能が次のように正しく設定された場合にのみ使用できます：

• 機能が有効化：システム設定でコードベースインデクシング機能を設定する必要があります
• 埋め込みサービスプロバイダー：OpenAI APIキーを設定する必要があります
• ベクトルデータベース：Qdrantインスタンスが正常に実行され、アクセス可能である必要があります
• インデックス状態：コードベースはインデックス構築を完了している必要があります（状態：「インデックス済み」または「インデックス中」）

制限事項

• 事前設定への依存：外部サービス（埋め込みサービスプロバイダー + Qdrantベクトルデータベース）に依存して動作
• インデックス依存性：インデックス化されたコードブロックのみ検索可能
• 結果数の制限：パフォーマンスを確保するため、1回の検索で最大50件の結果を返します
• 類似度しきい値：しきい値を超える類似度の結果のみ返します（デフォルトしきい値0.4、カスタマイズ可能）
• ファイルサイズ制限：1MB未満で正常にインデックス化されたファイルのみ検索
• 言語サポート：検索効果はTree-sitterのプログラミング言語解析サポート能力に依存

実行プロセス

codebase_search ツールが呼び出されると、次のプロセスに従って実行されます：

1. 可用性の検証

• コードインデックスマネージャーがインスタンス化され、利用可能であることを検証
• システム設定でコードベースインデクシング機能が有効化されていることを確認
• インデックス設定の有効性をチェック（APIキー、Qdrantサービスアドレスなど）
• 現在のインデックス状態が検索操作をサポートしていることを検証

2. クエリステートメントの処理

• 自然言語クエリステートメントを受け取り、対応する埋め込みベクトルを生成
• コードインデックス設定と同じ埋め込みサービスプロバイダー（OpenAI）を使用
• クエリステートメントの意味的内容を数学的なベクトル表現に変換

3. ベクトル検索の実行

• Qdrantベクトルデータベース内で類似のコード埋め込みベクトルを検索
• コサイン類似度アルゴリズムを使用して最も関連性の高いコードブロックを特定
• 最小類似度しきい値（デフォルト0.4、カスタマイズ可能）を適用して結果をフィルタリング
• 最適なパフォーマンスを確保するため、結果数を50件に制限

4. パスフィルタリング（pathパラメータが指定された場合）

• 検索結果を指定されたディレクトリ内のファイルにフィルタリング
• 正確なフィルタリングを確保するために標準化されたパス比較を採用
• フィルタリングされた範囲内で、結果の意味的関連性ランキングを維持

5. 結果の処理とフォーマット

• ファイルの絶対パスをワークスペース相対パスに変換
• 「ファイルパス、行番号範囲、類似度スコア、コード内容」によって結果を構造化して整理
• AI解析とインターフェース表示の両方のフォーマット要件に適応し、構文のハイライトをサポート

6. デュアル出力フォーマット

• AI対応フォーマット：クエリステートメント、ファイルパス、スコア、コードスニペットを含む構造化テキストフォーマット
• インターフェース表示フォーマット：構文のハイライトとコードナビゲーション機能をサポートするJSONフォーマット

検索クエリのベストプラクティス

効果的なクエリパターン

推奨：概念的かつ具体的な説明

<codebase_search>
<query>ユーザー認証とパスワード検証ロジック</query>
</codebase_search>

推奨：機能を中心とした説明

<codebase_search>
<query>データベースコネクションプールの設定実装</query>
</codebase_search>

推奨：問題指向の説明

<codebase_search>
<query>APIリクエストの例外処理メカニズム</query>
</codebase_search>

非推奨：あまりにも一般的な説明

<codebase_search>
<query>関数</query>
</codebase_search>

適合性の高いクエリタイプ

• 機能説明：「ファイルアップロード処理ロジック」、「メール検証ルール」
• 技術パターン：「シングルトンパターンの実装方法」、「ファクトリメソッドの使用シナリオ」
• ビジネスドメイン：「ユーザープロフィール管理ロジック」、「支払い処理フロー」
• アーキテクチャコンポーネント：「ミドルウェアの設定方法」、「データベース移行スクリプト」

ディレクトリ範囲の限定

オプションの path パラメータを使用して、検索範囲をコードベースの特定のディレクトリに限定できます：

APIモジュール内のコードを検索：

<codebase_search>
<query>インターフェースリクエストの検証ミドルウェア</query>
<path>src/api</path>
</codebase_search>

テストファイル内のコードを検索：

<codebase_search>
<query>モックデータの構築パターン</query>
<path>tests</path>
</codebase_search>

特定の機能ディレクトリ内のコードを検索：

<codebase_search>
<query>コンポーネントの状態管理ロジック</query>
<path>src/components/auth</path>
</codebase_search>

結果の解釈

類似度スコア範囲の説明

• 0.8-1.0：高度に関連する一致で、ターゲット検索コンテンツである可能性が高い
• 0.6-0.8：良好な関連性で、強い概念的な一致度が存在
• 0.4-0.6：潜在的に関連するが、人為的な確認が必要
• 0.4未満：類似度が低すぎるため、フィルタリングされて返されない

結果構造の説明

各検索結果には次の情報が含まれます：

• ファイルパス：一致するコードが含まれるファイルのワークスペース相対パス
• スコア：関連性を示す類似度スコア（0.4-1.0の範囲）
• 行番号範囲：一致するコードブロックの開始行と終了行の番号
• コードスニペット：クエリステートメントに一致する実際のコード内容

実際のアプリケーション例

• 新機能を実装する場合、インテリジェントコードアシスタントは「認証ミドルウェア」を検索し、新しいコードを作成する前に既存の実装パターンを理解します。
• 問題をデバッグする場合、インテリジェントコードアシスタントは「API呼び出しにおける例外処理」を検索し、プロジェクト内の関連する例外処理パターンを特定します。
• コードをリファクタリングする場合、インテリジェントコードアシスタントは「データベーストランザクションの実装パターン」を検索し、すべてのデータベース操作の実装の一貫性を確保します。
• 新しいコードベースにアクセスする場合、インテリジェントコードアシスタントは「設定ロードロジック」を検索し、アプリケーションの起動初期化フローを理解します。

ツール使用例

プロジェクト全体で認証関連のコードを検索：

<codebase_search>
<query>ユーザーログインと認証ロジック</query>
</codebase_search>

特定のディレクトリ内のデータベース関連コードを検索：

<codebase_search>
<query>データベース接続とクエリ実行ロジック</query>
<path>src/data</path>
</codebase_search>

APIコード内の例外処理パターンを検索：

<codebase_search>
<query>HTTPエラーレスポンスと例外処理メカニズム</query>
<path>src/api</path>
</codebase_search>

テストツールとモックデータ構築関連のコードを検索：

<codebase_search>
<query>テスト環境セットアップとモックデータ生成</query>
<path>tests</path>
</codebase_search>

設定と環境初期化関連のコードを検索：

<codebase_search>
<query>環境変数とアプリケーション設定のロードロジック</query>
</codebase_search>