O que ver: os sinais de alerta de um loop mal montado. Cada luz vermelha aqui é um dos oito erros abaixo — e cada um tem uma correção simples. Leia este módulo como um checklist de "o que não fazer".
❌ Sem passo de verificação
O erro número um, de longe: o agente age e nunca confere. Ele edita, declara "feito" e segue em frente — entregando trabalho quebrado com toda a confiança do mundo. A Anthropic chama "verifique seu trabalho" de o passo mais subestimado de todos.
✗ O erro
O loop faz a mudança e passa direto para a próxima. Não roda os testes, não relê o objetivo. Resultado: polido, confiante e errado.
✓ A correção
Coloque um checker explícito em cada volta: "depois de cada mudança, rode os testes e leia a saída antes de continuar". Sem verificação, não há loop — só um chute repetido.
💡 Por que esse é o erro-mãe
Quase todos os outros sete erros pioram quando falta verificação. Um objetivo vago dói menos se você checa; um loop sem parada é menos perigoso se ele percebe que terminou. A verificação é o sentido observe do loop — tire ela e o agente fica cego.
🌫️ Objetivo vago
"Melhore o código." "Deixe bom." Um objetivo vago não dá ao loop nenhum done-state — nenhuma linha de chegada checável. Sem saber quando parou, o loop vagueia: muda coisas, desfaz, muda de novo, sem nunca convergir.
✗ O erro
- ✗"Melhore o código."
- ✗"Deixe isso mais limpo."
- ✗"Resolva os problemas."
✓ A correção
- ✓"Todo teste em /tests passa ao rodar npm test."
- ✓"O build compila sem warnings."
- ✓"Abaixo de 50 palavras e menciona o preço."
♾️ Sem condição de parada
O iniciante supõe que o modelo para sozinho. Ele não para. Muitos loops populares — como o Ralph — nem têm parada do lado do modelo: rodam até alguém apertar o botão. Sem um hard stop, você fica com comportamento estranho ou uma conta de tokens absurda.
Leia o diagrama: à esquerda, sem parada, o loop gira para sempre — queimando tokens. À direita, o hard stop ("pare quando os testes passarem ou após 10 tentativas") dá uma saída garantida. Sempre ponha um teto e assista o primeiro run ao vivo.
Quem é responsável por fazer o loop parar?
🐘 Fazer demais por volta
"Conserte tudo de uma vez." É tentador — e faz o loop se debater. A Anthropic foi explícita: trabalhar em uma feature por vez foi crítico para os agentes de longa duração convergirem. Uma mudança por volta dá ao checker algo pequeno e claro para avaliar.
✗ O erro
"Conserte todos os 12 testes e refatore o módulo." O loop muda dez coisas de uma vez, um teste novo quebra outro, e ele não consegue isolar o que deu errado. Vira um cabo de guerra com ele mesmo.
✓ A correção
"Conserte o teste da primeira falha. Verifique. Só então passe para a próxima." Uma mudança → uma verificação → repete. Pequeno e verificável converge; grande e ambíguo derrapa.
🧠 Por que "uma de cada vez" converge
Quando cada volta muda só uma coisa, a verificação isola exatamente o efeito dessa mudança. O loop ganha um sinal limpo: melhorou ou piorou? Com dez mudanças simultâneas, o sinal vira ruído — e o loop perde a bússola.
⚠️ Ferramentas perigosas cedo demais
Deixar o primeiro loop dar merge, deploy ou delete é receita para bagunça irreversível. No começo, o loop ainda erra — e um erro com poder de produção custa caro. Escope as permissões: o agente abre um PR, você dá o merge.
✗ O erro
Dar ao loop iniciante o poder de git push --force, deploy em produção ou rm. Um passo errado e o estrago não tem desfazer.
✓ A correção
No primeiro run, permita só editar arquivos e rodar testes. Ações irreversíveis ficam atrás de um gate humano: o loop abre o PR, você aprova.
💾 Não salvar estado
Um loop que roda além de uma context window e não escreveu nada em disco esquece o que já tentou — e repete os mesmos becos sem saída. A cura é barata: um arquivo de progresso (PROGRESS.md) e commits frequentes.
✗ O erro
O loop tenta uma abordagem, ela falha, a context window enche, o registro daquela tentativa some — e o loop tenta exatamente a mesma coisa de novo. Anda em círculos sem perceber.
✓ A correção
"A cada mudança relevante, anote 1 linha em PROGRESS.md e commite." O loop relê esse arquivo no começo de cada volta e retoma de onde parou — memória externa que sobrevive à janela.
🔀 Confundir os 2 sentidos de "loop"
A palavra "loop" tem dois sentidos que vivem sendo trocados. Um é o loop de agente (a cognição reason→act→observe). O outro é human-in-the-loop (HITL): portões onde um humano aprova antes do agente seguir. São coisas diferentes — e copiar um guia de HITL achando que é um padrão de build te deixa perdido.
🔁 Loop de agente
A cognição do agente: pensar → agir → observar, repetindo até "pronto". É o que você projeta quando monta o loop. É sobre como o agente raciocina.
🙋 Human-in-the-loop
Um portão de aprovação: o humano confirma antes de uma ação sensível. É supervisão, não a mente do agente. Útil — mas não é um padrão de build de loop.
⚠️ A armadilha na prática
Você busca "como construir um loop de agente", cai num tutorial de HITL cheio da palavra "loop", e sai com um fluxo de aprovação — não com a cognição que queria. Sempre cheque: o guia descreve como o agente pensa (build) ou quando o humano aprova (supervisão)?
🛋️ Cognitive surrender
O último erro é o mais sutil. Addy Osmani chama de cognitive surrender: entregar o controle total ao loop e parar de ler a saída. O loop é bom — mas você continua o revisor, sobretudo no começo. Confiança cega é como um bug entra em produção sorrindo.
✗ O erro
Você dispara o loop, vai tomar um café, volta e dá merge sem ler. Funciona nas primeiras vezes — até a vez em que ele "conserta" deletando metade dos testes e você não percebe.
✓ A correção
Assista os primeiros runs ao vivo. Leia o diff antes de aprovar. Vá soltando a rédea só quando o loop provar que merece — e mesmo assim, amostre a saída de vez em quando.
💡 Você no comando, não na poltrona
Um loop bem montado aumenta o seu alcance — não substitui o seu julgamento. O objetivo é delegar a execução repetitiva, mantendo você como o revisor que define "pronto" e bate o olho no resultado. Engenharia de loops é exatamente isso: projetar o sistema, não abdicar dele.
🧾 Resumo do Módulo
Próximo:
Trilha 4 — Loop Engineering: pare de promptar, projete loops.