Como manter seu agente de codificação de IA nos trilhos: explorar, planejar, depois construir

Quando as pessoas usam pela primeira vez uma ferramenta de codificação agêntica como o Claude Code ou o Cursor, elas tendem a digitar um pedido de uma linha e torcer. Às vezes funciona. Muitas vezes o agente, com confiança, constrói a coisa errada — resolvendo um problema sobre o qual você não perguntou, mexendo em arquivos que você não esperava ou pulando o caso de borda que realmente importava.

A solução não é um modelo mais esperto. É um fluxo de trabalho: explorar primeiro, depois planejar, depois construir. Esse é o padrão que a Anthropic recomenda em seu guia oficial de boas práticas do Claude Code, e a mesma ideia se aplica a qualquer agente que consiga ler seu repositório antes de editá-lo.

Por que pular direto para o código falha

Um agente de IA trabalha dentro de uma janela de contexto limitada — o registro corrente da sua conversa mais cada arquivo que ele lê e cada comando que ele roda. Duas coisas dão errado quando você pula o planejamento:

1. O agente adivinha a intenção. Ele não consegue ler sua mente, então um prompt vago recebe uma implementação plausível, porém errada.
2. Os erros se acumulam em silêncio. Quando o agente começa a editar, uma suposição errada no primeiro passo fica enterrada sob mais dez mudanças antes de você perceber.

Separar o pensar do fazer pega a suposição errada enquanto ainda é barato corrigir — uma frase de correção em vez de reverter 12 arquivos.

Passo 1: Explore em um modo somente leitura

A maioria dos agentes sérios agora tem um modo em que eles podem ler e analisar, mas não podem mudar nada. No Claude Code ele se chama plan mode: um estado somente leitura em que o agente lê arquivos e responde perguntas sem editar, rodar comandos que alteram estado ou commitar.

Comece pedindo ao agente para entender o código, não mudá-lo:

Leia /src/auth e explique como lidamos com sessões e login.
Veja também como gerenciamos variáveis de ambiente para segredos.

Você está construindo um contexto compartilhado e verificando se o agente realmente entende seu código antes de confiar nele para modificá-lo.

Passo 2: Peça um plano e depois questione-o

Uma vez que o agente explorou, peça um plano concreto antes de qualquer código:

Quero adicionar login com Google OAuth. Quais arquivos precisam mudar?
Qual é o fluxo de sessão? Escreva um plano passo a passo — não escreva código ainda.

O agente devolve um plano numerado: quais arquivos vai tocar, o novo fluxo de sessão, onde vai armazenar os tokens. Agora não aceite o primeiro rascunho. Este é o momento mais barato para corrigir o rumo. Pressione nos pontos fracos:

• "O que acontece se o callback do OAuth falhar no meio?"
• "Já temos um helper refreshToken em src/auth/tokens.ts — reutilize-o em vez de escrever um novo."
• "Restrinja isso apenas ao fluxo de login. Não mexa no código de redefinição de senha existente."

Alguns minutos refinando o plano aqui economizam uma hora desembaraçando uma implementação errada depois.

Passo 3: Construa com uma forma de verificar

Só agora você deixa o agente escrever código — e lhe dá uma forma de checar o próprio trabalho. A adição mais poderosa a qualquer prompt é um passo de verificação que o agente possa rodar sozinho:

Implemente o fluxo de OAuth do seu plano. Escreva um teste para o handler
do callback cobrindo o caso de falha, rode a suíte de testes e corrija quaisquer falhas.

Sem uma verificação que ele possa rodar — testes, um build, uma captura de tela para comparar — "parece pronto" é o único sinal que o agente tem, e você vira o detector de erros de cada deslize. Com uma verificação, o ciclo se fecha sozinho: o agente escreve, roda o teste, lê o resultado e itera até passar. Peça que ele mostre a saída real do teste, em vez de só alegar sucesso.

Passo 4: Saiba quando pular o plano

Planejar tem custo, e nem sempre vale a pena. Se a mudança é pequena e o escopo é óbvio — corrigir um erro de digitação, adicionar uma linha de log, renomear uma variável — apenas peça ao agente para fazer direto. Uma boa regra prática do guia da Anthropic: se você consegue descrever o diff em uma frase, pule o plano. Reserve o ciclo explorar-planejar-construir para trabalho que abrange vários arquivos, usa uma abordagem da qual você não tem certeza ou mexe em código que você não conhece bem.

Uma rede de segurança: corrija o rumo cedo e use checkpoints

Mesmo com um bom plano, os agentes derivam. Dois hábitos te mantêm no controle:

• Interrompa no momento em que ele sai dos trilhos. Não espere o agente terminar uma abordagem errada. No Claude Code, Esc o interrompe no meio da ação com o contexto preservado, para que você possa redirecionar.
• Use checkpoints para experimentar livremente. O Claude Code tira um snapshot dos seus arquivos antes de cada mudança, então você pode pedir ao agente para tentar algo arriscado e, se não der certo, voltar (Esc Esc ou /rewind) e tentar uma abordagem diferente. (Os checkpoints rastreiam as próprias edições do agente, não processos externos — são uma conveniência, não um substituto do git.)

E se você se pegar corrigindo o mesmo erro mais de duas vezes, o contexto provavelmente está poluído por tentativas frustradas. Limpe-o e recomece com um prompt mais afiado que já incorpore o que você acabou de aprender — uma sessão limpa com um prompt melhor quase sempre vence uma longa, cheia de becos sem saída.

A conclusão

Explorar, planejar, construir, verificar. Parece mais lento na primeira tarefa e se paga já na segunda. Você para de receber código confiante-porém-errado e passa a ter um agente que constrói a coisa que você realmente quis dizer.