smart-explore

Smart Explore

AST 解析を使用した構造的なコード探索です。このスキルは、デフォルトの探索動作を上書きします。 このスキルが有効な間は、Read、Grep、Glob の代わりに、smart_search/smart_outline/smart_unfold を主要なツールとして使用してください。

基本原則： まずインデックスを作成し、必要に応じて取得します。実装の詳細を読み込む前に、コードの全体像を把握してください。ファイルを読む前に毎回、「この内容をすべて見る必要があるか、それとも先に構造の概要を把握できるか」と考えてください。ほとんどの場合、まず全体像を把握するのが正解です。

次に呼び出すツール

このスキルは指示のみを読み込みます。MCP ツールは自分で呼び出す必要があります。次のアクションとして、以下のいずれかを実行してください。

smart_search(query="<topic>", path="./src")    -- discover files + symbols across a directory
smart_outline(file_path="<file>")              -- structural skeleton of one file
smart_unfold(file_path="<file>", symbol_name="<name>")  -- full source of one symbol

ファイルを見つけるために、最初に Grep、Glob、Read、find を実行しないでください。smart_search はディレクトリを走査し、すべてのコードファイルを解析して、ランク付けされたシンボルを1回の呼び出しで返します。Glob → Grep → Read の検索サイクルに代わるツールです。

3 層ワークフロー

ステップ 1：検索 -- ファイルとシンボルを見つける

smart_search(query="shutdown", path="./src", max_results=15)

戻り値： シグネチャ、行番号、一致理由を含む、ランク付けされたシンボルと、折りたたまれたファイルビュー（約 2～6k トークン）

-- Matching Symbols --
  function performGracefulShutdown (services/infrastructure/GracefulShutdown.ts:56)
  function httpShutdown (services/infrastructure/HealthMonitor.ts:92)
  method WorkerService.shutdown (services/worker-service.ts:846)

-- Folded File Views --
  services/infrastructure/GracefulShutdown.ts (7 symbols)
  services/worker-service.ts (12 symbols)

これは検索用のツールです。関連ファイルを見つけ、その構造も表示します。事前に Glob/find でスキャンする必要はありません。

パラメーター：

• query（文字列、必須）-- 検索する内容（関数名、概念、クラス名）
• path（文字列）-- 検索するルートディレクトリ（デフォルトは cwd）
• max_results（数値）-- 一致するシンボルの最大数。デフォルトは 20、最大は 50
• file_pattern（文字列、省略可能）-- 特定のファイル／パスに絞り込むフィルター

ステップ 2：アウトライン -- ファイル構造を把握する

smart_outline(file_path="services/worker-service.ts")

戻り値： 完全な構造の骨格 -- すべての関数、クラス、メソッド、プロパティ、インポート（ファイルあたり約 1～2k トークン）

このステップを省略する場合： ステップ 1 の折りたたまれたファイルビューで、すでに十分な構造が把握できている場合です。検索結果に含まれていないファイルで特に役立ちます。

パラメーター：

• file_path（文字列、必須）-- ファイルのパス

ステップ 3：展開 -- 実装を確認する

ステップ 1～2 で見つけたシンボルを確認します。必要なものを選び、それだけを展開してください。

smart_unfold(file_path="services/worker-service.ts", symbol_name="shutdown")

戻り値： 指定したシンボルの完全なソースコード。JSDoc、デコレーター、完全な実装を含みます（シンボルのサイズに応じて約 400～2,100 トークン）。AST ノードの境界により、シンボルのサイズにかかわらず、内容を完全に取得できます。長いメソッドが切り詰められる可能性のある Read とエージェントによる要約とは異なります。

パラメーター：

• file_path（文字列、必須）-- ファイルのパス（search/outline の戻り値と同じ）
• symbol_name（文字列、必須）-- 展開する関数／クラス／メソッドの名前

標準ツールを代わりに使う場合

smart_* ツールが適さない場合に限り、以下を使用してください。

• Grep： 完全一致する文字列／正規表現の検索（「すべての TODO コメントを検索する」、「ensureWorkerStarted はどこで定義されているか？」）
• Read： 約 100 行未満の小さなファイル、コード以外のファイル（JSON、Markdown、設定ファイル）
• Glob： ファイルパスのパターン（「すべてのテストファイルを検索する」）
• Explore agent： 6 ファイル以上にまたがる内容を統合して理解する必要がある場合、アーキテクチャの説明を作成する場合、または「このシステム全体は、最初から最後までどのように動作するのか？」といった自由形式の質問に答える場合。Smart-explore はメスのようなツールで、「これはどこか？」や「これを見せて」に答えます。機能全体にわたるファイル横断のデータフロー、設計上の判断、エッジケースを統合するものではありません。

