IA fugiu da spec no meio da implementação: como corrigir o rumo sem perder o trabalho

Fala aí, beleza? Você escreveu a spec, mandou o agente implementar, foi buscar um café e voltou com cinco arquivos mexidos e uma solução que não é nem parecida com o que você pediu

O problema não é a IA errar, isso vai acontecer de novo amanhã

O problema é o tempo entre o erro acontecer e você descobrir

A documentação de boas práticas do Claude Code é bem direta nisso: corrija o rumo assim que perceber o desvio, porque loops de feedback curtos produzem soluções melhores e mais rápidas do que esperar o agente terminar errado

Neste post a gente vai ver como perceber cedo, como decidir entre corrigir o código ou corrigir a spec (sim, às vezes a errada é a spec) e como retomar sem jogar fora o que já foi feito

O que você precisa ter antes de tentar corrigir o rumo

Correção de rumo não é mágica, é uma coisa que só funciona se você já tinha três coisas no lugar

• Uma spec escrita em algum lugar: um arquivo, um plano aprovado no modo de planejamento ou os artefatos do Spec Kit (spec.md, plan.md, tasks.md). Se a spec só existe na sua cabeça, não tem como dizer que o agente fugiu dela, tu só vai ter uma sensação ruim
• Git em dia: a própria documentação recomenda continuar usando controle de versão para histórico permanente, porque checkpoint é recuperação em nível de sessão e não substitui commits e branches
• Noção do alcance do desfazer: o Claude Code guarda snapshots de arquivo dos 100 checkpoints mais recentes da sessão, e apaga os checkpoints junto com as sessões depois de 30 dias

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Que checkpoint, afinal?

É um snapshot automático do estado do código, tirado antes de cada prompt que você envia, e também antes de cada edição feita pelas ferramentas de edição de arquivo

Ou seja: enquanto você conversa, o histórico vai sendo montado sozinho, sem você pedir 🙂

Só não confunda isso com backup eterno, porque não é

Passo a passo para corrigir o rumo sem perder o trabalho

1. Pare o agente na hora, com Escape

Dá pra interromper o Claude Code em qualquer fase: raciocínio, chamada de ferramenta ou edição de arquivo

E o contexto é preservado, então você redireciona ou amplia as instruções em cima do que já estava rolando

O erro comum deste passo: mandar um prompt novo por cima enquanto o agente ainda escreve, esperando que ele "escute". Para primeiro, fala depois

2. Leia o que já foi feito e compare com a spec antes de mandar qualquer correção

Aqui é onde a maioria queima o trabalho

Você olha um arquivo torto e conclui que tudo está torto

Na real, muita coisa costuma estar certa: o desvio quase sempre é um pedaço, não a implementação inteira

O erro comum deste passo: apagar tudo por reflexo e recomeçar do zero, pagando de novo por um trabalho que em boa parte já estava de pé

Vale lembrar que cada rodada de correção consome contexto e, dependendo da ferramenta, consome cota também: se você roda em plano gratuito, dá uma olhada em até onde vai o plano gratuito antes de sair reimplementando por esporte

3. Abra o menu de rewind

O menu abre com o comando /rewind ou pressionando Esc duas vezes com o campo de prompt vazio

/rewind

Ele lista os prompts enviados na sessão e oferece quatro ações:

• restaurar código e conversa
• restaurar só a conversa (mantendo o código atual)
• restaurar só o código (mantendo a conversa)
• resumir a conversa daquele ponto em diante

Escolha conforme o que está podre: se o código desandou mas o raciocínio da conversa é bom, restaure só o código. Se o agente entendeu errado lá atrás e vem carregando o mal-entendido, é a conversa que precisa voltar

O erro comum deste passo: apertar Esc duas vezes com texto no campo de prompt. Nesse caso o Esc duplo limpa o texto em vez de abrir o menu, e aí vem aquela cara de "não funcionou" 😀

4. Decida o alvo da correção: o código ou a spec

Esse é o passo que ninguém faz e que muda tudo

Se a spec estava certa e o agente saiu da linha, o alvo é o código

Agora, se durante a implementação apareceu uma restrição real que a spec ignorava, o alvo é a spec

Insistir em implementar uma spec que a realidade já derrubou é o retrabalho mais caro que existe

5. Reescreva a instrução e retome, verificando contra o plano

A orientação para problema complexo é a abordagem em duas fases: separar pesquisa de codificação, revisar o plano, refinar por conversa e só então deixar o agente implementar, verificando o resultado contra o plano

Na retomada, seja específico sobre o que muda e o que fica: "mantenha o que está em X, refaça só Y, seguindo a spec"

O erro comum deste passo: retomar com um "agora faz direito", que não diz nada sobre qual parte estava errada e convida o agente a reescrever o que já estava bom

Corrigir o código ou corrigir a spec: como escolher

Quando o alvo é a spec, ainda tem uma bifurcação

A documentação do Spec Kit descreve dois modelos de persistência para quando a implementação muda o seu entendimento: flow-forward (cada pasta de feature vira registro histórico e a mudança substancial vira uma nova spec) e flow-back (a descoberta da implementação reescreve os artefatos existentes, editando primeiro onde o insight apareceu, seja spec.md, plan.md, tasks.md ou o código)

O alerta que vem junto do flow-back merece atenção: não deixe uma mudança de nível mais baixo parada em tasks.md ou no código enquanto o spec.md ainda diz outra coisa

