smart-explore

smart-explore skill の概要

smart-explore ができること

smart-explore skill は、生のファイルを片っ端から読むのではなく、構造検索を軸にしたコードベース探索ワークフローです。主な役割は、フルファイルを開く前に smart_search、smart_outline、smart_unfold のような AST ベースのツールを使い、エージェントがリポジトリをより速く理解できるようにすることです。コードナビゲーション、アーキテクチャ把握、ピンポイントなデバッグ用途で smart-explore を検討しているなら、約束している価値はシンプルです。まずコードの地図を作り、読むべき箇所だけを読む、という点にあります。

smart-explore を導入すべき人

smart-explore は、見慣れないコードベースの調査を AI に任せることが多く、無駄なトークン消費や場当たり的なファイル巡回を減らしたいユーザーに向いています。特に有効なのは次のような場面です。

• コードレビューや変更影響分析
• 大規模リポジトリへのオンボーディング
• 機能名の裏にある実装本体の特定
• symbol、handler、service、call site の素早い特定
• ノイズの多い Read / Grep / Glob の探索ループ削減

なかでも最も相性がよいのは smart-explore for Code Review です。全行を読むことよりも、構造や symbol の境界を理解することが重要なレビューで特に力を発揮します。

smart-explore が本当に解決する仕事

多くのリポジトリ探索が失敗する理由は、エージェントが早い段階でファイルを読み始めてしまうからです。smart-explore はその挙動を変えます。
「関係ありそうなものが見つかるまでファイルを開く」ではなく、次の流れを基本動作として促します。

1. ディレクトリ全体を対象に一致する symbol を検索する
2. 関連ファイルの構造をアウトラインで確認する
3. 本当に必要な symbol だけを unfold する

そのため smart-explore skill は、単なる検索ショートカットではありません。フルファイルを読むべきでないタイミングを決めるための判断ルールでもあります。

smart-explore が汎用プロンプトと違う点

普通のプロンプトでも「効率よく調べて」とモデルに指示することはできますが、smart-explore はツールの実行順を明確に定め、リポジトリ探索の既定の癖を置き換えます。違いはドキュメント量の多さではなく、明示的な上書きにあります。つまり、Read、Grep、Glob、場当たり的なファイル発見ではなく、smart_search / smart_outline / smart_unfold を主経路として使う、という点です。

インストール前に確認すべきこと

導入判断で本当に重要なのは、「考え方として良いか」ではなく、「そのツール環境があるか」です。smart-explore が意味を持つのは、使っている環境で対応する MCP ツールが利用できる場合だけです。skill 自体は軽量で、ほぼ指示ベースです。価値の大半は、エージェントが実際に参照先の構造探索ツールを呼び出せるかどうかに依存します。

smart-explore skill の使い方

まずツール依存を確認する

smart-explore install を試す前に、環境で次の MCP ツールが使えることを確認してください。

• smart_search
• smart_outline
• smart_unfold

この skill はそれらを置き換えるものでも、内包しているものでもありません。変えるのはエージェントの探索戦略です。クライアント上でこれらのツール名が利用できないなら、smart-explore usage は実行というより発想レベルにとどまります。

インストール文脈と skill の場所

この skill のリポジトリ上のパスは次のとおりです。

plugin/skills/smart-explore

このリポジトリ系でよく使われるページ単位のインストールパターンは次のコマンドです。

npx skills add thedotmack/claude-mem --skill smart-explore

上流の SKILL.md には専用の install コマンドが書かれていないため、この skill コレクション向けの実用的な導入入口として上記コマンドを扱い、そのうえでローカルの skill loader と MCP 設定を確認するのが現実的です。

まず読むべきファイル

最初に確認すべきなのは次です。

• plugin/skills/smart-explore/SKILL.md

この skill には README.md、metadata.json、rules/、resources/ といった補助ファイルがありません。つまり、実用的なガイダンスの大半はこの 1 ファイルに集約されています。素早く評価できる点では便利ですが、その一方で、より深い例やエッジケース向けの補足を別ファイルに期待しないほうがよい、ということでもあります。

smart-explore の基本的な使い方パターン

この skill は 3 層構成のワークフローでできています。

1. smart_search で関連ファイルや symbol を見つける
2. smart_outline でファイル全体を開かずに構造を確認する
3. smart_unfold で必要な symbol だけを完全な形で取得する

これが smart-explore guide の実践的な中核です。最初のステップを飛ばしていきなりファイル全体を読み始めるなら、それはこの skill を意図どおりに使っていることにはなりません。

最初のプロンプトは「目的 + 範囲」で書く

弱いプロンプト:

“Find the bug in auth.”

