🔄 Desenhe o ciclo de execução
Um agente trabalha em ciclo: observar → entender → planejar → executar → testar → avaliar → corrigir → repetir. O que separa um loop de engenharia de um loop de esperança é a etapa de avaliar: é ali que se decide se a próxima volta tem sentido.
Como ler: o círculo à esquerda é o loop; as três caixas à direita são as únicas formas de sair dele. Se o seu loop hoje só tem a primeira (sucesso), ele não tem saída quando as coisas dão errado — e é exatamente aí que ele queima orçamento a noite inteira.
🆕 Novo aqui?
Loop aqui é o ciclo automático que o agente executa sozinho entre uma instrução sua e a próxima. Condição de parada é a regra que encerra o ciclo. Rollback é desfazer o que foi feito; fallback é seguir por um caminho alternativo quando o principal falha. São coisas diferentes: um volta, o outro contorna.
Avaliar
A etapa que quase somem
Sinal novo
Cada volta precisa de um
Três saídas
Sucesso, teto, desistência
Mensurável
Loop cego é custo cego
🎯 Estabeleça objetivo verificável e estado persistente
O agente precisa saber o que deve alcançar — em termos que um comando responde. E o sistema precisa registrar o que já foi feito, para que uma interrupção não jogue tudo fora.
✓ Objetivo que encerra o loop
- ✓"npm test retorna 0 e o teste X, que hoje falha, passa."
- ✓"O lint não reporta nenhuma ocorrência nova."
- ✓"Nenhum arquivo fora de src/x/ aparece no diff."
✗ Objetivo que nunca encerra
- ✗"Deixe o módulo mais robusto."
- ✗"Continue melhorando até ficar bom."
- ✗"Corrija todos os problemas que encontrar."
Estado mínimo que vale registrar entre voltas
tentativa: 2 de 3 hipótese atual: chave de idempotência não considera o valor já tentado: (1) índice único simples — falhou, mesma duplicidade arquivos tocados: src/pagamentos/idempotencia.ts, tests/idempotencia.test.ts último resultado: 128 passaram, 1 falhou
Com isso escrito, qualquer pessoa (ou o próprio agente após uma interrupção) retoma sem repetir o que já falhou.
Comando decide
Não a impressão
Hipótese
Cada volta tem uma
Já tentado
Evita repetição
Retomável
Interrupção não zera
🛑 Defina as condições de parada
Todo loop precisa saber quando encerrar. São três saídas — e a terceira, a parada por falta de progresso, é a que quase ninguém implementa.
Sucesso
O objetivo verificável foi atingido e a evidência está registrada (saída real do comando). O loop encerra e entrega para revisão.
Teto atingido
Tentativas, tempo ou custo estouraram. O loop encerra, preserva o estado e relata o que tentou — o trabalho parcial não se perde.
Sem progresso (a saída esquecida)
Duas tentativas seguidas com a mesma falha, ou o diff começou a crescer sem o teste avançar. O loop para e pergunta — resultado válido, não fracasso.
⚠️ Atenção
O agente encurralado tende a "resolver" a falha do jeito errado: relaxando a asserção, marcando o teste como pulado, ou capturando a exceção em silêncio. Se o loop pode editar testes, ele pode redefinir o próprio critério de sucesso — proíba isso explicitamente.
Sucesso
Com evidência anexa
Teto
Preserva o parcial
Parar e perguntar
É resultado válido
Teste intocável
Senão o critério some
💸 Controle tentativas, tempo e custo
Limite de tentativas evita que o agente fique repetindo a mesma ação. Limite de custo controla consumo de tokens, tempo e recursos. Os dois juntos transformam um risco aberto em um valor previsível por tarefa.
🧪 Exercício copiável — loop de correção de bug com limite
Objetivo: rodar um ciclo real de correção com condição de parada e sem edição de teste. Use um bug de verdade do seu repositório.
Bug: <descreva o comportamento errado> Como reproduzir: <passos ou comando> Siga EXATAMENTE este loop, sem pular etapas: 1. reproduza o erro e cole a saída real; 2. localize a causa e escreva a hipótese em uma frase; 3. escreva um teste NOVO que falha por causa desse bug (não altere testes existentes); 4. implemente a MENOR correção que faz esse teste passar; 5. rode <comando de teste> e cole a saída real completa; 6. me mostre o diff. Limites (obrigatórios): - no máximo 3 tentativas de correção; - se a mesma falha aparecer 2 vezes seguidas, PARE e me diga o que tentou; - não altere nem remova nenhum teste existente; - não adicione dependências; - no máximo 5 arquivos alterados. Se qualquer limite for atingido, pare e relate o estado — não continue.
Como verificar: confira três coisas no resultado — (1) existe um teste novo que falhava antes; (2) nenhum teste antigo foi modificado (git diff --stat nos arquivos de teste); (3) a saída colada é a real, não um resumo. Se o agente parou no limite, o exercício também deu certo: o loop funcionou.
Mesma falha 2x
Mude a estratégia
Menor correção
Mantém o diff revisável
Saída real
Resumo não é evidência
Custo por tarefa
Vira número previsível
↩️ Prepare rollback e fallback
Rollback permite voltar ao estado anterior. Fallback define uma alternativa quando o caminho principal não funciona. Onde não existe rollback, não deveria existir autonomia.
🧯 Reversibilidade por tipo de ação
- •Barato de desfazer: commit em branch, arquivo novo, container descartado. Pode ser autônomo.
- •Caro de desfazer: migração de banco, mudança de contrato de API pública. Exige plano de rollback escrito antes.
- •Impossível de desfazer: e-mail enviado, pagamento processado, dado apagado sem backup. Sempre humano.
💡 Dica prática
Antes de autorizar qualquer loop autônomo, responda: "se isso der errado às 3h da manhã, qual é o comando exato que desfaz?". Se você não sabe responder em uma linha, o loop ainda não pode rodar sozinho.
Rollback
Volta ao estado anterior
Fallback
Contorna o caminho
Migração
Reversível ou não vai
Autonomia
Limitada pela reversão
🙋 Insira aprovação humana no ponto certo
Aprovação humana interrompe o loop antes de ações críticas. Colocada em todo lugar, vira carimbo automático; colocada no ponto certo — imediatamente antes do irreversível — é o último controle real que você tem.
✓ Aprovação que funciona
- ✓Poucas, e sempre antes de algo irreversível
- ✓Com evidência anexada: diff, saída de testes, plano de rollback
- ✓Com um "não" fácil: rejeitar precisa custar menos que aprovar
- ✓Registrada: quem aprovou, quando e com base em quê
✗ Aprovação decorativa
- ✗Uma a cada passo — ninguém lê a partir da quinta
- ✗Sem evidência: "aprova?" com um resumo do próprio agente
- ✗Depois do fato consumado ("já apliquei, confirma?")
- ✗Para mudanças triviais e reversíveis, que poderiam ser automáticas
Checagem rápida: o loop tentou a mesma correção duas vezes e falhou igual nas duas. O que deve acontecer?
Antes do dano
Nunca depois
Com evidência
Não por confiança
Poucas
Muitas viram carimbo
Registrada
Quem, quando, por quê
📌 Resumo do Módulo
Próxima trilha:
Trilha 3 - Fluxo & Qualidade: automações, code review com IA e quality gates.