Se você fizer isso duas ou três vezes, a spec deixa de ser confiável, e aí não adianta reclamar que o agente não segue a spec

Quando o rewind não devolve o que você esperava

Tem três casos clássicos em que o desfazer engana, e todos machucam mais porque você acha que está protegido

Arquivo mexido por comando bash não volta

Sintoma: você restaura o código, mas o arquivo continua sumido ou continua no lugar novo

Causa: o checkpointing não rastreia arquivos modificados por comandos bash, como os rm, mv e cp da vida. Só edições diretas feitas pelas ferramentas de edição de arquivo entram no snapshot

Solução: git. É ele que devolve arquivo apagado por comando

Como prevenir: commit antes de sessão que vai mexer em estrutura de pastas, e desconfiança saudável com qualquer passo que envolva mover ou remover coisa em massa

Edição de subagente não entra no checkpoint

Sintoma: o rewind volta a sessão, mas as mudanças que um subagente fez continuam lá

Causa: edições feitas por subagentes normalmente não entram nos checkpoints da sessão, e o rewind não as restaura

Solução: a orientação é usar git para reverter esse tipo de mudança

Como prevenir: quando o trabalho vai ser delegado para subagente, trate a sessão como se não tivesse desfazer nenhum e trabalhe em branch

Estado misto: conversa de um ponto, código de outro

Sintoma: o agente fala de um código que não existe mais, ou edita como se o arquivo estivesse na versão antiga

Causa: você escolheu restaurar só a conversa (mantendo o código atual) ou só o código (mantendo a conversa), e as duas linhas do tempo ficaram fora de sincronia

Solução: volte ao menu e restaure código e conversa juntos, ou use a ação de resumir a conversa daquele ponto em diante para o agente reancorar no estado real

Como prevenir: antes de escolher a ação, responda pra você mesmo: o que está errado aqui é o arquivo ou o entendimento? Escolher no automático é o que gera o estado misto

Detalhe importante: isso é diferente de ferramenta travada, que é outro tipo de problema e tem outro tipo de saída, mais parecido com quando o ChatGPT trava e você precisa recuperar a sessão em vez do código

Como reduzir a chance de a IA fugir da spec de novo

Corrigir rumo é ótimo, não precisar corrigir é melhor ainda

Use o modo de planejamento antes de qualquer edição em disco

Ele é ativado com Shift+Tab (o ciclo de modos é default, acceptEdits e plan) ou prefixando um único prompt com /plan, e a barra de status mostra quando o plan mode está ativo

Nesse modo o Claude lê arquivos e propõe um plano sem fazer nenhuma edição em disco até você aprovar, e você sai do modo aprovando o plano ou apertando Shift+Tab de novo

É o momento mais barato de discordar: discordar de um plano custa uma frase, discordar de uma implementação custa uma tarde

Separe pesquisa de codificação em problema complexo

Revisar o plano, refinar por conversa e só então implementar, verificando o resultado contra o plano

Se você trabalha no VS Code, o plano abre como um documento Markdown completo, onde dá pra deixar comentários inline como feedback antes de o agente começar

Comentar ponto a ponto no plano é MUITO mais preciso do que escrever um parágrafo genérico de correção depois

Rode a checagem de consistência entre tasks e implement

Se você usa o github/spec-kit, toolkit de desenvolvimento orientado a especificação mantido pela GitHub, o fluxo central é Spec, Plan, Tasks e Implement, com os comandos rodando dentro de agentes como Claude Code, Copilot e Cursor

/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.analyze
/speckit.implement

O /speckit.analyze faz uma análise não destrutiva de consistência entre spec.md, plan.md e tasks.md, apontando inconsistências, duplicações, ambiguidades e itens subespecificados

Ele roda depois de /speckit.tasks e antes de /speckit.implement, exatamente no ponto em que corrigir ainda é barato, e não altera os artefatos por conta própria

Barre antes, não depois

Hooks PostToolUse não conseguem desfazer ação nenhuma, porque a ferramenta já executou: eles só avisam depois do estrago

Quando a ação precisa ser impedida de acontecer, o evento é o PreToolUse, cujo retorno permissionDecision com valor deny bloqueia a ferramenta mesmo em bypassPermissions ou com --dangerously-skip-permissions

Tome cuidado com a confusão entre os dois, é o tipo de coisa que só aparece no dia em que você precisava do bloqueio de verdade

Conclusão

Divergência não é acidente raro, é parte do ciclo de trabalhar com agente

O que separa o retrabalho caro da correção barata é o tamanho do loop de feedback: quanto antes você para, menos código torto tem pra desfazer

Recapitulando o caminho: Escape para parar em qualquer fase com o contexto preservado, leitura do que já foi feito, /rewind (ou Esc duplo com o campo vazio) para escolher entre restaurar código, conversa, os dois ou resumir dali em diante, decisão consciente entre corrigir o código ou a spec, e retomada verificando contra o plano

E lembre que o desfazer tem buraco: comando bash e edição de subagente não voltam pelo checkpoint, quem resolve isso é o git

Próximo passo pra próxima sessão: defina de antemão o seu gatilho de parada (o sinal que faz você apertar Escape sem pensar duas vezes) e, depois de cada mudança, realinhe a spec e os artefatos

Spec desalinhada por muito tempo deixa de ser confiável, e aí o agente não tem mais como seguir uma coisa que nem você segue mais

até o próximo post!