codebase-search

コードベース検索

このスキルを使うタイミング

• 主な目的が編集前のリポジトリ内のナビゲーションである場合。
• ユーザーが定義、呼び出し箇所、エントリーポイント、設定の管理元、テスト、テンプレート、コンテンツ参照、または影響範囲の候補を探す必要がある場合。
• リポジトリが十分に大きく、適当にファイルを読んでいると時間を無駄にする場合。
• ユーザーが「検索」と言っていなくても、実際の依頼が**「これはどこにあるか／何がこれを使っているか／最初に何を調べるべきか」**である場合。
• リポジトリがアプリコード、インフラ／設定、コンテンツ／テンプレート、ゲームのツール／アセットのいずれであっても、最初のステップが調査である場合。

次の場合は、このスキルを主なワークフローとして使わないでください。

• ユーザーがすでに対象箇所を特定しており、根本原因の診断を求めている場合 → debugging または log-analysis を使ってください。
• ユーザーが動作を維持したままの整理や移行計画を求めている場合 → code-refactoring を使ってください。
• ユーザーが具体的な差分や PR に対する評価を求めている場合 → code-review を使ってください。
• ユーザーがリポジトリ全体または複数コーパスにわたる永続的な構造マップを求めている場合 → graphify を使ってください。

基本方針

codebase-search は、巨大な検索チュートリアルではなく、パケットルーターのように機能するべきです。

1. 依頼を1つの主要パケットに整理します。
2. 一致結果を大量に出す前に、範囲を絞り込みます。
3. 有力なファイルだけを読みます。
4. 簡潔なエビデンスマップを返します。
5. 検索がボトルネックでなくなったら、すぐに適切な手段へ引き継ぎます。

パケットを選ぶ前に、次の補足ドキュメントを読んでください。

• references/intake-packets-and-route-outs.md
• references/search-modes.md
• references/evidence-map-template.md
• references/handoff-boundaries.md

手順

Step 1: 依頼を整理する

まず、プロンプトを次の受付形式に変換します。

codebase_search_packet:
  primary_packet: exact-text | symbol-indexed | structural | config-content | hosted-search | graph-path
  repo_shape: app | infra | content | game | mixed | unknown
  search_goal: locate | references | ownership | impact | archaeology | unknown
  scope_hint: path | package | file-type | subsystem | repo-wide | unknown
  route_after: stay-here | debugging | log-analysis | code-refactoring | code-review | graphify

実行ごとに、主要パケットを1つ選びます。2つが有力に思える場合は、不確実性を最も早く減らせる、より低コストのものを選びます。

Step 2: パケットを選ぶ

パケット	使用する場面	最適な用途	代表的なツール／形式
exact-text	ユーザーが文字列、環境変数、ルート、フラグ、クラス名の表記、エラーテキスト、またはファイルの一部を把握している場合	文字列の直接検索、設定キー、ルートパス、インポート名	rg、git grep、エディター検索
symbol-indexed	ユーザーが定義、参照、または呼び出し箇所を必要としている場合	関数／クラス／インターフェースの所有元、API の追跡、モノレポ内のナビゲーション	LSP／ワークスペースシンボル、ctags、インデックス化されたリポジトリ検索
structural	文字列そのものより構文の形式が重要な場合	クリーンアップ漏れ、安全でないパターンの一覧化、移行準備	ast-grep、Semgrep、Comby、tree-sitter 形式の検索
config-content	リポジトリの対象が設定、コンテンツ、テンプレート、フロントマター、ショートコード、シーン、アセット、またはビルドスクリプトである場合	Terraform／Kubernetes、Markdown／MDX サイト、Hugo／Next のコンテンツ、ゲームのパッケージング／設定	ファイル検出＋文字列の直接検索＋対象を絞ったスクリプト
hosted-search	リポジトリがリモート／ブラウザー中心である場合、またはリポジトリ横断の検索が重要な場合	PR の調査、ローカルにないリポジトリ、共有可能なリンク	GitHub／GitLab のホスト型検索
graph-path	依頼の本質が依存関係の追跡や永続的な構造の把握である場合	呼び出しグラフ、パスの追跡、アーキテクチャマップ、グラフレポート	graphify、コードグラフ／コードマップツール

