smart-explore

smart-explore skill 概覽

smart-explore 是做什麼的

smart-explore skill 是一套以結構化搜尋為核心的程式碼庫探索流程，不是靠直接讀完整檔案來摸索。它的主要用途，是讓 agent 在載入整個檔案之前，先透過 AST 型工具，例如 smart_search、smart_outline 與 smart_unfold，更快理解 repository 的結構。如果你正在評估 smart-explore 是否適合用來做程式碼導覽、架構探索，或有目標的除錯，它的核心承諾其實很簡單：先把程式碼地圖畫出來，再只讀真正有關的部分。

哪些人適合安裝 smart-explore

smart-explore 特別適合那些經常要求 AI 檢查陌生程式碼庫、又希望少浪費 tokens、少做無目的檔案翻閱的使用者。它尤其適合以下情境：

• code review 與變更影響分析
• 大型 repository 的 onboarding
• 從功能名稱反查真正實作位置
• 快速定位 symbols、handlers、services 與 call sites
• 減少高噪音的 Read／Grep／Glob 探索循環

其中最契合的場景之一是 smart-explore for Code Review：當你更在意結構、symbol 邊界與呼叫關係，而不是逐行把所有程式碼看完時，它的價值會最明顯。

這個 skill 真正解決的工作是什麼

多數 repository 探索失敗，不是因為工具不夠，而是 agent 太早開始讀檔。smart-explore 改變的正是這個習慣。它不是讓你「一直開檔，直到看到像是相關的內容」，而是推動以下流程：

1. 先在目錄範圍內搜尋相符的 symbols
2. 再查看相關檔案的結構 outline
3. 最後只展開你真正需要的 symbol

因此，smart-explore skill 不只是搜尋捷徑，而是一條明確的判斷規則：哪些時候不該直接讀完整檔案。

smart-explore 和一般 prompt 有什麼不同

一般 prompt 也許會叫模型「更有效率」，但 smart-explore 提供的是明確的工具順序，以及一套可以取代預設 repository 瀏覽習慣的方法。它的差異不在於文件寫得更長，而在於它明白覆寫了預設行為：把 smart_search／smart_outline／smart_unfold 當成主要探索路徑，而不是依賴 Read、Grep、Glob 或臨時性的檔案搜尋。

安裝 smart-explore 前真正該先確認的事

是否採用 smart-explore，最大的問題其實不是「這個想法好不好」，而是「我的工具環境對不對」。只有當你的環境有提供對應的 MCP 工具時，smart-explore 才真正有意義。這個 skill 本身很輕量，主要是靠指令與流程驅動；它能不能發揮價值，取決於你的 agent 是否真的能呼叫它提到的那些結構化探索工具。

如何使用 smart-explore skill

先確認 smart-explore 依賴的工具是否存在

在嘗試任何 smart-explore install 流程之前，先確認你的環境支援以下 MCP 工具：

• smart_search
• smart_outline
• smart_unfold

這個 skill 不會取代這些工具，也不會把它們打包進來。它做的是改變 agent 的探索策略。如果你的 client 裡看不到這些工具名稱，那麼 smart-explore usage 大多只能停留在概念層面，而無法真正執行。

安裝脈絡與 smart-explore skill 所在位置

這個 skill 在 repository 內的路徑是：

plugin/skills/smart-explore

這個 repo 系列頁面常見的安裝方式是：

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

由於上游 SKILL.md 本身沒有提供獨立的安裝指令，因此實務上可以先把上面的命令視為這組 skills 的安裝入口，再進一步確認你的本機 skill loader 與 MCP 設定是否正確。

先讀這個檔案

請先從這裡開始：

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

這個 skill 沒有額外的 README.md、metadata.json、rules/ 或 resources/ 檔案可供輔助，所以幾乎所有可用的指引都集中在這一個檔案裡。這對快速評估很方便，但也代表你不應期待在其他地方找到更深入的範例或邊界情境說明。

