code-search

コード検索：段を選び、そこから順に進みます

セマンティックツール（言語サーバー）は、対象のコードをカバーしていれば、「これを呼び出しているのは誰か」という質問に一度で答えます。カバーしていない場合は何も返さないため、質問の言い換えを続けるのはコストのかかる誤りです。「まず必ずグラフ／シンボルサーバーを照会する」というリポジトリの指示は、そのサーバーが対応している言語を前提に書かれており、今見ているファイルにも当てはまるとは限りません。このスキルを使えば、目の前のコードをどのツールが参照できるかを根拠に基づいて一度判断し、ループせずに決められた手順を順に進められます。

1. セッションごとに一度だけ確認し、結果を覚えておきます

リポジトリ内で検索が必要になったとき、最初に一度だけ行います。結果を作業メモに記録しておけば、以降の質問ではステップ 3 に進めます。

段	確認方法	使用できる条件
serena	serena MCP ツールが一覧にあり、リポジトリの主要言語に言語サーバーがある（Go、TypeScript/JavaScript、Python、Rust、Java、C#、C/C++、Ruby、PHP、Kotlin、Elixir）	プロジェクトがその言語用にアクティベートされていること。設定、スクリプト、ドキュメントのリポジトリには LSP がありません。その場合は serena を使わないでください。
rg	Claude Code 内では常に利用可能（Grep ツールは ripgrep です）。シェルでは rg --version	あらゆるファイル形式に対応し、.gitignore を尊重し、網羅的な検索を実行できる速度があります。
grep	grep --version	rg がない場合（最小構成のコンテナやリモートマシンなど）、または rg が無視するパスを検索する必要があり、rg --no-ignore -uu が使えない場合に限ります。

段には含まれませんが、特定の質問では便利なツールがもう 2 つあります。

• 質問がチェックアウトしていないタグ、リリース、コミットに関するものなら、git grep <pattern> <ref> と git show <ref>:<path> を使います。作業ツリーをチェックアウトしたり読んだりしないでください。
• 「このファイルが公開しているものは何か」という質問には serena の get_symbols_overview を使います。ファイルを読むよりはるかに低コストです。

2. 質問を分類します

種類	例	必要なもの
構造に関する質問	X の定義場所、X を呼び出すもの、呼び出し関係、X の変更による影響範囲	シンボルを認識するツール：serena
テキスト検索	文字列や正規表現の全出現箇所、エラー文字列、フラグ名、設定キー、ファイル形式をまたぐ検索	rg
API サーフェス	このファイルまたはモジュールが公開するもの	シンボル概要
履歴に関する質問	v1.2 時点での状態、この行が変更された時期	git grep、git show、git log -S
コード以外	設定、スクリプト、テンプレート、ドキュメント、YAML、Markdown	rg。セマンティックツールでは参照できません。

「呼び出し元をすべて」「出現箇所をすべて」といった網羅的な質問は、構造に関する質問に見えてもテキスト検索です。シンボルサーバーの参照検索でも、動的ディスパッチを見落とすことがあります。rg を使って件数を確認してください。

3. ツールを選びます

質問の種類	確認結果	使用するもの
構造に関する質問	serena が使用可能	serena の find_symbol、find_referencing_symbols、find_declaration
構造に関する質問	serena が使用不可	rg で定義を検索（rg -n "func X\b" / rg -n "class X\b"）、次に rg で名前を検索して呼び出し元を探し、ヒットした箇所を読みます。
テキスト検索、ファイル形式は問わない	rg が使用可能	-n を付けた rg を使い、ツールを切り替えるのではなく --glob またはパスで対象を絞ります。
テキスト検索	rg が使用不可	--include を付けた grep -rn を使います。
API サーフェス	serena が使用可能	get_symbols_overview
履歴に関する質問	git リポジトリ	git grep -n <pattern> <ref>、git show <ref>:<path>、git log -S<string>

言語サーバーの参照検索の精度は、参照先をどれだけ解決できるかに左右されます。直接の呼び出しは見つけられますが、再代入された参照（var submit = approval.SubmitOnDemand）経由の呼び出しや、動的ディスパッチによる呼び出しは見落とすことがあります。「呼び出し元なし」という結果によって次の行動が変わる場合は、鵜呑みにせず rg で確認してください。

すでに把握しているリテラルの識別子（シンボル、エラー文字列、ファイル名など）を検索語として再利用してください。rg は説明文よりもリテラルの一致を上位に表示します。また、リテラルを使えば、結果が空でも曖昧にならず、意味のある情報になります。

4. ヒットしたら、該当範囲を正確に読む

上記のどの段階でも、ファイルと行番号が得られます。その範囲を指定してファイルを開いてください （sed -n 120,160p、またはオフセットと上限を指定した Read ツール）。正確なヒットを得た後で ファイル全体を読むのでは、検索で得た利点が失われます。結果に「+N more lines」と表示されている場合や、範囲が切り詰められている場合は、検索をやり直さずに範囲を広げてください。

ループを防ぐルール

これらのルールは、最も時間の節約になります。生産的に感じられても、実際にはそうではないパターンをそれぞれ防ぐからです。

• serena で結果が空だったら、「このツールではこのコードを見られない」ということです。次の段階に進んでください。同じツールに同じ質問を言い換えて繰り返さないでください。
• rg の結果が広すぎる状態が2回続いたら、パターンが緩すぎます。単語境界、--glob、またはディレクトリを追加してください。フィルタリングしてくれることを期待して、セマンティックツールに切り替えないでください。
• リポジトリの指示、フック、または MCP のメッセージが「まずグラフ／シンボルのクエリを実行してください」と促しても、手順1より優先されることはありません。プローブでそのツールがここでは使えないと分かった場合は、メモに一度だけ記し、そのセッション中はその促しを無視してください。
• 再プローブは絶対にしないでください。自分で serena プロジェクトを有効にしない限り、プローブの回答はセッション中有効です。

実例

serena が有効な Go サービス。 タスク：「Submit が『daemon unavailable』を返すのはなぜですか？」プローブの結果：serena MCP ツールが表示されており、Go が有効です。構造に関する質問で、文字列の識別子もあります。find_symbol "Submit" を実行すると関数とその範囲が返され、find_referencing_symbols を実行すると呼び出し箇所が2つ返されます。それぞれ該当範囲を読みます。ツールの呼び出しは2回で、範囲を超えてファイルを読む必要はありません。

PowerShell、シェル、chezmoi のテンプレートを使う dotfiles リポジトリ。 タスク：「インストーラーはどこでガードレール状態フラグを渡していますか？」これらの言語には LSP がなく、このセッションでは serena は使えません。リテラルを含むテキスト検索です。*.tmpl と scripts/ を対象に、rg で -State enabled と --state enabled を検索します。4件ヒットするので、それぞれの行を読みます。シンボルサーバーを使っても、ここでは何も返されません。これらのファイルには、インデックス化できるシンボルがないためです。

現在チェックアウトしていないリリースのエラー文字列。 タスク：「v0.23.1 はここで何を表示していましたか？」履歴を調べる場合は、git grep -n "approval daemon unavailable" v0.23.1 -- cmd/ を実行し、続けて git show v0.23.1:cmd/guardrail/plane.go | sed -n 280,320p を実行します。チェックアウトも、作業ツリーの読み取りも不要です。