Explorar, Planejar, Codificar, Commit: O Lugar Mais Barato de Corrigir um Agente É Antes do Código

A maioria dos times que usa um agente de código cola um prompt e deixa o agente digitar. O modelo escreve código. O engenheiro reage ao diff. Cada correção nesse estágio reescreve o que já foi escrito. O hábito caro se esconde à vista: ninguém planejou o trabalho antes do agente começar a gastar tokens para produzi-lo.

O fluxo canônico da Anthropic para o Claude Code tem um nome para o oposto desse hábito. Explorar, Planejar, Codificar, Commit. A estrutura é simples e a disciplina é deselegante: o agente não pode editar nada até que o plano seja aprovado. O modo plano é somente leitura. O humano revisa o plano, não o código. Quando o plano está bom, o trabalho prossegue.

Essa inversão muda a economia do desenvolvimento com agentes. O custo de corrigir um desenho ruim em um plano é algumas frases de texto. O custo de corrigir o mesmo desenho ruim em 500 linhas de diff é o diff somado à reexecução de testes, somado ao ciclo de revisão, somado à faxina do histórico de commits. Times pulam o modo plano porque a musculatura organizacional ainda recompensa digitação visível. Pagam o pulo em retrabalho.

As Quatro Fases, Em Ordem

O fluxo tem quatro fases. Cada uma corresponde a uma postura diferente que o agente e o humano assumem diante do trabalho.

Explorar. O agente lê arquivos, roda buscas e forma um mapa mental de onde a mudança pertence. Ainda não propõe ações. Está descobrindo o que não sabe.

Planejar. Acionado com Shift+Tab no Claude Code, o modo plano trava o agente em postura de leitura. O agente continua podendo ler, buscar e raciocinar. Não pode editar, não pode rodar comandos de shell que mutam estado, não pode criar arquivos. Produz uma lista numerada das ações que pretende executar. O humano lê a lista e aprova, edita ou rejeita.

Codificar. Com o plano aprovado, o agente percorre as ações propostas e as executa. O plano vira checklist, não sessão livre. Desvios ficam visíveis porque o plano está visível.

Commit. Antes de a mudança virar commit, um subagente revisor de código inspeciona o diff. Depois o agente gera a mensagem de commit no estilo do time. O humano aprova o commit.

A ordem importa. Cada fase é mais barata de corrigir do que a próxima. Correção na exploração custa uma busca. Correção no plano custa uma frase. Correção no código custa um diff. Correção no commit custa o diff somado à trilha de auditoria. Times que pulam direto do prompt para o código escolhem a superfície de correção mais cara como primeira linha de defesa.

O Exemplo Canônico

O tutorial da Anthropic usa um prompt concreto para demonstrar o formato: “Preciso adicionar conversão WebP ao nosso pipeline de upload de imagens. Descubra onde no pipeline isso deveria acontecer, se precisamos de novas dependências e como abordar.”

Repare no que o prompt não diz. Não diz “escreva o código”. Não diz “abra o arquivo e comece”. Diz “descubra e proponha”. Esse enquadramento coloca o agente em postura de explorar-e-planejar por padrão. O agente lê os arquivos do pipeline, roda uma busca na web para checar boas práticas atuais e devolve um plano. O humano lê o plano e decide se a dependência proposta, o ponto de inserção proposto e o tratamento proposto para casos de borda estão certos. O humano está revisando seis linhas de plano, não 200 linhas de diff.

Se o plano está errado, a conversa continua no modo plano. Se o plano está certo, o humano aprova e o agente prossegue. A primeira linha de código é a primeira linha de código que já passou pela revisão de desenho.

Três Superfícies de Verificação

O fluxo presume verificação, e a Anthropic recomenda três superfícies que o agente deve aprender a usar.

A primeira é a suíte de testes como fonte da verdade. O agente roda os testes continuamente enquanto codifica e trata o resultado como sinal autoritativo de que o trabalho está pronto. Testes verdes não provam correção, mas removem a classe de afirmações “acho que funciona” que poluiu o primeiro ano de desenvolvimento com agentes.

