codebase-exploration

SocratiCode コードベースの探索

SocratiCode MCP ツールを使って、コードベースを効率よく探索します。基本原則は次のとおりです。 読む前に検索する — インデックスは数ミリ秒でコードベースの地図を示します。ファイルを直接読むのはコストが高く、コンテキストも消費します。

ワークフロー

1. ほとんどの探索は codebase_search から始めます

ハイブリッドなセマンティック検索とキーワード検索（ベクトル検索＋BM25、RRF による統合）を1回の呼び出しで実行します。

• 全体像をつかむための広いクエリ：「認証はどのように処理されるか」「データベース接続のセットアップ」「エラー処理のパターン」
• シンボルを検索するための具体的なクエリ：正確な関数名、定数名、型名
• どのファイルを読むかは検索結果から判断してください。推測でファイルを開かないでください
• fileFilter で対象を1つのファイルに絞るには、結果ヘッダーに表示されたパスをそのまま指定してください。ディレクトリ、glob、ルート以下のファイルの名前だけを指定しても一致しません
• languageFilter で対象を1つの言語に絞るには、結果ヘッダーに角括弧付きで表示されたラベルをそのまま指定してください（例：typescript。ts ではありません）
• minScore（デフォルトは0.10）を調整して、精度と再現率のバランスを取ってください。結果を増やすには値を下げ、より厳密に一致させるには値を上げます

代わりに grep を使う場合：正確な識別子、エラー文字列、正規表現パターンがすでにわかっているなら、grep／ripgrep のほうが高速で正確です。意味的な隔たりを埋める必要がありません。探索や概念的な質問、どのファイルを調べるべきかわからない場合は、codebase_search を使ってください。

2. インポートをたどる前にグラフを確認します

ファイルの内容を詳しく調べる前に、codebase_graph_query を使って、そのファイルが何をインポートしているか、また何に依存されているかを確認します。これにより、推移的な依存関係を不必要に読むのを防げます。

• codebase_graph_query — 任意のファイルのインポート元と依存先を確認します（相対パスを渡します）
• codebase_graph_stats — アーキテクチャの概要を確認します。ファイル数、エッジ数、最も多く接続されたファイル、孤立ファイル、言語の内訳などを表示します
• codebase_graph_circular — 循環依存を検出します（微妙な実行時バグの原因となるため、予期しない動作をデバッグするときは事前に確認してください）
• codebase_graph_visualize — 言語ごとに色分けされた Mermaid 図を表示し、循環依存は赤色で強調します。代わりに、mode: "interactive" を渡すと、自己完結型の HTML エクスプローラーを開きます（ファイルとシンボルの表示、影響範囲のオーバーレイ、検索、PNG エクスポートに対応し、オフラインで動作します）

グラフはインデックス作成後に自動構築されます。codebase_graph_status を使って、グラフの準備ができているか確認してください。SOCRATICODE_WATCHER=manual または off の場合、グラフクエリは存在しないグラフを作成しません。明示的に要求された場合は、codebase_graph_build を実行してください。

3. 検索で絞り込んでからファイルを読みます

検索結果から対象ファイルが1〜3個に絞れたら、関連する箇所だけを読みます。関連があるかどうかを確かめるためだけにファイルを読んではいけません。まず検索してください。

codebase_search を1回呼び出すだけで、コードベース全体からランキング済みの重複なしスニペットが数ミリ秒で返されます。ごくわずかなトークンコストでコードベースの広範な見取り図を得られるため、推測でファイルを開くよりもはるかに効率的です。

4. コード以外の知識にはコンテキストアーティファクトを活用します

プロジェクトでは .socraticodecontextartifacts.json 設定ファイルを定義して、データベーススキーマ、API 仕様、インフラ設定、アーキテクチャ文書など、ソースコード外にあるプロジェクトの情報を利用可能にできます。

• codebase_context — 利用可能なアーティファクトを一覧表示します（名前、説明、パス、インデックスの状態）
• codebase_context_search — すべてのアーティファクトを対象にセマンティック検索します（artifactName で絞り込むこともできます）
• アーティファクトは最初の検索時に自動でインデックス化され、古くなっているかどうかも自動検出されます

早い段階で codebase_context を実行して、利用可能な情報を確認してください。データベース構造、API コントラクト、インフラについて質問する前に、codebase_context_search を使ってください。

5. 問題があるように見える場合はステータスを確認する

• codebase_status — インデックスのステータス、進行状況、ウォッチャーの状態、グラフのステータスを確認します
• 検索結果がない場合、プロジェクトがまだインデックス化されていない可能性があります
• ウォッチャーが無効の場合、結果が古い可能性があります — codebase_update を実行してください。ステータスに無効と表示されていない場合に限り、ウォッチャーを開始してください
• スナップショットモード（SOCRATICODE_WATCHER=off と SOCRATICODE_AUTO_RESUME=off の組み合わせ）では、明示的に更新するまで結果が古いままなのは想定どおりです。ウォッチャーを有効化したり、開始したりしないでください。
• Git モード（SOCRATICODE_WATCHER=git）では、検索、グラフ、ステータスのリクエストに更新状態が表示されます。保留中、失敗、未検証の結果を最新のものとして扱わないでください。Git の状態遷移によって更新が開始されます。作業ツリーの編集内容をただちに更新するには、codebase_update を使用してください。ファイルウォッチャーは開始しないでください。

6. すべてのツールの概要を確認する

• codebase_about — SocratiCode のすべてのツールと一般的なワークフローのクイックリファレンス

目的 → ツールのクイックリファレンス

目的	ツール
コードベースの機能や、ある機能の所在を把握する	codebase_search（広範なクエリ）
特定の関数、定数、型を見つける	codebase_search（正確な名前）または grep
正確なエラーメッセージ、ログ文字列、正規表現パターンを見つける	grep / ripgrep
あるファイルが何をインポートしているか、またはそのファイルに何が依存しているかを確認する	codebase_graph_query
アーキテクチャの概要（ファイル、エッジ、最も多く接続された要素）を確認する	codebase_graph_stats
循環依存を見つける	codebase_graph_circular
モジュール構造をテキスト形式／Mermaid 形式で可視化する	codebase_graph_visualize
視覚的／インタラクティブ／共有可能なグラフを求められた場合	codebase_graph_visualize mode="interactive"
グラフの構築ステータスを確認する	codebase_graph_status
インデックスが最新か確認する	codebase_status
利用可能なスキーマ、仕様、設定を見つける	codebase_context
データベースのテーブル、API エンドポイント、インフラ設定を見つける	codebase_context_search
すべてのツールの概要をすばやく確認する	codebase_about

各ツールのパラメーターの詳細については、references/tool-reference.md を参照してください。