より良いプロンプト:

“Use smart-explore on ./src to find where token refresh is implemented. Start with smart_search for refresh token, outline the top 2 matching files, then unfold the main refresh handler and summarize control flow.”

これが良い理由:

• skill の挙動を明示的に呼び出している
• 検索語を定義している
• 探索範囲を絞っている
• フルコードの前に構造確認を求めている

曖昧な目的を smart-explore 向けの良いプロンプトに変える方法

強い smart-explore usage にするなら、次の情報を含めるのが有効です。

• トピック名または機能名
• 検索ルートのパス
• 望ましい結果件数
• discovery、review、tracing、extraction のどれをしたいか
• 見つかった場合に unfold したい symbol

テンプレート:

“Use smart-explore in <path>. Search for <concept>, return up to <n> ranked symbols, outline the most relevant files, then unfold the symbol most likely responsible for <job-to-be-done>. Avoid reading full files unless the outline is insufficient.”

smart-explore for Code Review に最適なワークフロー

コードレビューでは、コードベースの文脈が不明なまま、いきなり「差分全体をレビューして」と頼まないほうが得策です。よりよい順序は次のとおりです。

1. 変更に関係する feature、class、endpoint、function 名を検索する
2. 触られているファイルをアウトラインして周辺構造を把握する
3. 変更された symbol または隣接 symbol だけを unfold する
4. 変更ロジックを近くの interface、validator、caller と比較する
5. symbol レベルの文脈で足りないときだけフルファイルを読む

これによりノイズを抑えつつ、「変更されたコードが何に接続しているのか」をレビューしやすくなります。

まず smart_search を使うべき場面

smart_search は、概念は分かっているがファイルの場所が分からないときに使います。相性のよいクエリは次のようなものです。

• 機能名
• endpoint 名
• エラーメッセージ
• ドメイン用語
• メソッド名
• 状態遷移

この skill は、構造検索が使える状況で初動に Grep、Glob、Read、find を使うことを明確に勧めていません。理由は判断の質です。生のテキストヒットより、順位づけされた symbol 一致のほうが、次の行動に結びつきやすいからです。

次に smart_outline を使うべき場面

smart_outline は、有力なファイル候補は見つかったものの、まだ実装詳細までは取りに行きたくないときに使います。特に次を知りたいときに適切です。

• そのファイルにどんな class や function があるか
• 目当ての symbol が本当にそこにあるか
• トップレベル構造の始まりと終わりがどこか
• ファイル全体を読む価値があるか

このステップは、とくに大きなファイルでトークン消費を抑えるのに有効です。

smart_unfold を使うべき場面

smart_unfold は、必要なロジックを含んでいそうな symbol を特定したあとに使います。次のような対象を確認するうえで、最もシグナルが高い方法です。

• 1 つの handler
• 1 つの service method
• 1 つの resolver
• 1 つの reducer
• 1 つの utility function

早すぎる段階で unfold すると、本当に見るべき symbol を見逃す可能性があります。逆に遅すぎると、明らかに有力なファイルに対しても延々とアウトラインだけを続けて時間を無駄にします。

出力品質を上げる実践的なプロンプト例

例 1:

“Use smart-explore on ./src to locate the shutdown sequence. Search shutdown, outline the top relevant file, then unfold the main shutdown function and identify its dependencies.”

例 2:

“Use smart-explore for Code Review on ./app. Search for rate limit, outline matching middleware files, then unfold the enforcement symbol and summarize request flow and likely edge cases.”

例 3:

“Use smart-explore to find where email verification is triggered. Search verify email, rank up to 10 results, outline the top 3 files, and unfold the symbol that sends or schedules the verification.”

smart-explore skill の FAQ

すでに良いプロンプトを書けるなら smart-explore は導入する価値があるか

はい。前提として、期待されるツールが環境で使えるなら価値があります。smart-explore の利点は、単に言い回しが良くなることではありません。探索ポリシー自体を強くする点にあります。ファイルを 1 つずつさまよう代わりに、構造ベースの発見を優先させるので、実際に無駄時間が生まれやすい箇所を減らせます。

smart-explore は初心者向きか

中程度です。考え方自体はシンプルですが、初心者は symbol 発見とファイル読解の違いが分からなかったり、必要な MCP ツール対応がないまま導入して詰まったりしがちです。初めて使うなら、リポジトリ全体タスクではなく、狭い機能単位の検索から始めるのが安全です。

smart-explore を使わないほうがよいのはどんなときか

次のような場合は smart-explore を見送るほうがよいです。

