smart-explore

Visão geral da skill smart-explore

O que a smart-explore faz

A skill smart-explore é um fluxo de exploração de codebase baseado em busca estrutural, e não em leitura bruta de arquivos. O principal objetivo é ajudar um agente a entender um repositório mais rápido usando ferramentas baseadas em AST, como smart_search, smart_outline e smart_unfold, antes de carregar arquivos inteiros. Se você está avaliando a smart-explore para navegação de código, descoberta de arquitetura ou debugging direcionado, a promessa central é simples: mapeie o código primeiro e só depois leia as partes que realmente importam.

Quem deve instalar a smart-explore

A smart-explore faz mais sentido para quem pede com frequência que uma IA inspecione codebases desconhecidas e quer desperdiçar menos tokens e evitar navegação aleatória entre arquivos. Ela é especialmente útil para:

• code review e análise de impacto de mudanças
• onboarding em repositórios grandes
• encontrar a implementação real por trás do nome de uma feature
• localizar símbolos, handlers, services e call sites com rapidez
• reduzir ciclos ruidosos de exploração com Read/Grep/Glob

O encaixe mais forte é smart-explore for Code Review, em que entender estrutura e limites de símbolos importa mais do que ler cada linha.

O trabalho real que ela resolve

Grande parte das falhas na exploração de repositórios acontece porque o agente começa a ler arquivos cedo demais. A smart-explore muda esse comportamento. Em vez de “abrir arquivos até algo parecer relevante”, ela impõe um fluxo de trabalho com esta lógica:

1. buscar símbolos compatíveis dentro de um diretório
2. inspecionar a estrutura do arquivo relevante
3. expandir apenas o símbolo de que você realmente precisa

Isso faz da smart-explore skill mais do que um atalho de busca; ela vira uma regra de decisão sobre quando não ler arquivos completos.

O que diferencia a smart-explore de um prompt genérico

Um prompt comum pode dizer ao modelo para “ser eficiente”, mas a smart-explore fornece uma ordem de ferramentas específica e uma substituição clara para os hábitos padrão de navegação em repositórios. O diferencial não está em documentação mais profunda; está no override explícito: usar smart_search/smart_outline/smart_unfold como caminho principal de exploração em vez de Read, Grep, Glob ou descoberta ad hoc de arquivos.

O que importa antes de instalar

A principal pergunta de adoção não é “a ideia é boa?”, e sim “meu ambiente tem as ferramentas certas?”. A smart-explore só faz sentido se o seu setup expõe as ferramentas MCP correspondentes. A skill em si é leve e guiada por instruções; o valor real depende de o agente conseguir chamar de fato as ferramentas de exploração estrutural que ela referencia.

Como usar a skill smart-explore

Confirme primeiro a dependência de ferramentas

Antes de testar qualquer fluxo de smart-explore install, verifique se o seu ambiente oferece estas ferramentas MCP:

• smart_search
• smart_outline
• smart_unfold

Esta skill não substitui essas ferramentas nem as inclui por padrão. Ela muda a estratégia de exploração do agente. Se esses nomes de ferramentas não estiverem disponíveis no seu client, o smart-explore usage ficará limitado a ideia e intenção, não à execução.

Contexto de instalação e onde a skill fica

O caminho desta skill no repositório é:

plugin/skills/smart-explore

O padrão de instalação mais usado para esta família de repositórios nesta página é:

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

Como o SKILL.md de origem não traz um comando de instalação próprio, trate o comando acima como o ponto de entrada prático para instalar esta coleção de skills e, em seguida, valide o seu loader local de skills e a configuração de MCP.

Leia este arquivo primeiro

Comece por:

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

Não há arquivos extras como README.md, metadata.json, rules/ ou resources/ dando suporte a esta skill, então quase toda a orientação útil está concentrada nesse único arquivo. Isso ajuda numa avaliação rápida, mas também significa que você não deve esperar exemplos mais profundos ou documentação de edge cases em outro lugar.

O padrão central de uso da smart-explore

A skill foi construída em torno de um fluxo de 3 camadas:

1. smart_search para descobrir arquivos e símbolos relevantes
2. smart_outline para inspecionar a estrutura de um arquivo sem carregar o arquivo inteiro
3. smart_unfold para buscar em completo exatamente o símbolo de que você precisa

