Claude Code fica tentando a mesma correção em loop? Como quebrar o ciclo

Você pede o fix, o Claude Code edita o arquivo, o teste quebra igualzinho, ele responde "agora deve funcionar" e edita o mesmo arquivo de novo

Fala aí, beleza? Se essa cena te parece familiar, relaxa: não é o modelo que ficou burro no meio da sessão

Loop de correção quase sempre é problema de enunciado e de contexto, não de capacidade

O histórico da conversa já está entupido de tentativa que não deu certo, e o seu pedido continua sendo exatamente o mesmo pedido. Sem entrada nova, o espaço de solução não muda, e a saída tende a ser a mesma coisa com outras palavras

A boa notícia: quebrar o ciclo é mecânico. E o segredo não é esperar ele acertar na próxima tentativa, é interromper cedo…

Como saber que o Claude Code entrou em loop (e não só errou uma vez)

Errar uma vez é normal, faz parte. Loop é outra coisa, e ele tem assinatura própria

Os sinais:

• a mesma hipótese reaparece reescrita com palavras diferentes
• o mesmo arquivo é editado ida e volta, sempre nas mesmas linhas
• uma mudança é revertida e depois reaplicada como se fosse ideia nova
• o "agora deve funcionar" vira refrão

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

A causa: o histórico já contém todas as tentativas falhas, e o enunciado do problema continua o mesmo. O agente lê aquele raciocínio como o contexto mais forte que ele tem, então ele reincide. Não é teimosia, é o material que você deixou na mesa

E olha, nem todo loop é ruim. Loop de verificação, aquele em que o modelo confere o próprio trabalho, é feature, tipo a autocorreção por loops de verificação que já rolou papo por aqui. O problema é o loop de correção cega, que só empilha edição

A solução: parar de responder "tenta de novo" e tratar a repetição como sinal de intervenção sua

Como prevenir: cria um limite mental de duas tentativas. Falhou a segunda, você para e muda a entrada, não o pedido. Essa regra é sua, de bolso, não é configuração do produto

Passo 1: interromper com Esc antes que a tentativa termine

O sintoma: você deixa a execução ir até o fim "só pra ver no que dá", e o loop ganha mais uma rodada inteira de contexto ruim de graça

A causa: correção tardia produz ciclo de feedback longo. Quanto mais tarde você intervém, mais tentativa falha tem no histórico competindo com o seu redirecionamento

A solução: aperta Esc

A tecla interrompe a ação em andamento e o contexto da sessão é preservado, então você redireciona sem recomeçar do zero. A documentação oficial de boas práticas resume a orientação em uma frase: course-correct early and often, ou seja, corrija assim que perceber o desvio, e quantas vezes for preciso

O erro comum deste passo: tratar o Esc como último recurso, coisa de emergência. Ele é o primeiro recurso

Como prevenir: transforma o Esc em reflexo. Leu a segunda frase da resposta e já sentiu que o caminho está errado? Interrompe ali, não no final

Passo 2: desfazer as edições com Esc duas vezes ou /rewind

O sintoma: o arquivo virou um bolo de camadas de correção que não funcionaram, e ninguém sabe mais qual era o estado limpo

A causa: cada tentativa editou por cima da anterior, sem ninguém apagar o quadro no meio

A solução: Esc duas vezes (double tap) ou o comando /rewind abrem o menu de rewind

/rewind

E de onde vem esse histórico? Do checkpointing: o Claude Code captura automaticamente o estado do código antes de cada prompt do usuário, e guarda os snapshots dos arquivos referentes aos 100 checkpoints mais recentes

Ao escolher um checkpoint no menu, as opções são:

• restaurar código e conversa
• restaurar só a conversa
• restaurar só o código
• Summarize from here, pra resumir a partir dali
• Never mind, pra cancelar

Se nenhuma edição de arquivo foi capturada depois daquele ponto, o menu aparece reduzido: só restaurar conversa, as opções de resumo e o Never mind

Detalhe MUITO massa: os checkpoints são salvos junto com a conversa. Dá pra fechar o terminal, retomar a sessão depois e ainda usar o rewind

O erro comum deste passo: achar que o rewind desfaz tudo

Tome cuidado! O checkpointing rastreia apenas os arquivos editados pelas ferramentas de edição do Claude na sessão atual. Arquivo mexido por comando bash, os rm, mv e cp da vida, não volta pelo rewind

Como prevenir: se a sessão envolve comando bash mexendo em arquivo, o seu undo é o git, não o /rewind

Passo 3: limpar o histórico que está alimentando a mesma hipótese

O sintoma: você desfez o código, pediu de novo, e o agente voltou com a mesma explicação errada de antes

A causa: o código voltou, mas a conversa continua ali carregando o raciocínio falho. E aquele raciocínio segue sendo o contexto mais forte da sessão

A solução: limpar o que está alimentando a hipótese

/clear
/compact
/context

O /clear reseta a conversa para um contexto vazio, então os prompts seguintes começam sem nenhum histórico anterior. É o corte seco, ideal quando a sessão inteira apodreceu

O /compact reduz o tamanho do histórico resumindo mensagens antigas e preservando o contexto importante. Serve pra quando você não quer perder tudo, só quer tirar o peso morto