パケットの選択ルール：

• ユーザーが具体的なトークンをすでに把握している場合は、exact-text を優先します。
• 「これはどこで定義／参照されているか？」という依頼には、symbol-indexed を優先します。
• 正規表現では大雑把すぎる場合に限り、structural を優先します。
• 実際の対象が従来型のソースコードではない場合は、config-content を優先します。
• ローカルのコンテキストがない場合は、hosted-search を優先します。
• 通常の検索では不十分な場合に限り、graph-path を優先します。

範囲を絞ったソースドキュメントに対する明示的な Jevgrep の依頼では、 jevgrep に従い、別途定められたリモートコンテンツ／コストの確認と、範囲を限定した調査を行ってください。exact-text、LSP／インデックス検索、構造検索、および既存の zvec 経由の方法が引き続き標準かつ優先されます。この任意の方法は、グラフクエリの代替にはなりません。

Step 3: すべて読む前に範囲を絞り込む

ファイルを読む前に、少なくとも1つの絞り込みを行います。

• ディレクトリまたはパッケージで絞り込む
• ファイル形式で絞り込む
• 作成されたファイルと生成物／ベンダーフォルダーを分ける
• エントリーポイント、ローダー、設定スキーマ、テスト、例、ビルドスクリプトから始める
• コンテンツ／ゲームのリポジトリでは、コードが答えを持っていると決めつける前に、メタデータとテンプレート／アセットの範囲を検索する

リポジトリの種類ごとの便利なヒューリスティック：

• アプリ → エントリーポイント、ルーター／ハンドラー、設定ローダー、テストから始める
• インフラ → モジュール／オーバーレイ／ルート設定、変数／スキーマ、デプロイ範囲から始める
• コンテンツ → コンテンツフォルダー、フロントマターのキー、パーシャル／インクルード／ショートコード／テンプレートから始める
• ゲーム → ランタイムコード、エンジン設定、シーン／アセット／ビルドスクリプト、エディター／ビジュアルグラフの参照から始める

Step 4: 検索結果をすべて読むのではなく、有力なものを読む

検索結果が返されたら、次の手順で進めます。

1. 定義または所有元である可能性が最も高いファイルを選ぶ
2. 重要な利用箇所または参照を1～3件選ぶ
3. セットアップが重要な場合は、設定／テスト／例／ビルド用ファイルを1つ選ぶ
4. ターミナル出力をそのまま貼り付けず、処理の流れを要約する

Step 5: 根拠マップを返す

既定の回答形式：

## Search brief
- Goal: [what I was locating]
- Packet: exact-text | symbol-indexed | structural | config-content | hosted-search | graph-path
- Scope: [paths/file types/packages]

## Best entry points
- `path/to/file`: why it matters
- `path/to/other-file`: why it matters

## Key evidence
- `path:line` — what it shows
- `path:line` — how it connects

## Likely flow / ownership
- entry → consumer → config/test/content surface

## Next route-out
- stay in `codebase-search` or route to the next skill

Step 6: パケット固有のヒューリスティックを使う

バグの場所を特定する依頼の場合

• エラー文字列、ルート、フラグ、または最近の変更を示すトークンから始める
• 定義と、最も有力な利用箇所を特定する
• 失敗しそうな経路を特定したら、debugging に切り替える

影響分析の場合

• まず定義を確認する
• 次に主な利用箇所を確認する
• その後、テスト／設定／ドキュメント／コンテンツの範囲を確認する
• 必ず更新する項目と影響を受ける可能性がある項目を分ける
• ユーザーが動作を変えずに構造を変更する段階になったら、code-refactoring に切り替える