Esse é o núcleo prático do smart-explore guide. Se você pula a etapa 1 e começa lendo arquivos inteiros, na prática não está usando a skill como ela foi pensada.

Seu primeiro prompt deve combinar objetivo e escopo

Prompt fraco:

“Find the bug in auth.”

Prompt mais forte:

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

Por que isso é melhor:

• instrui explicitamente o agente a acionar o comportamento da skill
• define os termos de busca
• estreita o caminho de exploração
• pede estrutura antes de pedir código completo

Como transformar um objetivo vago em um bom prompt de smart-explore

Para um smart-explore usage forte, inclua estes elementos:

• o tópico ou nome da feature
• o caminho raiz da busca
• o número preferido de resultados
• se você quer descoberta, review, tracing ou extração
• quais símbolos devem ser expandidos se forem encontrados

Modelo:

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

Melhor fluxo de smart-explore for Code Review

Para code review, não peça primeiro que o agente “revise o diff inteiro” se o contexto da codebase ainda estiver pouco claro. Uma sequência melhor é:

1. buscar a feature, classe, endpoint ou nome de função afetado pela mudança
2. inspecionar a estrutura dos arquivos tocados para entender o contexto ao redor
3. expandir apenas os símbolos alterados ou adjacentes
4. comparar a lógica alterada com interfaces, validadores ou callers próximos
5. ler arquivos completos apenas quando o contexto no nível de símbolo não for suficiente

Isso reduz ruído e ajuda o reviewer a entender a que o código alterado está ligado.

Quando usar smart_search primeiro

Use smart_search quando você conhece o conceito, mas não o arquivo exato. Boas consultas incluem:

• nomes de features
• nomes de endpoints
• mensagens de erro
• termos de domínio
• nomes de métodos
• transições de estado

A skill recomenda explicitamente não usar Grep, Glob, Read ou find para descoberta inicial quando a busca estrutural estiver disponível. O motivo é qualidade de decisão: correspondências de símbolos ranqueadas costumam ser mais acionáveis do que ocorrências brutas de texto.

Quando usar smart_outline em seguida

Use smart_outline quando você já encontrou um arquivo promissor, mas ainda não quer entrar nos detalhes de implementação. Esse é o movimento certo quando você precisa saber:

• quais classes ou funções existem no arquivo
• se o símbolo-alvo realmente está ali
• onde a estrutura de topo começa e termina
• se vale a pena ler o arquivo inteiro

Essa etapa é especialmente útil em arquivos grandes, em que a leitura completa desperdiça tokens.

Quando usar smart_unfold

Use smart_unfold depois de identificar o símbolo que provavelmente contém a lógica de que você precisa. Esse é o jeito de maior sinal para inspecionar:

• um handler
• um método de service
• um resolver
• um reducer
• uma função utilitária

Se você fizer unfold cedo demais, pode deixar passar um símbolo melhor. Se fizer unfold tarde demais, perde tempo inspecionando estruturas de arquivos que já eram obviamente relevantes.

Exemplos práticos de prompt que melhoram a qualidade da saída

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

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

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

FAQ da skill smart-explore

Vale a pena instalar a smart-explore se eu já uso bons prompts?

Sim, desde que o seu ambiente suporte as ferramentas que ela espera. O benefício da smart-explore não é apenas um texto de prompt melhor; é uma política de exploração mais forte. Ela faz o agente preferir descoberta estrutural em vez de ficar vagando de arquivo em arquivo, que muitas vezes é a verdadeira fonte de desperdício de tempo.

A smart-explore é amigável para iniciantes?

Moderadamente. A ideia é simples, mas iniciantes podem travar se não entenderem a diferença entre descoberta de símbolos e leitura de arquivos, ou se instalarem a skill sem o suporte MCP necessário. Se você está começando, inicie com a busca de uma feature bem específica, e não com uma tarefa para o repositório inteiro.

Quando eu não devo usar a smart-explore?

Evite smart-explore quando:

