Pesquisando um Codebase com a Ferramenta Grep Integrada do Claude Code
O Claude Code vem com ferramentas de busca integradas que escaneiam um repositório em busca de padrões, nomes de funções, chaves de configuração ou strings literais e retornam onde cada correspondência está localizada.
Antes que o Claude Code leia um arquivo ou proponha uma edição, ele geralmente busca primeiro, para que esteja agindo no conjunto real de arquivos relevantes em vez de adivinhar quais importam.
Resumo
As ferramentas de busca do Claude Code funcionam como uma busca rápida em todo o repositório por padrões: forneça um termo ou padrão e elas retornam cada arquivo e linha correspondentes, em quantos arquivos o repositório contiver.
Isso é distinto de abrir um único arquivo - a busca opera em toda a árvore (ou um subconjunto dela) em uma única passagem.
A busca é tipicamente o passo que é executado antes do início do loop de leitura-edição-execução-teste, porque o Claude Code precisa saber quais arquivos são realmente relevantes antes de lê-los por completo.
É especialmente valioso para tarefas que abrangem vários arquivos: renomear uma função com segurança requer conhecer todos os locais de chamada primeiro, e encontrar todos os usos de uma chave de configuração ou string de erro requer a mesma visão de todo o repositório.
Como a busca retorna correspondências, não arquivos inteiros, é um passo de reconhecimento - o Claude Code ainda lê o contexto circundante de uma correspondência antes de editar esse arquivo.
Receita
Referência rápida: estes são prompts em linguagem natural que você digita no prompt do Claude Code. O Claude Code decide quando invocar suas ferramentas de busca com base no que você pede.
# Find where something is defined
> Where is the function calculateTotal defined in this repo?
# Find every call site before a rename
> Find every place that calls calculateTotal so I can rename it safely.
# Find every usage of a config key, constant, or literal string
> Search the codebase for every reference to the config key MAX_RETRIES.
# Scope a search to a subdirectory or file type
> Search only the api/ directory for calls to the old auth middleware.Quando usar isso:
- Antes de renomear uma função, classe ou variável, para saber todos os locais de chamada antecipadamente.
- Antes de excluir ou descontinuar uma chave de configuração, flag ou símbolo exportado.
- Ao rastrear de onde uma mensagem de erro ou string de log é realmente impressa.
- Quando você é novo em um repositório e precisa encontrar o arquivo que possui um determinado comportamento.
- Antes de uma edição em vários arquivos, para que o Claude Code tenha a lista completa de arquivos a serem tocados em vez de editar um e perder os outros.
Exemplo de Trabalho
Um cenário comum: você deseja renomear uma função e precisa ter certeza de que captura todos os locais de chamada primeiro.
# 1. Start Claude Code in the project root
cd my-project
claude
# 2. Ask it to search before touching anything
> Find every call site of calculateTotal, then rename it to computeOrderTotal
> everywhere, including its definition and any imports.O passo de busca do Claude Code retorna algo conceitualmente como isso (caminhos de arquivo e números de linha, um por correspondência):
src/orders/pricing.ts:42: export function calculateTotal(items, discounts) {
src/orders/checkout.ts:18: import { calculateTotal } from "./pricing";
src/orders/checkout.ts:57: const total = calculateTotal(cartItems, activeDiscounts);
src/reports/summary.ts:9: import { calculateTotal } from "../orders/pricing";
src/reports/summary.ts:31: const lineTotal = calculateTotal(row.items, []);
tests/pricing.test.ts:12: expect(calculateTotal([], [])).toBe(0);
A partir dessa lista de correspondências, o Claude Code lê cada arquivo ao redor da linha correspondente e, em seguida, propõe edições coordenadas em todos eles:
- export function calculateTotal(items, discounts) {
+ export function computeOrderTotal(items, discounts) {
- import { calculateTotal } from "./pricing";
+ import { computeOrderTotal } from "./pricing";
- const total = calculateTotal(cartItems, activeDiscounts);
+ const total = computeOrderTotal(cartItems, activeDiscounts);O que isso demonstra:
- A busca é executada primeiro e retorna uma lista de correspondências em todos os arquivos afetados, não apenas naquele em que você começou.
- A lista de correspondências, e não um palpite, é o que diz ao Claude Code quais arquivos precisam de edições.
- Uma renomeação só é considerada segura quando a definição, todas as importações e todos os locais de chamada são atualizados juntos.
- Testes que referenciam o nome antigo aparecem na mesma busca, para que não sejam deixados quebrados.
- O passo de busca e o passo de edição são separados - as correspondências são locais de texto, as edições ainda exigem a leitura e compreensão do código circundante.
Mergulho Profundo
Como Funciona
- As ferramentas de busca integradas do Claude Code escaneiam o conteúdo dos arquivos em todo o repositório (ou um caminho com escopo que você fornecer) em busca de um padrão, nome ou string literal.
- Cada correspondência é retornada como um caminho de arquivo e linha, juntamente com um pouco de contexto circundante, não o arquivo inteiro.
- A busca geralmente respeita as regras de ignorar do repositório, portanto, a saída de compilação, pastas de dependência e outros arquivos gerados geralmente não são retornados como correspondências.
- Os resultados alimentam diretamente o próximo passo do loop de leitura-edição-execução-teste: o Claude Code lê os arquivos específicos que corresponderam, em vez de ler todo o repositório.
- Como a busca é uma operação somente leitura, geralmente tem menos atrito do que um passo que executa um comando ou grava um arquivo, portanto, pode ser executada cedo e com frequência sem interromper seu fluxo de trabalho.
- A mesma infraestrutura de busca sustenta várias solicitações do dia a dia: "encontre a função", "encontre os chamadores", "encontre todos os usos" e "encontre o arquivo que possui esta string" são todas variações do mesmo padrão de busca e leitura.
Busca vs. Leitura vs. Edição
| Passo | O que retorna | Quando o Claude Code usa |
|---|---|---|
| Busca | Arquivo + correspondências de linha para um padrão em vários arquivos | Primeiro, para descobrir quais arquivos são relevantes |
| Leitura | O conteúdo completo e atual de um arquivo específico | Após a busca refinar os candidatos, ou quando um arquivo já é conhecido |
| Edição | Um diff proposto contra um arquivo que acabou de ler | Por último, quando o arquivo certo e o contexto certo estão em mãos |
Obtendo Resultados Úteis
# Vague - likely to return noise or miss intent
> Find "total" in the code.
# Specific - names the exact symbol and what you want done with the results
> Find every call site of calculateTotal (the function in src/orders/pricing.ts),
> not just the string "total".
# Scoped - narrows the search when the repo is large or the term is common
> Search only src/api/ for references to the old webhook URL.Ser específico sobre o nome exato e limitar a um diretório ou tipo de arquivo quando o termo é comum, obtém uma lista de correspondências mais limpa e uma edição de acompanhamento melhor.
Armadilhas
- Assumir que a busca cobre tudo na árvore de trabalho. Arquivos gerados, saída de compilação e qualquer coisa nas regras de ignorar do repositório normalmente não aparecerão como correspondências. Correção: se você realmente precisar pesquisar a saída gerada, diga explicitamente para que o Claude Code saiba incluí-la.
- Usar um termo muito comum. Pesquisar uma palavra curta e genérica como "total" ou "config" em um repositório grande pode retornar uma lista de correspondências esmagadora e em grande parte irrelevante. Correção: pesquise o nome exato da função, classe ou chave e limite a um diretório quando possível.
- Tratar uma correspondência de busca como prova de um local de chamada ativo. Uma correspondência de padrão pode cair dentro de um comentário, uma string ou código morto que nunca é realmente executado. Correção: peça ao Claude Code para confirmar que cada correspondência é um uso real antes de editar, especialmente para uma renomeação que afeta vários arquivos.
- Esperar que a busca entenda o uso dinâmico ou reflexivo. Uma correspondência de padrão encontra apenas texto; não capturará uma função invocada por uma string construída dinamicamente ou por meio de metaprogramação. Correção: chame isso explicitamente e peça escrutínio extra, depois verifique com uma execução de teste após a edição.
- Confiar em um resultado de busca do início de uma longa sessão. Se os arquivos mudaram desde que essa busca foi executada, a lista de correspondências pode estar desatualizada quando uma grande edição em vários arquivos ocorrer. Correção: peça ao Claude Code para reexecutar a busca imediatamente antes de uma grande edição coordenada, em vez de reutilizar resultados antigos.
- Confundir "encontrei" com "li". Uma correspondência retorna apenas uma linha e um pouco de contexto, não o arquivo inteiro. Correção: espere que o Claude Code leia o arquivo completo antes de propor uma edição e não assuma que uma correspondência sozinha é base suficiente para uma mudança.
- Pesquisar com diferenciação de maiúsculas/minúsculas (ou não) sem querer. Uma renomeação ou busca de chave de configuração pode silenciosamente perder variantes que diferem apenas em maiúsculas/minúsculas. Correção: declare explicitamente se você deseja uma correspondência exata ou uma que não diferencie maiúsculas de minúsculas.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Executar um comando de busca você mesmo no terminal | Você só quer ver as correspondências brutas sem que o Claude Code aja sobre elas | Você quer que o Claude Code raciocine sobre as correspondências e edite vários arquivos na mesma interação |
| "Localizar em Arquivos" / busca global do seu editor | Navegação manual rápida enquanto você já está no IDE | Você precisa que os resultados impulsionem uma edição automatizada e coordenada em vários arquivos |
git log -S<termo> ou git blame | Você precisa saber quando uma string ou símbolo foi introduzido historicamente | Você precisa de todos os usos atuais, não do histórico |
| "Encontrar referências" do servidor de linguagem | Você precisa de resolução de referências em nível de símbolo, ciente do escopo, em uma linguagem com um LSP configurado | Nenhum LSP está configurado, ou você está procurando por chaves de configuração, strings ou padrões em vez de um símbolo resolúvel |
FAQs
O que a busca integrada do Claude Code realmente retorna?
- Uma lista de correspondências, cada uma com um caminho de arquivo e número de linha
- Uma pequena quantidade de contexto circundante por correspondência
- Não o conteúdo completo de cada arquivo - isso vem de um passo de leitura separado
Quando o Claude Code decide buscar em vez de apenas ler um arquivo que já conhece?
Se ele já souber exatamente qual arquivo e localização são relevantes, ele pode ler diretamente.
A busca entra em jogo quando os arquivos relevantes ainda não são conhecidos, o que é o caso comum para renomeações, auditorias de uso e perguntas de "onde isso está definido".
A busca verifica todo o repositório, incluindo dependências e saída de compilação?
Geralmente não. A busca normalmente respeita as regras de ignorar do repositório, portanto, pastas como saída de compilação ou dependências instaladas são excluídas das correspondências por padrão.
Você pode pedir ao Claude Code para incluir um caminho específico explicitamente se precisar que ele seja pesquisado de qualquer maneira.
Posso limitar uma busca a um diretório específico ou tipo de arquivo?
Sim. Nomear um diretório ("busque apenas em src/api/") ou um tipo de arquivo em sua solicitação limita a busca, o que é útil em um repositório grande ou quando o termo que você está procurando é comum.
Isso é o mesmo que executar um comando de busca manual no terminal?
Conceitualmente semelhante - ambos procuram um padrão em arquivos - mas a versão do Claude Code está integrada ao seu fluxo de trabalho, de modo que as correspondências alimentam diretamente os próximos passos de leitura e edição na mesma interação, sem que você copie os resultados de volta.
A busca encontrará todos os locais de chamada antes de uma renomeação?
Ela encontra todas as correspondências de texto para o padrão que você fornece, o que cobre a grande maioria dos locais de chamada reais.
Ela não capturará uma chamada construída dinamicamente em tempo de execução (por exemplo, por meio de um nome de função construído com string), portanto, vale a pena verificar novamente qualquer coisa incomum após uma renomeação.
Uma correspondência de busca garante que o código lá realmente é executado?
Não. Uma correspondência pode cair em um comentário, uma string literal ou código morto.
O Claude Code geralmente lê o contexto circundante antes de editar, o que é exatamente a salvaguarda para filtrar correspondências que não são usos reais.
Como a busca se encaixa no loop de leitura-edição-execução-teste do Claude Code?
A busca geralmente ocorre antes da primeira leitura do loop: ela identifica quais arquivos são relevantes, então o Claude Code lê esses arquivos específicos, propõe edições, executa um comando e verifica o resultado.
A busca diferencia maiúsculas de minúsculas?
O comportamento pode variar dependendo do que você pede, por isso vale a pena ser explícito: diga se deseja uma correspondência exata de maiúsculas/minúsculas ou se deseja incluir variantes que diferem apenas em maiúsculas/minúsculas.
E se uma busca em um repositório muito grande retornar muitos resultados?
Refine a solicitação: nomeie o símbolo exato em vez de uma palavra genérica, ou limite a busca a um diretório específico ou tipo de arquivo. Uma solicitação mais específica geralmente produz uma lista de correspondências mais limpa e curta.
A busca pode encontrar uma string literal, como uma mensagem de erro, e não apenas um nome de função?
Sim. A busca não se limita a nomes de funções ou símbolos - funciona para chaves de configuração, mensagens de erro, strings de log e outros textos literais igualmente bem.
A busca precisa da minha permissão para ser executada, da mesma forma que um comando de shell?
A busca é uma operação somente leitura, portanto, na maioria das configurações de permissão, ela é executada sem o tipo de prompt de aprovação que um comando com efeitos colaterais (como uma gravação de arquivo ou uma instalação) poderia acionar.
Se eu já sei o arquivo e a linha exatos, ainda devo pedir ao Claude Code para buscar?
Não necessariamente - se você já sabe exatamente onde algo está localizado, pode apontar o Claude Code diretamente para lá.
A busca vale a pena quando você ainda não conhece todos os locais afetados, o que é a maioria das vezes para qualquer coisa que abrange mais de um arquivo.
Relacionados
- Como o Claude Code Executa o Loop de Leitura-Edição-Execução-Teste - onde a busca se encaixa antes do passo de leitura
- Fazendo Edições em Vários Arquivos em uma Única Interação do Claude Code - o que acontece depois que a busca encontra todos os arquivos afetados
- Por que o Claude Code Re-Lê Arquivos Antes de Editá-los - por que uma correspondência de busca não é tratada como uma resposta final
- Navegando no REPL do Claude Code: Prompts e Comandos de Barra - o básico de digitar solicitações como estas no prompt
Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.