code-semantic-search

コードのセマンティック検索

概要

Phase 1 のベクトル埋め込みと Phase 2 のハイブリッド検索（セマンティック検索＋構造検索）を使用した、コードのセマンティック検索です。キーワードだけでなく、意味からコードを見つけます。

基本原則： コードの名前ではなく、その動作で検索します。

Phase 2：ハイブリッド検索

このスキルでは、次の 3 つの検索モードをサポートするようになりました。

1. ハイブリッド（デフォルト）：

   • セマンティック検索と構造検索を組み合わせます
   • 最も高い精度（95％以上）
   • わずかに遅くなりますが、それでも <150ms です
   • すべての検索におすすめです

2. セマンティックのみ：

   • Phase 1 のセマンティックベクトルのみを使用します
   • 最速（<50ms）
   • 概念的な検索に適しています
   • 構造が重要でない場合に使用します

3. 構造のみ：

   • ast-grep パターンのみを使用します
   • 完全一致の検索に高い精度を発揮します
   • 関数やクラスの定義を見つけるのに最適です
   • 正確な構造パターンが必要な場合に使用します

パフォーマンス比較

モード	速度	精度	最適な用途
ハイブリッド	<150ms	95%	一般的な検索
セマンティックのみ	<50ms	85%	概念
構造のみ	<50ms	100%	完全なパターン
Phase 1 のみ	<50ms	80%	レガシー（フォールバック）

使用する場合

常に使用する場合：

• 関数名がわからなくても認証ロジックを見つける場合
• エラー処理パターンを検索する場合
• データベースクエリの場所を特定する場合
• ある概念に似たコードを見つける場合
• 実装パターンを見つける場合

使用しない場合：

• 正確なテキスト一致（代わりに Grep を使用）
• ファイル名の検索（代わりに Glob を使用）
• 単純なキーワード検索（代わりに ripgrep を使用）

使用例

ハイブリッド検索（推奨）

// Basic hybrid search
Skill({ skill: 'code-semantic-search', args: 'find authentication logic' });

// With options
Skill({
  skill: 'code-semantic-search',
  args: 'database queries',
  options: {
    mode: 'hybrid',
    language: 'javascript',
    limit: 10,
  },
});

セマンティックのみの検索

// Fast conceptual search
Skill({
  skill: 'code-semantic-search',
  args: 'find authentication',
  options: { mode: 'semantic-only' },
});

構造のみの検索

// Exact pattern matching
Skill({
  skill: 'code-semantic-search',
  args: 'find function authenticate',
  options: { mode: 'structural-only' },
});

実装リファレンス

ハイブリッド検索： .claude/lib/code-indexing/hybrid-search.cjs

クエリ分析： .claude/lib/code-indexing/query-analyzer.cjs

結果のランキング： .claude/lib/code-indexing/result-ranker.cjs

統合ポイント

• developer：コードの探索、実装の発見
• architect：システムの理解、パターン分析
• code-reviewer：類似パターンの発見、一貫性の確認
• reverse-engineer：不慣れなコードベースの理解
• researcher：既存の実装の調査

絶対原則

1. 一般的な検索では、必ずハイブリッドモード（セマンティック検索＋構造検索）を使用してください — セマンティックのみでは完全一致を見逃し、構造のみでは概念的なバリエーションを見逃します。ハイブリッドなら、単一モードの 85% に対して 95% の精度が得られます。
2. キーワードをすばやく見つけるには、必ず最初に ripgrep／キーワード検索を使用してください — セマンティック検索は意味に基づくクエリに使用します。正確な文字列、関数名、ファイル名は ripgrep のほうがすばやく見つかります。
3. 意味のある自然言語クエリを使わずに、セマンティック検索を使用しないでください — 単語 1 つだけのクエリやコード構文のクエリでは、セマンティック検索の結果が不適切になります。コードの名前ではなく、動作を説明してください。
4. 精度を高めるには、必ず code-structural-search と組み合わせてください — まずセマンティック検索で幅広く見つけ、その結果から ast-grep パターンを使って正確な構造一致を探します。
5. 類似度の低い結果を確認せずに無視しないでください — 類似度スコアは概算です。珍しいパターンの場合、スコア 0.7 の結果のほうが、0.9 の結果より関連性が高いことがあります。

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
完全一致検索にセマンティック検索を使う	テキスト検索より遅く、精度も低くなります	ripgrep/Grep を使ってキーワードを完全一致で検索します
単語だけのクエリ（「auth」）	セマンティック検索には曖昧すぎて、ノイズが返ります	自然言語で説明します（「認証トークンの検証ロジック」など）
一般的な検索にセマンティック専用モードを使う	構造上のバリエーションを見逃します。精度は 85% 対 95% です	一般的なクエリにはハイブリッドモード（デフォルト）を使います
期待と異なる検索結果を無視する	セマンティック検索では、意外でも関連性のあるコードが見つかります	すべての結果を読みます。予想外の一致が最も価値のある情報であることもよくあります
構造検索と組み合わせない	概念は見つかりますが、正確なパターンは見つかりません	発見にはセマンティック検索を使い、精度を高めるには構造検索を使います

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 見つかった問題 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断されることを前提にしてください。メモリに記録されていなければ、行われなかったのと同じです。