• seu ambiente não tiver smart_search, smart_outline e smart_unfold
• você já souber exatamente qual arquivo pequeno e qual símbolo quer inspecionar
• o repositório for tão pequeno que ler o arquivo inteiro saia mais barato do que preparar a exploração estrutural
• sua tarefa for mais focada em prosa do que em estrutura de código

Como a smart-explore se diferencia de Grep ou Read comuns?

Grep retorna correspondências de texto. Read retorna conteúdo bruto de arquivo. A smart-explore foi pensada para encontrar e inspecionar primeiro a estrutura do código no nível de símbolo. Isso normalmente significa melhor ranqueamento, limites mais claros e menos carregamentos desnecessários de arquivos completos.

A smart-explore funciona bem em monorepos grandes?

Sim, esse é um dos cenários com melhor encaixe, desde que as ferramentas por trás funcionem bem no seu setup. A mentalidade de “indexar primeiro, buscar sob demanda” fica muito mais valiosa quando o repositório é grande demais para navegação ingênua.

Posso usar smart-explore for Code Review e nada além disso?

Sim. Na prática, code review é um dos casos de uso mais claros, porque reviewers frequentemente precisam entender símbolos vizinhos e a estrutura de chamadas sem reler por completo todos os arquivos afetados. smart-explore for Code Review funciona muito bem quando a pergunta da revisão é “a que esta mudança está conectada?”.

Como melhorar a skill smart-explore

Faça consultas mais inteligentes, não mais amplas

A qualidade da saída da smart-explore depende muito da primeira consulta. Em geral, as melhores buscas combinam um termo de domínio com uma ação, por exemplo:

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

Consultas amplas demais, como auth ou user, costumam devolver conjuntos de símbolos ruidosos e enfraquecem o restante do fluxo.

Sempre inclua um escopo de caminho

Uma das formas mais simples de melhorar o smart-explore usage é especificar a raiz da busca, como ./src, ./app ou o diretório de um package. Sem esse escopo, os resultados tendem a ficar mais ruidosos e lentos, especialmente em repositórios maiores.

Peça ranqueamento e uma etapa de decisão

Não peça apenas para o agente buscar. Peça que ele escolha. Exemplo:

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

Isso força uma etapa de seleção e reduz o uso cego e repetitivo de ferramentas.

Use outlines para evitar leitura completa cedo demais

Um modo comum de falha é voltar para leitura de arquivo inteiro logo após o primeiro resultado da busca. Para extrair mais valor da smart-explore, diga explicitamente ao agente:

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

Isso mantém o fluxo alinhado com a principal vantagem da skill.

Melhore smart-explore for Code Review com prompts conscientes da mudança

Para code review, combine a área alterada com a pergunta arquitetural. Exemplo:

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

Isso é melhor do que “review this code”, porque direciona a exploração estrutural para o risco real da revisão.

Fique atento aos principais modos de falha

Os problemas mais prováveis são:

• falta de suporte às ferramentas MCP
• termos de busca vagos demais
• pular direto da busca para conclusões
• expandir o símbolo errado porque o arquivo nunca foi inspecionado com outline
• usar a skill em repositórios tão pequenos que o método “estrutura primeiro” só adiciona overhead

Tudo isso é corrigível, mas pesa mais do que acabamento textual no SKILL.md.

Itere após o primeiro resultado em vez de recomeçar do zero

Uma boa prática no smart-explore guide é fazer refinamento iterativo. Depois da primeira rodada:

• refine a consulta com um termo mais específico
• reduza o caminho de busca
• aumente ou diminua max_results
• inspecione um segundo arquivo candidato
• expanda um símbolo vizinho, não apenas a primeira correspondência

Isso costuma gerar resultados melhores do que abandonar o fluxo e voltar para leitura aleatória de arquivos.

O que deixaria a própria skill smart-explore mais forte

A documentação atual da smart-explore é utilizável, mas enxuta. A skill seria mais fácil de adotar se tivesse:

• uma seção explícita de instalação
• um exemplo para iniciantes, do search ao unfold
• um exemplo de code review
• uma seção curta de “quando não usar”
• uma observação logo no início esclarecendo os pré-requisitos de MCP/ferramentas

Esses acréscimos reduziriam a incerteza antes da instalação e tornariam a smart-explore skill mais fácil de acionar corretamente logo na primeira tentativa.