Como o Claude Code Executa o Loop Ler-Editar-Executar-Testar
O Claude Code não é um motor de autocompletar que adivinha um arquivo e para.
É um agente que trabalha da maneira que um engenheiro trabalha: olha o código, muda o código, executa algo para verificar a mudança e, em seguida, olha novamente.
Esse ciclo, ler, editar, executar, verificar, é o núcleo mecânico de quase tudo que o Claude Code faz, desde uma correção de erro de digitação de uma linha até um refatoramento de vários arquivos.
Entender o loop é importante porque ele explica o que você está realmente vendo acontecer no seu terminal e por que o Claude Code se comporta de maneira tão diferente de um gerador de código de "disparo único".
Resumo
- Ideia Central: O Claude Code repete um ciclo de ler, editar, executar, verificar, usando a saída real de cada comando para decidir seu próximo passo, até que a tarefa seja concluída ou ele seja bloqueado.
- Por que é Importante: Um gerador de "disparo único" só pode adivinhar; um loop que lê a saída real pode capturar seus próprios erros antes que eles cheguem até você.
- Conceitos Chave: a etapa de ler (carregar o estado atual do arquivo), a etapa de editar (propor uma mudança), a etapa de executar (executar um comando), a etapa de verificar (interpretar o resultado) e iteração (repetir o ciclo até a conclusão).
- Quando Usar: Este é o comportamento padrão para qualquer tarefa não trivial do Claude Code; não há um modo separado para ativá-lo.
- Limitações / Compromissos: O loop só é tão bom quanto os comandos disponíveis para executar; sem testes ou uma etapa de compilação, a verificação é mais fraca e erros são mais propensos a passar despercebidos.
- Tópicos Relacionados: releitura de arquivos antes de edições, pesquisa na base de código, edições em vários arquivos, iteração automatizada de testes, prompts de permissão.
Fundamentos
O loop tem quatro etapas, e vale a pena nomear cada uma delas com precisão.
Ler significa que o Claude Code abre o arquivo ou arquivos relevantes e olha seus conteúdos atuais e reais, não uma memória do que eles provavelmente contêm.
Editar significa que ele propõe uma mudança específica: uma nova função, uma linha modificada, uma variável renomeada, expressa como um diff concreto contra o que ele acabou de ler.
Executar significa que ele executa um comando, um conjunto de testes, um linter, uma compilação, um script único e captura a saída real: código de saída, stdout, stderr.
Verificar significa que ele lê essa saída e decide o que ela significa: o teste passou, a compilação falhou, o linter sinalizou algo novo.
O loop não é ler-editar-concluir.
É ler-editar-executar-verificar e, em seguida, se a verificação indicar que o trabalho não foi concluído, voltar para ler (ou ir direto para outra edição) e dar a volta novamente.
Uma maneira simples de visualizar uma passagem pelo loop:
LER arquivo(s)
|
v
EDITAR (propor um diff)
|
v
EXECUTAR um comando (teste / build / lint)
|
v
VERIFICAR a saída
|
+--- tarefa concluída? --> parar
|
+--- não concluída? --> voltar para LER ou EDITAR
Este é o mesmo ritmo que um desenvolvedor cuidadoso já usa manualmente: abrir o arquivo, fazer a mudança, executar os testes, verificar o resultado, corrigir o que quebrou, executar novamente.
O Claude Code apenas executa esse ritmo explicitamente e pode repeti-lo várias vezes sem que um humano digite cada comando novamente.
Mecânicas e Interações
A etapa de leitura é deliberadamente baseada no conteúdo real e atual do arquivo, em vez de uma suposição.
Se o Claude Code já olhou um arquivo anteriormente na conversa, ele não trata necessariamente essa leitura anterior como ainda válida quando está pronto para editar; uma cópia desatualizada é uma fonte comum de patches com falha, portanto, uma leitura fresca logo antes de editar faz parte de como o loop permanece confiável (um artigo separado nesta seção, linkado abaixo, cobre exatamente por que essa releitura acontece).
A etapa de edição produz uma mudança concreta e aplicável, em vez de uma descrição vaga dela.
Isso é importante para a etapa de execução: uma mudança que não se aplica de fato, ou que introduz um erro de sintaxe, surgirá imediatamente assim que um comando tentar usar o arquivo, que é exatamente o tipo de sinal que o loop foi projetado para capturar cedo, em vez de deixar uma pessoa descobrir mais tarde.
A etapa de execução é onde o loop se conecta ao estado real do seu projeto.
npm test
npm run build
npm run lint
pytest
go test ./...Qualquer um desses, ou um equivalente específico do projeto, pode servir como a etapa de "execução".
O comando específico importa menos do que o fato de sua saída ser real: um teste com falha imprime um erro de asserção real, uma compilação quebrada imprime uma mensagem de compilador real, e o Claude Code lê esse texto literal em vez de assumir sucesso.
A etapa de verificação é onde o loop ganha seu nome.
Verificação não é o Claude Code declarando "isso deve funcionar agora"; é o Claude Code lendo o status de saída real e a saída do comando que ele acabou de executar e decidindo, com base nessa evidência, se deve parar, continuar ou mudar de abordagem.
Uma falha de teste nesta etapa não é um beco sem saída, é informação: qual asserção falhou, qual valor era esperado, qual valor foi produzido, e essa informação alimenta diretamente a próxima edição.
Os prompts de permissão ficam dentro deste loop na etapa de execução especificamente, pois executar um comando é a ação que mais provavelmente precisará de aprovação, dependendo do seu modo de permissão; leituras de arquivos e, em muitas configurações, edições de arquivos podem ser aprovadas automaticamente, enquanto um comando bash pode pausar para um sim/não, dependendo das configurações abordadas na seção Claude Code 101 deste site.
Considerações Avançadas e Aplicações
O loop escala de um único arquivo para uma base de código inteira sem mudar de forma.
Para uma correção de uma linha, o ciclo pode ser executado uma vez: ler o arquivo, fazer a edição, executar o linter, ver que passou, parar.
Para uma tarefa maior, "adicionar um novo campo e passá-lo pela API, pela camada de banco de dados e pelo formulário frontend", os mesmos quatro passos se repetem em vários arquivos e várias passagens, com cada etapa de verificação reduzindo o que ainda precisa de trabalho.
| Tamanho da tarefa | Forma típica do loop | O que a "verificação" geralmente checa |
|---|---|---|
| Correção de uma linha | Passagem única: ler, editar, executar, verificar | Passagem do linter ou verificador de tipos |
| Correção de bug com reprodução | Algumas passagens: ler, editar, executar teste, verificar, repetir | O teste com falha específico agora passa |
| Recurso multi-arquivo | Muitas passagens entre arquivos: ler, editar conjunto, executar suíte, verificar, repetir | Suíte de testes completa, compilação e quaisquer chamadas afetadas |
Uma segunda consideração é que o loop só é tão forte quanto o que ele pode executar.
Se um projeto não tem testes e nenhuma etapa de compilação, o Claude Code ainda pode ler e editar código, mas a etapa de verificação tem muito menos evidências reais para trabalhar, é por isso que projetos com uma suíte de testes rápida e confiável tendem a obter iterações notavelmente mais precisas do que projetos sem uma.
Uma terceira consideração é que o loop não requer que um humano assista a cada etapa.
Uma vez que uma tarefa esteja em andamento e o modo de permissão a permita, o Claude Code pode passar por várias passagens de ler-editar-executar-verificar em um único turno, retornando a você apenas quando a tarefa for concluída, bloqueada em uma decisão que só você pode tomar, ou quando um comando precisar de aprovação explícita.
Conceitos Errôneos Comuns
- "O Claude Code escreve o código uma vez e pronto." Todo o valor do loop está nas etapas de execução e verificação; uma mudança que não foi verificada contra um comando real é tratada como incompleta, não final.
- "O loop sempre executa a suíte de testes completa." A etapa de execução usa qualquer comando apropriado para a mudança, um único arquivo de teste, um linter, um verificador de tipos, uma compilação completa, não necessariamente a suíte inteira todas as vezes.
- "Verificação significa que o Claude Code confia em seu próprio julgamento sobre a correção." Verificação significa ler a saída literal de um comando que realmente executou; esse é um sinal mais forte do que a autoavaliação.
- "Se um teste falhar, o loop para e relata a falha." Uma falha de teste é geralmente tratada como entrada para a próxima edição, não como um ponto final; o loop continua iterando dentro do mesmo turno quando é capaz.
- "Reler um arquivo no meio do loop é esforço desperdiçado." É uma salvaguarda contra a edição de uma cópia desatualizada de um arquivo que pode ter mudado desde que foi lido pela última vez, coberto em detalhes em um artigo complementar.
FAQs
Quais são as quatro etapas do loop principal do Claude Code, em ordem?
Ler o arquivo relevante, propor uma edição, executar um comando contra o resultado e verificar o que a saída desse comando significa.
Se a verificação mostrar que a tarefa não foi concluída, o ciclo se repete a partir da leitura ou edição.
O Claude Code sempre executa testes como parte deste loop?
Ele executa qualquer comando que se ajuste à situação, que pode ser uma suíte de testes, um linter, um verificador de tipos ou uma compilação.
Testes são a forma mais comum e forte de verificação quando um projeto os possui, mas não são o único comando que a etapa de execução pode usar.
O que acontece se a etapa de execução falhar, por exemplo, um teste falhar ou uma compilação quebrar?
O Claude Code lê a saída real da falha e a trata como informação para a próxima passagem: qual asserção falhou, qual erro o compilador relatou ou o que o linter sinalizou.
Isso geralmente alimenta diretamente outra edição em vez de encerrar a tarefa.
Este loop pode ser executado sem que um humano aprove cada etapa?
Dentro de um único turno, sim, dependendo do seu modo de permissão; o Claude Code pode passar por várias passagens de ler-editar-executar-verificar antes de retornar a você.
Comandos que precisam de aprovação explícita sob suas configurações de permissão atuais ainda pausarão para essa aprovação.
Por que o loop é mais importante do que o fato de o Claude Code poder "escrever código"?
Porque escrever código sem verificá-lo contra a saída real é adivinhação, e o loop é projetado especificamente para substituir a adivinhação por evidências: um resultado de teste real, um erro de compilação real, um aviso de lint real.
Isso é o que diferencia um fluxo de trabalho de agente de um gerador de código de "disparo único".
O loop se aplica apenas a correções de bugs ou também a novos recursos?
Ambos. Um novo recurso geralmente passa por mais passagens do loop do que uma correção de bug de uma linha, pois geralmente afeta mais arquivos, mas a forma do ciclo, ler, editar, executar, verificar, é a mesma de qualquer maneira.
E se meu projeto não tiver testes para executar?
O Claude Code ainda pode ler, editar e executar quaisquer comandos disponíveis, como uma compilação ou verificação de tipos, mas com verificações menores ou mais fracas, a etapa de verificação tem menos evidências reais para trabalhar, então erros são mais propensos a passar despercebidos.
O "verificar" é apenas o Claude Code dizendo que o código parece correto?
Não, verificar significa especificamente interpretar a saída literal de um comando que foi realmente executado, um código de saída, uma mensagem de erro, uma asserção que passou ou falhou, não uma opinião não verificada sobre o código.
Onde os prompts de permissão se encaixam neste loop?
Eles ficam na etapa de execução, pois executar um comando é a ação que mais provavelmente precisará de sua aprovação, dependendo do seu modo de permissão.
Ler arquivos e, em muitas configurações, editá-los podem ser aprovados automaticamente, enquanto executar um comando bash pode pausar para confirmação.
O loop para assim que a edição de um arquivo é aplicada?
Não, o loop é orientado em torno da tarefa a ser concluída, não em torno de um único arquivo a ser modificado.
Para trabalho multi-arquivo, ele se repete entre arquivos e passagens até que a verificação mostre que a tarefa inteira, não apenas uma edição, está completa.
Como isso é diferente de pedir a um LLM para "escrever uma função para mim" em uma janela de chat?
Uma janela de chat normalmente retorna texto uma vez, sem nenhum mecanismo para verificar esse texto em relação a um arquivo real, um comando real ou um resultado de teste real.
O loop do Claude Code fecha essa lacuna executando comandos e lendo suas saídas reais antes de decidir que a tarefa está concluída.
Relacionados
- Noções Básicas dos Fluxos de Trabalho Principais do Claude Code - pratique o loop na prática com uma tarefa pequena
- Por que o Claude Code Relê Arquivos Antes de Editá-los - a salvaguarda dentro da etapa de leitura
- Executando Testes e Iterando em Falhas Automaticamente - um olhar mais aprofundado sobre a etapa de verificação em ação
- Como o Claude Code Decide Quando Executar um Comando vs Pedir Permissão - o que governa o comportamento de aprovação da etapa de execução
- Modos de Permissão Explicados: Aceitar Automaticamente vs Perguntar Sempre - as configurações que moldam a aprovação em todo o loop
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.