smart-explore 的核心使用模式

這個 skill 建立在一個三層流程上：

1. 用 smart_search 找出相關檔案與 symbols
2. 用 smart_outline 在不載入整個檔案的前提下查看檔案結構
3. 用 smart_unfold 抓出你真正需要的 symbol 完整內容

這就是 smart-explore guide 最實際的核心。如果你跳過第 1 步，直接開始讀完整檔案，那其實就不算是在照這個 skill 的設計方式使用它。

第一個 smart-explore prompt 應該同時包含目標與範圍

較弱的 prompt：

「Find the bug in auth。」

較強的 prompt：

「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.」

這樣比較好的原因是：

• 它明確要求 agent 啟用這個 skill 的行為模式
• 它定義了搜尋詞
• 它縮小了探索路徑
• 它要求先看結構，再看完整程式碼

如何把模糊需求改寫成好的 smart-explore prompt

想讓 smart-explore usage 更穩定，prompt 最好包含以下資訊：

• 主題或功能名稱
• 搜尋根路徑
• 希望回傳的結果數量
• 你要的是 discovery、review、tracing 還是 extraction
• 如果找到候選目標，哪些 symbols 應該被 unfold

範本：

「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 的最佳工作流程

做 code review 時，如果程式碼庫脈絡還不清楚，不要一開始就叫 agent「review 整個 diff」。更好的順序是：

1. 先搜尋這次變更碰到的 feature、class、endpoint 或 function 名稱
2. outline 被碰到的檔案，理解周邊結構
3. 只 unfold 變更過的 symbols 或相鄰 symbols
4. 把變更後的邏輯，與附近的 interfaces、validators 或 callers 對照
5. 只有在 symbol 層級的上下文還不夠時，才去讀完整檔案

這樣可以降低噪音，也能幫 reviewer 先搞清楚改動到底掛在哪個結構上。

什麼時候應該先用 smart_search

當你知道某個概念，但還不知道確切檔案位置時，就該先用 smart_search。適合的查詢包括：

• feature 名稱
• endpoint 名稱
• 錯誤訊息
• 領域術語
• method 名稱
• 狀態轉移

只要有結構化搜尋可用，這個 skill 就明確不建議你在初始探索階段先用 Grep、Glob、Read 或 find。原因不是這些工具不能用，而是決策品質通常比較差：經過排序的 symbol 比對結果，往往比純文字命中更能直接帶你找到下一步。

什麼時候接著用 smart_outline

當你已經找到可能相關的檔案，但還不想立刻深入看實作細節時，就該用 smart_outline。這一步特別適合用來確認：

• 檔案裡有哪些 classes 或 functions
• 目標 symbol 是否真的存在於該檔案
• 頂層結構從哪裡開始、到哪裡結束
• 這個檔案值不值得完整讀取

在大型檔案裡，這一步尤其有價值，因為直接讀完整內容很容易浪費 tokens。

什麼時候使用 smart_unfold

當你已經辨識出最可能包含目標邏輯的 symbol 之後，再使用 smart_unfold。這通常是檢查以下內容時訊號最強的方式：

• 單一 handler
• 單一 service method
• 單一 resolver
• 單一 reducer
• 單一 utility function

如果你太早 unfold，可能會錯過更值得看的 symbol；如果太晚 unfold，則可能會在那些其實早已明顯相關的檔案上花太多時間做 outline。

能提升 smart-explore 輸出品質的實用 prompt 範例

Example 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.」

Example 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.」

Example 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 常見問題

如果我本來就很會寫 prompt，smart-explore 還值得裝嗎

值得，前提是你的環境支援它所依賴的工具。smart-explore 的好處不只是 prompt 寫法比較漂亮，而是它提供了更強的探索策略。它會讓 agent 優先採用結構化發現，而不是一個檔案一個檔案亂翻；而後者往往才是真正浪費時間的來源。

