Skill ast-grep: buscar código por estrutura sintática, não só por texto

Para quem

Use esta skill quando quiser que um assistente de programação busque pela estrutura do código (árvore de sintaxe abstrata), não só por correspondência de texto. Oficialmente ela fica no mercado de plugins do Claude Code e oferece a busca estrutural do ast-grep.

Pré-requisitos: ast-grep já está instalado nesta máquina, e o assistente consegue instalar skills. O guia não diz como instalar o próprio ast-grep; não invente um instalador. O guia nomeia o Claude Code; não trate outros clientes como exclusivos oficiais. Se algo fora desse conjunto nomeado pode ser usado, o texto original não diz.

Há só um caminho de instalação: um único comando npx. Depois de instalar, você deve pedir explicitamente o uso da skill na pergunta, por exemplo "Use ast-grep to find...". O guia diz que em novembro de 2025 o Claude Code ainda não consegue decidir automaticamente usar ast-grep em todas as situações adequadas. O guia não nomeia um diretório de destino; depois de instalar, confirme só no assistente atual que a skill pode ser chamada pelo nome.

Primeira tentativa em 3 minutos

Página oficial:

https://github.com/ast-grep/agent-skill

Confirme primeiro que o ast-grep local funciona e depois execute a instalação recomendada (ela grava arquivos de skill nesta máquina; confira primeiro o nome do repositório):

npx skills add ast-grep/agent-skill

Se o comando falhar, pare. Depois do sucesso, não altere primeiro o código da aplicação. Abra um repositório existente e diga com clareza em linguagem natural: Use ast-grep to find..., mais um alvo estrutural de baixo risco, por exemplo encontrar certa forma de chamada de função. Peça ao assistente que primeiro analise se ast-grep serve, escreva exemplos e regras de correspondência e teste primeiro nos exemplos.

Sinal de sucesso: o assistente usou ast-grep de forma explícita, a regra foi verificada nos exemplos e os resultados de todo o repositório incluem caminhos de arquivo e números de linha. Se quiser gravar um arquivo de regras ou alterar o código da aplicação, interrompa primeiro e confirme os efeitos colaterais antes de continuar.

Casos de uso

Caso 1: busca estrutural somente leitura. A pergunta deve nomear ast-grep de forma explícita. Faça o assistente encontrar correspondências por estrutura e devolver caminhos de arquivo e números de linha. Na primeira passagem, olhe só os resultados; não deixe refatorar no caminho. O guia não dá um escopo de linguagens nem um repositório de exemplo; não infira a partir de uma lista de linguagens imaginada.

Caso 2: escrever a regra primeiro, verificar e por último buscar em todo o repositório. Os passos do guia são: analisar se a consulta serve para ast-grep, criar código de exemplo para a correspondência, escrever a regra, testar no exemplo, buscar em toda a base de código só depois disso passar, e por fim indicar caminhos e números de linha. A busca em todo o repositório só é permitida depois que o teste de exemplo passa. O guia não escreve caminho de arquivo de regras nem flags de CLI; não invente o que falta.

Limites

O caminho principal só documenta:

npx skills add ast-grep/agent-skill

Esta máquina precisa ter ast-grep já instalado. O disparo deve nomeá-lo de forma explícita, por exemplo "Use ast-grep to find..."; não espere seleção automática em todas as situações.

A capacidade só está evidenciada para busca estrutural e a cadeia "exemplo → regra → teste → repositório inteiro → caminho e número de linha". Está escrita como uma skill do mercado de plugins do Claude Code, mas na primeira tentativa não mude para cliques de mercado que nunca aparecem.

O guia não documenta comandos de instalação do ast-grep, cobrança, escopo de linguagens nem diretório de destino. A primeira passagem é só consulta somente leitura; não trate isso como porta de entrada para refatoração. O que não tem base permanece desconhecido; não invente operações.