A segunda é o controle de navegador para trabalho de UI. O Claude consegue dirigir uma aba Chrome via MCP, abrir a aplicação em execução e verificar que a mudança se comporta como pedido antes de dizer que terminou. O agente não apenas compila a mudança. Confere se a mudança faz o que foi pedido na superfície que um usuário tocaria.

A terceira é o arquivo Claude.md. Correções recorrentes, convenções do repositório e decisões que o time já tomou ficam registradas no Claude.md para que o agente pare de redescobri-las. Trate o Claude.md como memória institucional do agente. Toda vez que um revisor colar a mesma correção duas vezes, na terceira essa correção pertence ao Claude.md.

Por Que o Modo Plano É Importante Arquiteturalmente

O modo plano não é firula de UX. É uma fronteira de contenção no perímetro do loop central do agente. Já escrevemos sobre a arquitetura de while-loop no coração do Claude Code: o agente é um loop que decide uma chamada de ferramenta, executa, observa o resultado e decide a próxima chamada. O loop é rápido e capaz. O loop também é caro quando produz trabalho que precisa ser descartado.

O modo plano envolve o loop. Dentro do modo plano, o catálogo de ferramentas do agente fica restrito a operações de leitura. O raciocínio segue igual. A saída é uma proposta, não um efeito colateral. O humano inspeciona a proposta e aprova ou manda o agente pensar de novo. O loop caro só roda contra trabalho que o humano já endossou.

É o mesmo instinto de contenção que move o agent harness e os primitivos de harness que defendemos: a confiança sai do por-ação e vai para o por-ambiente, e o ambiente agora inclui uma fase em que o agente raciocina sem consequências. A economia é estrutural. Você não está pegando o trabalho ruim depois de escrito. Está pegando antes de ser escrito.

Onde os Times Empacam

A falha mais comum não é técnica. É organizacional. Engenheiros se sentem produtivos quando veem código sendo digitado. O modo plano não produz digitação. Produz deliberação. Para uma cultura que premia movimento visível, deliberação parece agente travado.

A correção é medir retrabalho em vez de throughput. Conte quantas vezes uma mudança foi comitada, revertida e re-comitada na mesma semana. Conte quantos PRs precisaram de um segundo ciclo de mudanças substantivas depois da primeira revisão. Os dois números caem quando o modo plano é obrigatório. Os dois números permanecem altos quando o time pula o modo plano e reage a diffs.

A segunda falha é tratar o modo plano como atrito opcional. É opcional do mesmo jeito que usar cinto de segurança é opcional. O custo é pequeno. A perda esperada na pequena fração de casos em que o plano estava errado é enorme. Times aprendem isso depois da primeira vez que um agente refatorou com confiança o arquivo errado em escala de produção.

Faça Isso Agora

Escolha um repositório esta semana. Estabeleça a regra: toda mudança feita com agente de código passa pelo modo plano. O humano aprova o plano antes de qualquer arquivo ser editado. O plano vai na descrição do PR para que o revisor veja o que foi proposto e o que foi entregue.

Adicione um Claude.md ao repositório se ainda não houver. Coloque três coisas: o comando de teste, o comando de lint e as três correções que o time precisou repetir nas últimas quatro semanas. Atualize toda sexta-feira.

Crie um subagente revisor de código para a etapa de commit. Antes do commit, o revisor lê o diff contra o plano e sinaliza desvios. O humano segue dono do merge. O revisor é um segundo par de olhos barato que roda sempre, e não nas vezes em que alguém lembra de pedir.

Duas semanas depois, conte o retrabalho. Compare com o mês anterior. O número que cair é o número que decide se o time consegue escalar desenvolvimento assistido por agente sem escalar o custo de consertar o que o agente já escreveu.

Fontes

Anthropic. “The Explore → Plan → Code → Commit workflow in Claude Code.” Maio de 2026.
Anthropic Docs. “Claude Code overview.” 2026.
Anthropic Docs. “Claude Code sub-agents.” 2026.

A Victorino ajuda times de engenharia a adotarem fluxos nativos para agentes sem perder a disciplina de revisão: contato@victorino.com.br | www.victorino.com.br