smart-explore

smart-explore 技能概览

smart-explore 是做什么的

smart-explore 是一套围绕结构化搜索构建的代码库探索工作流，不是靠直接通读文件来摸索。它的核心作用，是让代理在加载完整文件之前，先借助 smart_search、smart_outline 和 smart_unfold 这类基于 AST 的工具，更快理解仓库结构。如果你正在评估 smart-explore 是否适合用于代码导航、架构梳理或定向排查问题，它最关键的承诺其实很直接：先把代码地图画出来，再只读真正相关的部分。

哪些人适合安装 smart-explore

如果你经常让 AI 去分析陌生代码库，并且希望减少 token 浪费、少做漫无目的的文件翻找，那么 smart-explore 会很适合你。它尤其适合这些场景：

• 代码审查与变更影响分析
• 进入大型仓库时的快速上手
• 根据功能名称反查真实实现位置
• 快速定位符号、handler、service 和调用点
• 减少高噪音的 Read / Grep / Glob 探索循环

其中最匹配的场景之一是 smart-explore for Code Review：这类任务里，理解结构和符号边界，往往比逐行通读更重要。

smart-explore 真正解决的任务是什么

大多数仓库探索之所以效率低，不是因为模型不会搜，而是因为它太早开始读文件。smart-explore 要改变的正是这个习惯。它不是让代理“打开文件直到看到点有用的东西”，而是推动这样一套流程：

1. 先在目录范围内搜索匹配的符号
2. 再查看相关文件的结构轮廓
3. 最后只展开你真正需要的那个符号

所以，smart-explore skill 不只是一个搜索捷径，它更像是一条判断规则：什么时候不该直接读完整文件。

smart-explore 与普通提示词有什么不同

普通 prompt 也能告诉模型“提高效率”，但 smart-explore 给出的不是泛泛建议，而是明确的工具调用顺序，以及对默认仓库浏览习惯的替代方案。它的差异点不在于文档更长，而在于它明确要求：把 smart_search / smart_outline / smart_unfold 作为主要探索路径，而不是优先使用 Read、Grep、Glob 或临时性的文件遍历。

安装 smart-explore 前最需要确认什么

决定要不要采用 smart-explore，真正关键的问题不是“这个思路好不好”，而是“我的工具环境是否匹配”。只有在你的环境暴露了对应的 MCP 工具时，smart-explore 才有意义。这个技能本身很轻量，主要靠指令驱动；它的价值，取决于你的代理是否真的能调用它引用的那些结构化探索工具。

如何使用 smart-explore 技能

先确认 smart-explore 依赖的工具是否可用

在尝试任何 smart-explore install 流程之前，先确认你的环境支持这些 MCP 工具：

• smart_search
• smart_outline
• smart_unfold

这个技能不会替代这些工具，也不会把它们一起打包安装。它改变的是代理的探索策略。如果你的客户端里根本没有这些工具名，那么 smart-explore usage 就只能停留在思路层面，无法真正落地执行。

安装上下文：smart-explore 在哪里，怎么装

这个技能在仓库中的路径是：

plugin/skills/smart-explore

这个仓库系列页面里常用的安装方式是：

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

由于上游 SKILL.md 本身没有写独立的安装命令，因此更实际的做法是：先把上面的命令当作这个技能集合的安装入口，再回头确认你本地的 skill loader 和 MCP 配置是否正常。

先读这个文件

优先看：

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

这个技能没有额外的 README.md、metadata.json、rules/ 或 resources/ 文件来补充说明，所以几乎所有真正可用的指引都集中在这一个文件里。好处是评估起来很快；但也意味着你不要预期仓库里还有更深入的示例或边界场景说明。

smart-explore 的核心使用模式

这个技能围绕一个三层工作流展开：

1. 用 smart_search 发现相关文件和符号
2. 用 smart_outline 在不加载整个文件的情况下查看文件结构
3. 用 smart_unfold 完整获取你真正需要的那个符号

这就是 smart-explore guide 的实用核心。如果你跳过第 1 步，一上来就开始读整个文件，那其实并没有按这个技能的设计方式在使用它。

第一个 smart-explore 提示词应该写成“目标 + 范围”

弱提示词：

“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.”

为什么这样更好：

• 它明确要求代理触发这个技能的行为
• 它给出了搜索词
• 它限制了探索路径
• 它要求先看结构，再看完整代码

如何把模糊目标改写成好用的 smart-explore prompt

想获得更稳定的 smart-explore usage，建议在提示词里包含这些输入：

• 主题或功能名称
• 搜索根路径
• 希望返回的结果数量
• 你要的是发现、审查、追踪还是抽取
• 如果找到目标，应优先展开哪些符号

模板：

“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 场景中，如果你对代码库上下文还不清楚，不要一开始就让代理“review 整个 diff”。更有效的顺序通常是：

1. 先搜索变更涉及的功能、类、endpoint 或函数名
2. 再 outline 相关文件，理解周边结构
3. 只 unfold 被修改的符号或其相邻符号
4. 将变更逻辑与附近的接口、校验器或调用方做对照
5. 只有在符号级上下文仍然不够时，才去读完整文件

这样可以显著降低噪音，也更有助于审查者判断“这段改动到底挂在哪条链路上”。

什么时候应该先用 smart_search

当你知道一个概念，但不知道它具体在哪个文件里时，先用 smart_search。典型查询包括：