約 100 行を超えるコードファイルでは、Read よりも smart_outline + smart_unfold を優先してください。

ワークフローの例

機能の仕組みを調べる（複数箇所にまたがる場合）：

1. smart_search(query="shutdown", path="./src")
   -> 14 symbols across 7 files, full picture in one call
2. smart_unfold(file_path="services/infrastructure/GracefulShutdown.ts", symbol_name="performGracefulShutdown")
   -> See the core implementation

大きなファイルを読み進める：

1. smart_outline(file_path="services/worker-service.ts")
   -> 1,466 tokens: 12 functions, WorkerService class with 24 members
2. smart_unfold(file_path="services/worker-service.ts", symbol_name="startSessionProcessor")
   -> 1,610 tokens: the specific method you need
Total: ~3,076 tokens vs ~12,000 to Read the full file

コードに関するドキュメントを書く（ハイブリッドワークフロー）：

1. smart_search(query="feature name", path="./src")    -- discover all relevant files and symbols
2. smart_outline on key files                           -- understand structure
3. smart_unfold on important functions                  -- get implementation details
4. Read on small config/markdown/plan files             -- get non-code context

コードの探索には smart_* ツールを、コード以外のファイルには Read を使用してください。自由に組み合わせてください。

探索してから、必要箇所を詳しく確認する：

1. smart_search(query="session", path="./src", max_results=10)
   -> 10 ranked symbols: SessionMetadata, SessionQueueProcessor, SessionSummary...
2. Pick the relevant one, unfold it

トークンの使用量

方法	トークン数	用途
smart_outline	約1,000～2,000	「このファイルには何が書かれていますか？」
smart_unfold	約400～2,100	「この関数を見せてください」
smart_search	約2,000～6,000	「コードベース全体から X をすべて見つけてください」
search + unfold	約3,000～8,000	エンドツーエンド：検索して読む（主なワークフロー）
Read（ファイル全体）	約12,000以上	本当にすべてが必要な場合
Explore agent	約39,000～59,000	複数ファイルにまたがる、説明を伴う統合

ファイルの把握にかかるトークンを4～8倍節約できます（outline + unfold と Read の比較）。Explore agent と比べると、コードベースの調査では11～18倍節約できます。クエリの範囲が狭いほど、差は広がります。27行の関数を読む場合、unfold を使えば Explore agent より55倍少ないトークンで済みます。これは、エージェントがそれでもファイル全体を読むためです。

言語サポート

Smart-explore は、構造解析にtree-sitter AST 解析を使用します。サポート対象外の言語のファイル内容を検索する場合は、rg などのテキスト検索ツールを使用してください。

同梱言語

言語	拡張子
JavaScript	.js、.mjs、.cjs
TypeScript	.ts
TSX / JSX	.tsx、.jsx
Python	.py、.pyw
Go	.go
Rust	.rs
Ruby	.rb
Java	.java
C	.c、.h
C++	.cpp、.cc、.cxx、.hpp、.hh

認識されない拡張子のファイルでは、smart_outline または smart_unfold による構造化シンボルの出力は行われません。smart_search は汎用的なファイル内容検索ではありません。拡張子フィルターによって未サポートのファイルが除外されることがあり、シンボルのないファイルはパスのみで一致します。ファイル内容を検索するには、rg などのテキスト検索ツールを使用してください。

追加言語

カスタム tree-sitter 文法は、現在 .claude-mem.json を通じて登録できません。プロジェクトの node_modules に文法をインストールしても、その拡張子の構造解析は有効になりません。smart_outline と smart_unfold で利用できるようにするには、同梱の言語マップ、文法パッケージ、シンボルクエリにサポートを追加する必要があります。

Markdown の特別なサポート

Markdown ファイル（.md、.mdx）には、一般的なプレーンテキストのフォールバックを超える特別な処理が適用されます。

• smart_outline — 見出し（#、##、###）をシンボルツリーとして抽出します。長いドキュメントをすべて読まずに移動する際に使用します。
• smart_search — 文章だけでなくコードフェンス内も検索するため、```ts ``` ブロック内の関数名をクエリしても想定どおりに動作します。
• smart_unfold — 関数本体ではなく見出しセクションを展開します。次に同じレベルの見出しが現れるまでの各セクションが、チャンクとして返されます。
• フロントマター — YAML フロントマター（先頭の --- 区切りの間にある行）は、合成シンボル frontmatter の下に smart_outline の出力として含まれます。そのため、ファイル全体を読まずに title: や description: などのメタデータを確認できます。