設定／コンテンツの所有元を特定する場合

• まずローダー／スキーマ／テンプレートを特定する
• 次にランタイムの利用箇所、または参照先のページ／アセットを探す
• 所有元が設定、コンテンツのメタデータ、テンプレート、コードのどこにあるかを明示する

構造検索の場合

• 検索方法を平易な言葉で説明する
• AST 対応ツールを優先する
• 正規表現での近似に頼らざるを得ない場合は、信頼度の限界を明示する

コードの変遷を調査する依頼の場合

• エントリーポイント、ドキュメント、例、テスト、ビルドスクリプトから始める
• 1回の検索だけでアーキテクチャを理解したかのように振る舞わない
• ユーザーが永続的な構造マッピングを求めている場合は、graphify に切り替える

Step 7: 必要に応じて積極的に切り替える

次の作業が検索ではなくなったら切り替えます。

• 根本原因、再現、仮説 → debugging
• 生ログのトリアージ → log-analysis
• 動作を変えないクリーンアップ／codemod の計画 → code-refactoring
• 差分／PR の評価 → code-review
• 永続的なアーキテクチャグラフまたは経路追跡 → graphify

例

例1：変更前の調査

プロンプト：

認証が実装されている場所と、変更前に確認すべきファイルを教えてください。

望ましい回答形式：

• symbol-indexed または exact-text を選ぶ
• エントリーポイント、設定、テストを特定する
• 簡潔な根拠マップを返す
• 調査を終えてから、必要に応じて code-refactoring または debugging に切り替える

例2：設定／コンテンツの所有元

プロンプト：

古い料金プランの CTA ショートコードをまだ使っている MDX ページと、共有パーシャルの定義場所を教えてください。

望ましい回答形式：

• config-content を選ぶ
• コンテンツのメタデータとショートコード／テンプレートの範囲を検索する
• 元となるパーシャルと、影響を受けるページを特定する
• まず調査結果を提示する

例3：構造クエリ

プロンプト：

クリーンアップ処理がない React のエフェクトをすべて見つけてください。単純な grep は使わないでください。

望ましい回答形式：

• structural を選ぶ
• AST 対応のマッチングを優先する
• 信頼度の高い該当箇所を列挙する
• 必要に応じて、正規表現で代替した場合の限界を明示する

例 4：ゲーム／インフラの調査

プロンプト：

このリポジトリを検索して、マッチメイキングのリージョン設定がどこで定義され、どのシーンやサービスがそれを使用しているか確認してください。

適切な回答の形式：

• リポジトリの構成に応じて、config-content または symbol-indexed を選択します
• 設定の管理元と実行時の利用箇所を分けて説明します
• コードとアセット／ビルドの両方が関係する場合は、両方を明記します

ベストプラクティス

1. 質問に回答できる範囲で、最小のパケットを選びます。
2. 大量の一致結果を読む前に、対象を絞り込みます。
3. ターミナルの出力記録ではなく、エビデンスマップを返します。
4. 設定／コンテンツ／ゲームの各領域を正確に扱います。リポジトリ内のナビゲーションは、ソースコードの検索だけではありません。
5. 検索と、診断、リファクタリング、レビュー、永続的なグラフ化を切り分けます。
6. プレーンテキスト検索で構造上の意図を推定する場合は、信頼度を明記します。
7. モノレポでは、パッケージまたはサブシステムごとに調査結果をまとめます。

参考資料

• references/intake-packets-and-route-outs.md
• references/search-modes.md
• references/evidence-map-template.md
• references/handoff-boundaries.md
• GitHub Code Search の構文ドキュメント：https://docs.github.com/en/search-github/github-code-search/understanding-github-code-search-syntax
• Sourcegraph のコード検索ドキュメント：https://sourcegraph.com/docs/code_search
• ast-grep の概要：https://ast-grep.github.io/guide/introduction.html
• ripgrep ガイド：https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md