E o /context? Ele mostra um detalhamento ao vivo do uso do contexto por categoria, com sugestões de otimização, incluindo quais arquivos CLAUDE.md e de memória foram carregados. É o seu raio-x antes de decidir entre resumir e zerar

O erro comum deste passo: limpar a conversa e recomeçar do zero sem anotar nada. Aí você perde justamente o que já foi descartado nas tentativas, e o agente pode repetir hipótese velha achando que é nova

Como prevenir: roda /context quando a sessão começa a ficar longa, antes do loop aparecer, não depois

Passo 4: reescrever o enunciado do problema em vez de repetir o pedido

O sintoma: o prompt de retomada é "não funcionou, tenta outra vez"

A causa: esse pedido descreve o sintoma, não a evidência. Sem informação nova entrando, a hipótese não tem por que mudar. Você repetiu a pergunta e vai ganhar a mesma resposta, é justo haha

A solução: reescrever o problema com o que mudou

O teste X continua falhando depois da sua última edição.

Erro completo:
cole aqui a saída inteira, sem cortar o stack trace

Comportamento esperado: descreva o que deveria acontecer
Comportamento observado: descreva o que acontece de verdade

Já foi descartado nas tentativas anteriores:
- hipótese A (a edição no arquivo Y não mudou o resultado)
- hipótese B (o valor já chega correto nessa função)

Me dê uma hipótese DIFERENTE dessas duas antes de editar qualquer arquivo.

Repara no que esse enunciado faz: ele entrega erro completo, comportamento esperado versus observado, e a lista do que já morreu. É informação nova, e é isso que move a hipótese

O erro comum deste passo: colar só a última linha do erro. O stack trace inteiro costuma ser o que separa o chute do diagnóstico

Como prevenir: descrever esperado e observado desde o primeiro pedido, não só depois que o loop começou. Vale o mesmo raciocínio de escrever uma especificação que o agente consiga seguir: quanto mais preciso o enunciado, menos espaço pro chute

Passo 5: obrigar o diagnóstico antes de qualquer nova edição

O sintoma: o agente já sai editando arquivo antes de te explicar qual é a causa

A causa: sem etapa de investigação, cada rodada é um chute com custo de código. E chute com custo de código é exatamente o combustível do loop

A solução: plan mode

No plan mode o Claude pesquisa e propõe as mudanças sem executá-las. Você aciona pressionando Shift+Tab, que cicla os modos de permissão, ou prefixando um único prompt com /plan

/plan investigue a causa raiz da falha no teste X e me apresente
o diagnóstico antes de propor qualquer edição

Gostou do plano mas quer ajustar antes de liberar? Ctrl+G abre o plano proposto no seu editor de texto padrão pra edição direta, antes do Claude prosseguir. Bem massa pra cortar aquele passo 3 que você sabe que é besteira 🙂

O erro comum deste passo: achar que você continua protegido depois de aprovar

Aprovar um plano sai do plan mode e muda a sessão para o modo de permissão descrito na opção de aprovação que você escolheu. Pra planejar de novo, você precisa voltar com Shift+Tab ou usar /plan no próximo prompt

Como prevenir: regra simples, falhou a segunda tentativa, a terceira só sai com plano na mesa

Como evitar que o loop volte na próxima sessão

O sintoma: você quebrou o ciclo hoje, e amanhã, sessão nova, o mesmo padrão de insistência aparece de novo

A causa: a regra de comportamento só existiu naquele chat, e o chat você limpou

A solução: registrar a instrução em CLAUDE.md, que é lido pelo Claude no início de cada sessão

O escopo de projeto vive no repositório, na raiz como CLAUDE.md ou dentro de .claude/. O escopo global fica em ~/.claude/, valendo pra tudo que você tocar na máquina

## Depuração

- Se duas tentativas de correção falharem, pare de editar
- Apresente o diagnóstico da causa raiz antes de qualquer nova edição
- Nunca repita uma hipótese que já foi descartada nesta sessão

Uma pegadinha boa de saber: CLAUDE.md que está em subdiretório carrega sob demanda, quando o Claude lê um arquivo daquele diretório com a ferramenta Read, e não no início da sessão. Se a sua regra precisa valer sempre, ela não pode morar lá no fundo

Verificação: roda /context e confere a lista em Memory files pra ver o que realmente foi carregado

O erro comum deste passo: escrever um calhamaço de regras e nunca checar se ele carregou

Como prevenir: regra curta, no escopo certo, e um /context de vez em quando pra confirmar

Conclusão

O loop não quebra quando você repete o pedido

Ele quebra quando você muda a entrada: o código volta pro estado limpo, o histórico deixa de empurrar a hipótese velha, e o enunciado passa a carregar evidência que antes não existia

A sequência de bolso, na ordem:

1. Esc pra interromper na hora que você percebe o desvio, sem esperar terminar
2. Esc duas vezes ou /rewind pra desfazer as camadas de edição
3. /clear ou /compact pra tirar o raciocínio falho do caminho, com /context pra enxergar o que está carregado
4. reescrever o enunciado com erro completo, esperado versus observado e o que já foi descartado
5. /plan ou Shift+Tab pra exigir diagnóstico antes da próxima edição

Próximo passo prático: na próxima vez que você vir o mesmo arquivo sendo editado duas vezes seguidas sem resolver nada, não espera a terceira

Interrompe ali e roda a sequência

até o próximo post! 😀