• 環境に smart_search、smart_outline、smart_unfold がない
• 調べるべき小さなファイルと symbol がすでに正確に分かっている
• リポジトリが極端に小さく、構造探索の準備よりフルファイル読解のほうが安い
• タスクの中心がコード構造ではなく文章・説明である

smart-explore は普通の Grep や Read とどう違うか

Grep はテキスト一致を返し、Read は生のファイル内容を返します。smart-explore はその前段で、まず symbol レベルのコード構造を見つけて確認するために設計されています。通常はそのほうが、ランキングの質、境界の分かりやすさ、不要なフルファイル読込の少なさで優位です。

smart-explore は大規模モノレポに向いているか

はい。バックエンドのツール性能が環境上で十分なら、これは最も相性のよいケースの 1 つです。リポジトリが大きすぎて素朴なブラウズが破綻しやすいほど、「まず索引化し、必要になったら取る」という考え方が効いてきます。

smart-explore for Code Review だけに使ってもよいか

はい。むしろコードレビューは特に分かりやすい用途です。レビュー担当者は、変更されたファイルを毎回フルで読み直すことなく、周辺 symbol や呼び出し構造を把握したい場面が多いからです。レビュー観点が「この変更は何につながっているのか」であるなら、smart-explore for Code Review はかなり相性がよい選択です。

smart-explore skill を改善するには

検索語は広くするより賢くする

smart-explore の出力品質は、最初のクエリに大きく左右されます。良いクエリは、たいていドメイン用語と動作を組み合わせています。たとえば次のようなものです。

• refresh token
• session revoke
• password reset
• shutdown
• rate limit

auth や user のように広すぎる語は、ノイズの多い symbol 集合を返しやすく、その後のワークフロー全体を弱めます。

必ずパス範囲を含める

smart-explore usage を改善する最も簡単な方法の 1 つは、./src、./app、あるいは package ディレクトリのように検索ルートを明示することです。スコープがないと、特に大きなリポジトリでは結果がノイジーになりやすく、速度面でも不利になります。

ランキングと選定ステップを要求する

単に検索を頼むだけでは不十分です。選ばせるところまで要求してください。例:

“Search for invoice export in ./services, rank the top 8 symbols, explain which 2 are most likely relevant, then outline those files before unfolding one symbol.”

こうすることで選定の段階が強制され、やみくもなツール実行を減らせます。

早すぎるフルファイル読解を避けるために outline を使う

よくある失敗は、最初の検索結果を見た直後にフルファイル読解へ戻ってしまうことです。smart-explore の価値を引き出すには、次のように明示しておくのが有効です。

“Do not read full files unless the outline does not provide enough context.”

これにより、ワークフローをこの skill 最大の強みと整合させやすくなります。

変更認識型プロンプトで smart-explore for Code Review を改善する

コードレビューでは、変更箇所とアーキテクチャ上の問いをセットで渡すと効果的です。例:

“Use smart-explore on ./src/payments to review the new refund path. Search refund, outline affected files, unfold the entry-point symbol and the main downstream processor, then check for validation, idempotency, and error handling gaps.”

これは “review this code” よりも優れています。レビューリスクに向けて構造探索の方向性を明確にできるからです。

主な失敗パターンを把握しておく

起こりやすい問題は次のとおりです。

• MCP ツール対応がない
• 検索語が曖昧すぎる
• 検索結果からそのまま結論に飛ぶ
• ファイルを outline していないため、誤った symbol を unfold する
• リポジトリが小さいのに structure-first 手法を使ってオーバーヘッドを増やす

どれも対処可能ですが、SKILL.md 上の細かな出来栄えより、実運用ではこちらのほうが重要です。

やり直すより、最初の結果から絞り込む

良い smart-explore guide の実践は、最初から完璧を狙うことではなく、反復的に絞ることです。1 回目の実行後は次を試してください。

• クエリをより具体的な語に直す
• パスを狭める
• max_results を増減する
• 2 番手の候補ファイルも outline する
• 最初の一致だけでなく、隣接する symbol も unfold する

そのほうが、ワークフローを捨ててランダムなファイル読解に戻るより、たいてい良い結果につながります。

smart-explore skill 自体を強くするには

現状の smart-explore ドキュメントは実用には足りますが、厚みはありません。次が加わると導入しやすさはかなり上がります。

• 明示的な install セクションを 1 つ追加する
• search から unfold までの初心者向け例を 1 つ入れる
• コードレビュー例を 1 つ入れる
• 「使わないほうがよい場面」を短く 1 セクション入れる
• MCP / ツール前提条件を冒頭で明記する

こうした追加があれば、導入前の手探りが減り、smart-explore skill を最初の 1 回目から正しく発火させやすくなります。