• 功能名
• endpoint 名称
• 错误消息
• 领域术语
• 方法名
• 状态转换名

这个技能明确不建议在初始发现阶段优先使用 Grep、Glob、Read 或 find，前提是结构化搜索可用。原因不只是效率，而是决策质量：经过排序的符号匹配结果，通常比原始文本命中更适合下一步判断。

什么时候接着用 smart_outline

当你已经找到一个看起来靠谱的文件，但暂时还不想看实现细节时，就该用 smart_outline。以下情况尤其适合：

• 你想知道文件里有哪些类或函数
• 你要确认目标符号是否真的在这个文件中
• 你需要知道顶层结构从哪里开始、到哪里结束
• 你在判断这个文件值不值得完整阅读

对于大文件来说，这一步尤其有价值，因为直接全量读取往往很浪费 token。

什么时候使用 smart_unfold

在你已经锁定“这个符号大概率包含我要找的逻辑”之后，再使用 smart_unfold。这是查看以下内容时信噪比最高的方式：

• 单个 handler
• 单个 service method
• 单个 resolver
• 单个 reducer
• 单个 utility function

如果你太早 unfold，可能会错过更关键的符号；如果太晚才 unfold，又可能把时间浪费在已经明显相关的文件结构浏览上。

能明显提升输出质量的 smart-explore 提示词示例

示例 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 技能 FAQ

如果我本来就很会写 prompt，还有必要安装 smart-explore 吗

有必要，前提是你的环境支持它依赖的工具。smart-explore 的价值不只是“措辞更好”，而是它提供了一套更强的探索策略。它会让代理优先做结构化发现，而不是在文件之间来回乱逛；而后者往往才是时间和 token 真正被浪费的地方。

smart-explore 对新手友好吗

算是中等友好。思路本身不复杂，但如果你还不理解“发现符号”和“直接读文件”的区别，或者在没有所需 MCP 工具支持的情况下就直接安装，那很容易卡住。如果你是新手，建议先从一个范围很窄的功能搜索开始，而不是一上来就扔整个仓库给它。

什么情况下不该用 smart-explore

以下情况建议跳过 smart-explore：

• 你的环境没有 smart_search、smart_outline 和 smart_unfold
• 你已经明确知道要看的就是哪个很小的文件和哪个精确符号
• 仓库非常小，直接读完整文件比搭结构化流程更省事
• 你的任务更偏 prose，而不是偏代码结构分析

smart-explore 和普通的 Grep 或 Read 有什么区别

Grep 给你的是文本命中，Read 给你的是原始文件内容。smart-explore 的设计目标，是先在符号级别发现和检查代码结构。通常这会带来更好的结果排序、更清晰的边界，以及更少不必要的完整文件加载。

smart-explore 适合大型 monorepo 吗

适合，而且这正是它最匹配的场景之一，前提是你这边的底层工具在大仓库里表现足够稳定。“先建立索引认知，再按需提取”的思路，在仓库大到无法靠朴素浏览处理时尤其有价值。

我能只把 smart-explore 用在 Code Review 吗

可以。实际上，code review 正是它最清晰的应用场景之一，因为审查者经常需要理解相邻符号和调用结构，但又不想把所有变更文件从头到尾重读一遍。当你的审查问题是“这次改动到底关联到什么”，smart-explore for Code Review 会非常合适。

如何改进 smart-explore 技能

给 smart-explore 更聪明的搜索词，而不是更宽泛的搜索词

smart-explore 的输出质量，很大程度取决于第一条查询。更好的查询通常会把领域术语和动作组合在一起，比如：

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

像 auth 或 user 这种过于宽泛的词，往往只会返回噪音很多的符号集合，连带拖累后续整个工作流。

使用 smart-explore 时一定要带上路径范围

提升 smart-explore usage 最简单的方法之一，就是明确搜索根目录，比如 ./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.”

这能让工作流始终贴合这个技能最大的优势。

用变更感知提示词改进 smart-explore for Code Review

在 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 这段代码”更有效，因为它把结构化探索直接对准了审查风险点。

留意 smart-explore 最常见的失败模式

最常见的问题包括：

• MCP 工具支持缺失
• 搜索词太模糊
• 从搜索结果直接跳到结论
• 因为没有先 outline 文件，就 unfold 了错误的符号
• 在很小的仓库上使用这个技能，导致“先结构后读取”的方法反而增加额外开销

这些问题都能修正，但它们对实际效果的影响，比 SKILL.md 文案写得漂不漂亮要大得多。

第一轮结果出来后先迭代，不要重开流程

好的 smart-explore guide 实践，通常是逐步收窄，而不是推翻重来。跑完第一轮后，你可以这样迭代：

• 用更具体的词细化查询
• 缩小路径范围
• 调整 max_results 的大小
• 再 outline 第二个候选文件
• unfold 相邻符号，而不只是第一个命中项

这样通常比直接放弃这套流程、重新回到随机读文件要有效得多。

怎样才能让 smart-explore 技能本身更强

当前的 smart-explore 文档能用，但确实偏薄。如果想让这个技能更容易被采用，至少可以补上这些内容：

• 一个明确的安装说明章节
• 一个从 search 到 unfold 的新手示例
• 一个 code review 示例
• 一个简短的“什么时候不要用”章节
• 一条放在前面的 MCP / 工具前置条件说明

这些补充能显著减少安装前的猜测成本，也能让用户第一次使用时更容易正确触发 smart-explore skill。