Exploração Inteligente

Exploração de código estrutural usando análise AST. Esta habilidade substitui seu comportamento de exploração padrão. Enquanto esta habilidade estiver ativa, use smart_search/smart_outline/smart_unfold como suas ferramentas principais em vez de Read, Grep e Glob.

Princípio central: Indexar primeiro, buscar sob demanda. Dê a si mesmo um mapa do código antes de carregar os detalhes de implementação. A pergunta antes de cada leitura de arquivo deve ser: "preciso ver tudo isso, ou posso obter uma visão estrutural primeiro?" A resposta é quase sempre: obtenha o mapa.

Sua Próxima Chamada de Ferramenta

Esta habilidade apenas carrega instruções. Você deve chamar as ferramentas MCP por conta própria. Sua próxima ação deve ser uma das seguintes:

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

NÃO execute Grep, Glob, Read ou find para descobrir arquivos primeiro. smart_search percorre diretórios, analisa todos os arquivos de código e retorna símbolos classificados em uma única chamada. Ele substitui o ciclo de descoberta Glob → Grep → Read.

Fluxo de Trabalho de 3 Camadas

Etapa 1: Pesquisar -- Descobrir Arquivos e Símbolos

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

Retorna: Símbolos classificados com assinaturas, números de linha, motivos da correspondência, além de visualizações de arquivos dobrados (~2-6k tokens)

-- 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)

Esta é sua ferramenta de descoberta. Ela encontra arquivos relevantes E mostra sua estrutura. Nenhuma varredura prévia com Glob/find é necessária.

Parâmetros:

• query (string, obrigatório) -- O que pesquisar (nome da função, conceito, nome da classe)
• path (string) -- Diretório raiz para pesquisar (padrão é cwd)
• max_results (number) -- Máximo de símbolos correspondentes, padrão 20, máximo 50
• file_pattern (string, opcional) -- Filtro para arquivos/caminhos específicos

Etapa 2: Esboçar -- Obter Estrutura do Arquivo

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

Retorna: Esqueleto estrutural completo -- todas as funções, classes, métodos, propriedades, importações (~1-2k tokens por arquivo)

Pule esta etapa quando as visualizações de arquivos dobrados da Etapa 1 já fornecerem estrutura suficiente. Mais útil para arquivos não cobertos pelos resultados da pesquisa.

Parâmetros:

• file_path (string, obrigatório) -- Caminho para o arquivo

Etapa 3: Expandir -- Ver Implementação

Revise os símbolos das Etapas 1-2. Escolha os que você precisa. Expanda apenas esses:

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

Retorna: Código-fonte completo do símbolo especificado, incluindo JSDoc, decoradores e implementação completa (~400-2.100 tokens dependendo do tamanho do símbolo). Limites de nós AST garantem a completude, independentemente do tamanho do símbolo — ao contrário de Read + sumarização do agente, que pode truncar métodos longos.

Parâmetros:

• file_path (string, obrigatório) -- Caminho para o arquivo (conforme retornado por pesquisa/esboço)
• symbol_name (string, obrigatório) -- Nome da função/classe/método para expandir

Quando Usar Ferramentas Padrão em Vez Disso

Use estas apenas quando as ferramentas smart_* não forem adequadas:

• Grep: Pesquisa exata de string/regex ("encontrar todos os comentários TODO", "onde ensureWorkerStarted está definido?")
• Read: Arquivos pequenos com menos de ~100 linhas, arquivos não de código (JSON, markdown, config)
• Glob: Padrões de caminho de arquivo ("encontrar todos os arquivos de teste")
• Agente de Exploração: Quando você precisa de compreensão sintetizada em mais de 6 arquivos, narrativas de arquitetura ou respostas a perguntas abertas como "como todo este sistema funciona de ponta a ponta?" O smart-explore é um bisturi — ele responde "onde está isso?" e "mostre-me aquilo". Ele não sintetiza fluxos de dados entre arquivos, decisões de design ou casos extremos em uma funcionalidade inteira.

Para arquivos de código com mais de ~100 linhas, prefira smart_outline + smart_unfold em vez de Read.

Exemplos de Fluxo de Trabalho

Descobrir como uma funcionalidade funciona (transversal):

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

Navegar em um arquivo grande:

…