Engenharia com agentes · retrabalho

O problema não é o agente. É a ausência de passos.

Ulisses Hen, Tech Lead26 JUL 2026 · SOBRE CLAUDE CODE, CODEX E DIFFS GRANDES DEMAIS

Todo dev que usa agente de código já viveu esta sequência: você cola o ticket, o agente responde com confiança, o terminal roda por alguns minutos e devolve um diff que parece certo. Você abre o PR. Aí começa o trabalho de verdade.

~/projeto · git

$ git diff --stat
 src/api/orders.ts            |  84 ++++++++++++-----
 src/api/orders.test.ts       |  12 ++
 src/domain/pricing.ts        | 141 +++++++++++++++++--------
 src/domain/discount.ts       |  63 +++++++---
 src/ui/CheckoutPanel.tsx     | 210 ++++++++++++++++++++-------
 prisma/schema.prisma         |  18 +++
 ... 28 arquivos não listados
 34 files changed, 1.812 insertions(+), 604 deletions(-)

$ npm test
 ✓ 118 passing   ✗ 0 failing   (nenhum teste novo cobre a regra pedida)

Verde não é evidência. É ausência de contradição.

Trinta e quatro arquivos. Suíte verde. E nenhuma linha do diff prova que a regra de negócio que você pediu foi implementada do jeito que você pensou. A revisão vira arqueologia: você reconstrói a intenção lendo o código do próprio agente.

Escrever código ficou barato. Decidir, validar e assinar continuam sendo o trabalho. E é aí que o agente não te ajuda por padrão.

Escrevo isso depois de mais de 10 aplicativos construídos com IA, do primeiro ChatGPT (colando função por função) aos agentes de hoje rodando no terminal. O padrão de falha nunca mudou. Só ficou mais rápido.

Por que o retrabalho aparece sempre nos mesmos quatro pontos

1. Objetivo nebuloso. Ticket é resumo, não especificação. O agente preenche as lacunas com suposições plausíveis e segue em frente sem sinalizar nada.

2. Contexto sem curadoria. Você joga a pasta inteira no contexto. Arquivos irrelevantes competem pela atenção do modelo e a qualidade cai de forma silenciosa.

3. Feedback tardio. A primeira validação acontece depois de dezenas de arquivos alterados. Corrigir ali custa dez vezes mais que corrigir na terceira linha.

4. Revisão sem referência. Sem um artefato que registre a intenção, não existe critério de aprovação. O PR passa por confiança.

OBSERVAÇÃO INCÔMODA

Nenhum desses quatro problemas é resolvido por um prompt melhor. Todos são resolvidos por ordem de execução e por artefato obrigatório no fim de cada etapa.

O método como changelog: seis passos, seis artefatos

PILOTO é a sequência que uso para conduzir o agente. Cada passo tem uma pergunta que precisa ser respondida e um arquivo que precisa existir antes de avançar. Se o artefato não existe, o passo não fechou, e você não pede código.

[P]PASSO FECHADO

Problema

O agente entrevista você até não sobrar decisão escondida. Escopo, critério de aceite e o que fica de fora.

artefato: briefing.md

[I]PASSO FECHADO

Insumos

Contexto mínimo e confiável: os arquivos que importam, um exemplo interno de padrão e os comandos de validação do repositório.

artefato: contexto-minimo.md

[L]PASSO FECHADO

Limites

Protótipo descartável para matar a dúvida técnica; spec curta para congelar as decisões antes de existir código de produção.

artefato: spec.md

[O]PASSO FECHADO

Organização

Fatias verticais demonstráveis. Nada de "ticket do banco, ticket da API, ticket da UI". Cada fatia roda e prova algo.

artefato: ticket-vertical.md

[T]PASSO FECHADO

Testes

Execução test-first num seam acordado. Um comportamento por ciclo, evidência antes de seguir para o próximo.

artefato: log de execução verde por ciclo

[O]PASSO FECHADO

Observação

Revisão em dois eixos (intenção versus padrões do repositório) antes de abrir o PR. A decisão final é sua, com base em evidência.

artefato: review.md + PR pequeno

CHECKLIST DE VOO · ANTES DE PEDIR CÓDIGO

briefing.md existe e não tem pergunta aberta
lista de arquivos do contexto tem justificativa item por item
spec.md caberia em uma tela
a primeira fatia é demonstrável em menos de 10 minutos
o comando de teste está escrito e roda localmente
existe um critério objetivo de "pronto"

O efeito prático é chato de tão previsível: os diffs encolhem, o número de idas e voltas cai e a revisão deixa de ser interpretação para virar conferência. Não é mágica. É a mesma disciplina que você já aplica em código humano, aplicada antes de o agente começar a digitar.