Realizando Edições em Vários Arquivos em um Único Turno de Código Claude
O Claude Code pode renomear uma função, adicionar um campo a um tipo compartilhado ou mover um módulo e atualizar todos os arquivos que o tocam - tudo em um único turno, sem deixar imports quebrados ou call sites desatualizados para trás.
Resumo
Uma "edição em vários arquivos" é qualquer alteração que não está contida em um único arquivo: um renomeação, uma mudança de assinatura, um novo campo obrigatório, um módulo movido. Cada uma dessas ações tem um raio de explosão - todos os lugares que importam, chamam ou constroem a coisa que você está mudando.
O Claude Code lida com isso tratando a busca como um primeiro passo, não como um pensamento posterior. Antes de tocar em qualquer coisa, ele localiza todos os usos em todo o repositório para que o plano de edição cubra todo o raio de explosão, não apenas o arquivo que você mencionou.
Ele também relê cada arquivo imediatamente antes de editá-lo, o que é mais importante em um turno de vários arquivos do que em um de arquivo único - quando o Claude chega ao arquivo cinco, os arquivos um a quatro já mudaram, e o próprio arquivo cinco pode ter sido tocado por uma ferramenta de build, formatador ou pelo usuário em outro terminal.
O turno não termina na última edição. O loop principal do Claude Code é ler, editar, executar, verificar - então, após as edições serem aplicadas, ele normalmente executa um comando de build, lint ou teste para capturar qualquer coisa que a busca perdeu, como um caminho de importação construído dinamicamente ou um call site em um arquivo que o padrão de busca não correspondeu.
Esta página percorre esse fluxo do início ao fim: encontrando todos os usos, editando em vários arquivos em ordem e verificando se nada quebrou.
Receita
Cartão de receita de referência rápida - o padrão de solicitação que obtém uma edição limpa em vários arquivos.
Rename the function `calculateTotal` to `calculateOrderTotal` everywhere it's
defined and called. Update all imports and call sites. Then run the test
suite to confirm nothing broke.# After Claude Code proposes and applies the edits, verify yourself too:
npm test
npm run build
grep -rn "calculateTotal(" src/ # should return nothingQuando usar isso:
- Renomear uma função, método ou variável exportada usada em mais de um arquivo.
- Adicionar ou remover um campo em um tipo/interface/esquema que é construído ou lido em vários lugares.
- Mover ou dividir um módulo e precisar que todos os caminhos de importação sejam corrigidos.
- Alterar a assinatura de uma função (novo argumento obrigatório, parâmetros reordenados) em todos os call sites.
- Qualquer alteração onde "grep o nome antigo" retornaria mais de um arquivo.
Exemplo de Trabalho
Digamos que um tipo User ganhe um campo obrigatório role e três arquivos o toquem: a definição do tipo, uma função de fábrica que constrói usuários e um componente que lê o campo.
# 1. Ask Claude Code for the change, naming the shared type explicitly
claude "Add a required `role: 'admin' | 'member'` field to the User type
in types/user.ts. Update every place that constructs a User to pass a role,
and every place that reads User fields to handle the new one. Search the
whole repo first, then show me the plan before editing."A primeira ação do Claude Code é uma busca em todo o repositório por usos de User - a definição do tipo, construtores e sites de leitura - antes de propor qualquer coisa. Assim que você confirmar, ele editará cada arquivo em sequência. Uma diff representativa entre os três arquivos:
--- a/types/user.ts
+++ b/types/user.ts
export type User = {
id: string;
name: string;
+ role: 'admin' | 'member';
};--- a/lib/create-user.ts
+++ b/lib/create-user.ts
-export function createUser(id: string, name: string): User {
- return { id, name };
+export function createUser(id: string, name: string, role: User['role']): User {
+ return { id, name, role };
}--- a/lib/format-user.ts
+++ b/lib/format-user.ts
export function formatUser(user: User): string {
- return `${user.name} (${user.id})`;
+ return `${user.name} (${user.id}) - ${user.role}`;
}# 2. Claude Code (or you) runs the build/tests to catch anything the search missed
npm run build
npm testO que isso demonstra:
- A busca é executada antes de qualquer edição, então o plano já considera o construtor e o leitor, não apenas a definição do tipo.
- Cada arquivo é editado para corresponder à sua própria responsabilidade - o tipo ganha um campo, o construtor ganha um parâmetro, o leitor ganha um caso de exibição - em vez de um find-and-replace cego.
- O turno fecha com uma execução de build/teste, que é o que capturaria um quarto call site que o padrão de busca não correspondeu (um acesso dinâmico a propriedade, por exemplo).
- Nada aqui é especulativo: cada linha alterada é usada por código real no mesmo turno, sem "TODO: lidar com isso mais tarde".
Mergulho Profundo
Como Funciona
- Busca primeiro. A ferramenta de busca integrada do Claude Code, semelhante ao grep, localiza todas as definições de função, call sites, imports ou usos de tipo correspondentes ao alvo antes que qualquer arquivo seja aberto para edição. É isso que transforma "renomear esta função" em "renomear esta função e seus N call sites" em vez de "renomear esta função no único arquivo que olhei".
- Edições ordenadas e sequenciais. Os arquivos são editados um de cada vez dentro do turno - tipicamente começando da definição (tipo, função, módulo) e movendo-se para seus consumidores - em vez de todos de uma vez, já que a correção de cada edição pode depender do que mudou logo antes dela.
- Relê antes de cada escrita. Imediatamente antes de editar um determinado arquivo, o Claude Code o relê em vez de confiar na cópia que leu durante a etapa de busca. Em um turno de vários arquivos, isso protege contra duas coisas: um arquivo mudando entre a passagem de busca e a passagem de edição, e um arquivo sendo editado duas vezes no mesmo turno (uma vez para a renomeação, outra para algo incidental) onde a segunda edição precisa do resultado da primeira edição, não da versão pré-turno.
- Verifica com comandos reais, não apenas inspeção. Após as edições, o loop principal do Claude Code passa para a execução - um build, uma verificação de tipo, um linter ou a suíte de testes - e lê a saída. Um import quebrado ou um call site perdido geralmente aparece aqui, mesmo que não fosse visível apenas pelo código-fonte (por exemplo, um arquivo de re-exportação que importa o nome antigo).
- Itera em falhas. Se a etapa de execução relatar um erro, o Claude Code trata isso como nova informação e volta para editar novamente, em vez de tratar a primeira passagem como final.
Regras em Resumo
| Etapa | O que acontece | Por que importa para edições em vários arquivos |
|---|---|---|
| Busca | Localiza todos os usos em todo o repositório | Define o raio de explosão real antes que qualquer arquivo seja tocado |
| Plano | Lista os arquivos que precisam mudar | Permite capturar um arquivo ausente antes que as edições comecem |
| Edição | Relê, depois escreve, um arquivo de cada vez | Evita trabalhar com uma cópia desatualizada no meio do turno |
| Execução | Compila, faz lint ou testa | Captura usos que o padrão de busca não correspondeu |
| Iteração | Corrige e reexecuta em caso de falha | Fecha o loop em vez de parar em "edições aplicadas" |
Dando ao Claude Code um Prompt de Vários Arquivos Melhor
Bad: "Rename calculateTotal to calculateOrderTotal."
Good: "Rename calculateTotal to calculateOrderTotal everywhere it's defined
and called (search the repo first), update the imports, and run
the test suite when you're done."Nomear explicitamente a etapa de busca e a etapa de verificação não é obrigatório - o Claude Code faz ambos por padrão - mas chamá-los antecipadamente tende a produzir um plano que você pode revisar antes que as edições comecem, o que vale a pena fazer em uma alteração que afeta mais de dois ou três arquivos.
Armadilhas
- Nomes de destino vagos subcontam usos. Pedir para renomear algo com um nome genérico (
get,Data,Item) pode perder símbolos não relacionados que por acaso compartilham o nome, ou corresponder de forma muito ampla. Correção: forneça o símbolo exato e totalmente qualificado (calculateTotalemlib/pricing.ts, não apenas "a função total") e peça ao Claude Code para pesquisar antes de editar. - Referências dinâmicas não aparecem em uma busca de texto. Uma chamada construída a partir de uma string (
window[fnName](), uma consulta baseada em reflexão, uma tabela de rotas com chave de string) não corresponderá a um grep para o nome antigo. Correção: chame isso explicitamente no prompt e confie na etapa de execução/teste - um call site dinâmico falhará em tempo de execução, mesmo quando a busca o perder estaticamente. - Barril/índice de re-exportações são perdidos. Um arquivo que faz
export { calculateTotal } from './pricing'é em si um call site para o nome da exportação, e é fácil de negligenciar. Correção: peça ao Claude Code para pesquisar o nome como uma string bruta, não apenas como uma chamada de função, para que os padrõesexport { name }eimport { name }sejam capturados. - Interromper no meio do turno deixa o repositório parcialmente editado. Se você parar o Claude Code depois que ele editou três de cinco arquivos, os outros dois agora discordam dos três primeiros. Correção: deixe um turno de vários arquivos terminar, ou se você precisar parar, peça ao Claude Code para resumir exatamente quais arquivos foram e não foram alterados antes de continuar em outro lugar.
- Pular a etapa de verificação oculta uma quebra real. Uma renomeação que "parece completa" em cada diff ainda pode falhar na compilação se um call site usou uma ordem de argumento diferente ou um alias re-exportado. Correção: sempre deixe (ou peça) ao Claude Code para executar o comando de build/teste/lint como parte do mesmo turno, não como uma etapa manual separada que você pode esquecer.
- Grandes alterações não relacionadas em vários arquivos são mais difíceis de revisar. Agrupar uma renomeação com uma passagem de formatação não relacionada nos mesmos arquivos torna a diff muito maior do que a alteração real. Correção: peça apenas a renomeação primeiro, revise-a, depois solicite a formatação ou outra limpeza como um turno separado.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Um turno de Claude Code por arquivo, revisado individualmente | A alteração é genuinamente local ao arquivo (uma correção de bug em uma função sem chamadores externos) | Os arquivos estão acoplados - uma renomeação ou alteração de campo precisa que eles se movam juntos para permanecerem limpos na compilação |
| Ferramenta de refatoração "renomear símbolo" nativa do editor | Seu IDE tem informações de tipo completas e a renomeação é uma mudança de identificador pura sem lógica para ajustar | A alteração também requer chamadas de julgamento por call site (por exemplo, um novo campo obrigatório precisa de um padrão diferente em cada local de construção) |
| Find-and-replace manual em todo o repositório | Uma troca de string trivial e inequívoca (uma chave de configuração renomeada usada apenas como literal) | O nome do símbolo pode colidir com texto não relacionado, ou os usos precisam de tratamento diferente dependendo do contexto |
| Um único turno de Claude Code abrangendo todos os arquivos afetados | A alteração tem um raio de explosão claro que o Claude Code pode pesquisar e os arquivos precisam ser aplicados juntos | A alteração é grande o suficiente para que revisar uma única diff gigante seja mais difícil do que revisar vários turnos pequenos e sequenciais |
FAQs
Como o Claude Code sabe quais arquivos mudar para uma renomeação?
- Ele executa uma busca em todo o repositório (sua ferramenta integrada semelhante ao grep) para o símbolo antes de editar qualquer coisa.
- A busca cobre a definição, imports e call sites.
- Nomear o símbolo exato e seu arquivo em seu prompt limita a busca e reduz correspondências falsas.
O Claude Code edita todos os arquivos de uma vez ou um de cada vez?
Um de cada vez, em sequência, geralmente começando da definição e movendo-se para os consumidores - não uma única escrita em lote simultânea.
Por que o Claude Code relê um arquivo logo antes de editá-lo, se já o leu durante a busca?
Porque o arquivo pode ter mudado desde essa primeira leitura - seja de uma edição anterior no mesmo turno de vários arquivos ou de algo fora do turno. Editar a partir de uma cópia desatualizada corre o risco de descartar silenciosamente essas alterações.
O que impede que uma edição em vários arquivos quebre silenciosamente um call site que a busca perdeu?
A etapa de execução. Após a edição, o loop principal do Claude Code executa um comando de build, lint ou teste e lê a saída, que normalmente expõe um import quebrado ou um call site incompatível, mesmo quando a busca de código-fonte não o capturou.
O que devo fazer se o plano de edição do Claude Code estiver faltando um arquivo que eu sei que precisa mudar?
Diga isso antes que ele comece a editar - nomeie o arquivo e o símbolo ausentes diretamente. Revisar o plano antes que as edições sejam aplicadas é o ponto mais barato para corrigir um raio de explosão subcontado.
Um turno de edição em vários arquivos pode falhar no meio?
Sim - se você o interromper, ou se uma edição posterior depender de um arquivo que o Claude Code não conseguiu resolver. O resultado é um repositório parcialmente editado, por isso é melhor deixar o turno terminar ou pedir um resumo do que mudou e o que não mudou antes de continuar.
O Claude Code capturará um call site construído dinamicamente, como uma pesquisa de função com chave de string?
Não de forma confiável apenas com a busca, pois uma busca de texto não pode corresponder a um nome construído em tempo de execução. Chame referências dinâmicas explicitamente em seu prompt e confie na execução de teste/build para capturar o que a busca estática não pode ver.
Devo pedir uma renomeação e uma limpeza não relacionada no mesmo turno?
Não - agrupá-los torna a diff mais difícil de revisar e mais difícil de reverter se algo estiver errado. Peça apenas a renomeação, revise-a e, em seguida, solicite a limpeza separadamente.
Qual é o prompt mínimo para uma edição limpa em vários arquivos?
Nomeie o símbolo exato e seu arquivo, declare que todos os usos em todo o repositório devem ser atualizados e peça um plano de busca primeiro, mais uma execução de verificação no final. Exemplo: "Renomeie X em path/to/file onde quer que seja usado, depois execute os testes."
Um arquivo de barril/índice que re-exporta uma função renomeada conta como um call site?
Sim - export { name } from './module' referencia o nome da exportação assim como um import, e é fácil de negligenciar se você estiver apenas escaneando chamadas de função em vez do identificador bruto.
Qual é a diferença em relação a uma edição de arquivo único?
O loop principal (ler, editar, executar, verificar) é o mesmo, mas a etapa de busca se torna essencial - uma edição de arquivo único não precisa descobrir um raio de explosão, enquanto a correção de uma edição de vários arquivos depende inteiramente de encontrar todos os arquivos afetados antecipadamente.
Qual é uma boa maneira de verificar novamente se a renomeação realmente removeu todas as referências antigas?
Execute um grep simples para o nome antigo após a conclusão do turno - grep -rn "oldName(" src/ - ele não deve retornar nada (além de comentários ou changelogs que você deixou intencionalmente).
Relacionados
- Pesquisando um Código-fonte com a Ferramenta Grep Integrada do Claude Code - a etapa de busca que define o raio de explosão de uma edição em vários arquivos.
- Por que o Claude Code Relê Arquivos Antes de Editá-los - por que a releitura é mais importante quando vários arquivos estão em jogo.
- Como o Claude Code Executa o Loop Ler-Editar-Executar-Testar - a etapa de verificação que captura o que a busca sozinha perde.
- Um Checklist para Revisar as Diffs Propostas pelo Claude Code - o que verificar em uma diff de vários arquivos antes de aceitá-la.
- Gerando Subagentes Paralelos para Tarefas de Pesquisa Isoladas - dividindo o trabalho entre arquivos quando ele não precisa ser aplicado como um turno coordenado.
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 de produtos mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.