smart-explore 對新手友善嗎

算是中等。概念本身不難，但如果新手不清楚 symbol discovery 和 file reading 的差別，或是在沒有必要 MCP 工具支援的情況下就先安裝 skill，很容易卡住。如果你剛開始用，建議先從單一、範圍明確的 feature 搜尋開始，不要一上來就做整個 repository 的任務。

什麼情況不該用 smart-explore

以下情況建議跳過 smart-explore：

• 你的環境沒有 smart_search、smart_outline 與 smart_unfold
• 你已經知道要檢查的精確小檔案和 symbol
• repository 小到直接讀完整檔案的成本比結構化前置更低
• 你的任務重點在文字內容，而不是程式碼結構

smart-explore 和一般的 Grep 或 Read 差在哪

Grep 給你的是文字命中結果，Read 給你的是原始檔案內容。smart-explore 的設計則是先在 symbol 層級上找出程式碼結構並做檢查。這通常代表更好的排序、更清楚的邊界，以及更少不必要的完整檔案載入。

smart-explore 適合大型 monorepo 嗎

適合，這正是它最匹配的場景之一，前提是底層工具在你的環境中表現穩定。當 repo 大到不能靠直覺式瀏覽時，「先索引、再按需抓取」這種思維就特別有價值。

我可以只把 smart-explore 用在 Code Review 嗎

可以。事實上，code review 正是最清楚、最有代表性的使用場景之一，因為 reviewer 常常需要理解相鄰 symbols 與呼叫結構，卻不想把每個被修改的檔案都從頭到尾重讀一遍。當你的 review 問題是「這個改動到底連到哪裡」時，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，最簡單有效的方法之一，就是明確指定搜尋根目錄，例如 ./src、./app，或某個 package 目錄。沒有範圍限制時，結果通常會更雜、更慢，尤其是在大型 repo 裡更明顯。

不只叫 agent 搜尋，也要它幫你做選擇

不要只是要求 agent 去 search，也要要求它判斷。例子如下：

「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 拿到更高價值，最好明確告訴 agent：

「Do not read full files unless the outline does not provide enough context.」

這樣才能讓整個流程維持在這個 skill 的主要優勢上。

用 change-aware prompt 提升 smart-explore for Code Review 的效果

做 code review 時，最好把變更區域和架構問題一起寫進 prompt。例子如下：

「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」好得多，因為它會把結構化探索直接對準真正有 review 風險的地方。

注意 smart-explore 最常見的失敗模式

最容易出問題的地方包括：

• 缺少 MCP 工具支援
• 搜尋詞太模糊
• 從搜尋結果直接跳到結論
• 因為沒有先 outline 檔案，導致 unfold 到錯的 symbol
• 在太小的 repo 上使用這個 skill，讓 structure-first 方法反而增加額外成本

這些問題都能修正，但它們對實際效果的影響，遠比 SKILL.md 的文字修飾更關鍵。

第一次結果不理想時，應迭代收斂，不要整個重來

好的 smart-explore guide 使用方式，是逐步收斂。第一次跑完之後，你可以：

• 用更精確的詞重新查詢
• 縮小搜尋路徑
• 增加或減少 max_results
• 再 outline 第二個候選檔案
• unfold 相鄰的 symbol，而不只看第一個命中結果

這通常比直接放棄流程、改回隨機讀檔更有效。

如果要讓 smart-explore skill 本身更強，還缺什麼

目前的 smart-explore 文件雖然可用，但偏精簡。若要讓這個 skill 更容易被採用，建議補上：

• 一個明確的安裝區段
• 一個從 search 到 unfold 的新手範例
• 一個 code review 範例
• 一個簡短的「什麼情況不適合使用」區段
• 一段放在前面的 MCP／工具前置需求說明

這些補強可以減少安裝前的猜測成本，也能讓使用者第一次就更容易正確觸發 smart-explore skill。