Mapa da trilha
Conteúdo detalhado
🎯 A sequência de 7 passos
Sete decisões em ordem que transformam uma tarefa qualquer no seu primeiro loop rodando de verdade.
Escolha algo cujo "pronto" dá pra checar por fora da sua opinião: testes passam, formato bate, o script roda sem erro.
No 1º loop, estreite para algo com checker embutido — é o que faz o loop convergir em vez de vaguear.
Tarefa aberta × tarefa com checker; done-state verificável.
Uma frase: "Todo teste em /tests passa ao rodar npm test." Vira o done-state do loop.
Objetivo vago ("limpe isso") não dá no que terminar; o loop não sabe parar.
Objetivo numa frase; checável × vago.
Permita editar /src e /tests + rodar testes; SEM poder de merge ou deploy no 1º run. O worker abre um PR, o humano dá merge.
"Os guardrails são o trabalho de verdade, não os agentes." Permissão larga cedo = bagunça irreversível.
Permissões, guardrail, PR (pull request).
Peça pra escrever o progresso em PROGRESS.md e commitar a cada mudança relevante, pra retomar de onde parou.
O harness da Anthropic: ler estado → progresso incremental → self-verify → commit → deixar limpo.
PROGRESS.md, commit, retomar entre sessões.
Reunir contexto → 1 mudança → verificar (rodar testes) → repetir. UMA mudança por volta é deliberado.
"Trabalhar em uma feature por vez" foi crítico na pesquisa; uma mudança por volta faz o loop convergir.
Ciclo de 4 passos; granularidade da iteração.
"Pare quando todos os testes passarem, ou após 10 tentativas, o que vier primeiro." Os SDKs trazem max_turns.
Sem stop, você arrisca "bizarre emergent behavior" e uma conta de tokens que não para de crescer.
Hard stop, max_turns, teto de tentativas.
Assista o 1º run ao vivo; conserte as INSTRUÇÕES, não a saída. Quando falha, conserte o domínio da falha e jogue de volta na roda.
Huntley: "clay on the pottery wheel" — você modela o prompt, não a peça de cada vez.
Apertar o prompt; observar o run; o loop completo dos 7 passos.
🧪 Loops para copiar e rodar
Prompts prontos para colar no Claude Code — para código e para texto — com objetivo, bloco e como verificar.
Um prompt completo: objetivo (testes passam), loop de 4 passos, PROGRESS.md + commit, hard stop em 10, e o que não tocar.
É o template que você adapta para tudo. Cole, rode, observe.
Loop colável; objetivo + bloco + como verificar.
Mesma forma, outro trabalho: reescrever um parágrafo até ficar abaixo de 50 palavras E mencionar o preço.
O check é Functional — confere as regras (contar palavras, achar "preço"), não se lê bem.
Loop fora de código; check Functional; guardrail de 5 tentativas.
Juntos, /goal e /loop criam um loop que se dirige e se termina sozinho a partir do objetivo declarado.
Ex.: gerar 10 conceitos, pontuar por rubrica, iterar no melhor até a nota X.
/goal, /loop, self-directing, self-terminating.
Adicione ao prompt: "Pause e me pergunte antes de deletar, enviar ou pagar qualquer coisa."
É o check "You-decide": ações irreversíveis passam por você antes de acontecer.
Portão humano; ação irreversível; aprovação.
Ler o estado de PROGRESS.md, progredir em UMA feature, self-verify, commitar com nota, deixar limpo, repetir.
É o loop que sobrevive entre sessões e não se repete quando o contexto enche.
Estado externalizado; commit com nota; árvore limpa.
Troque o checker (Functional → Visual com screenshot, ou Judgment com 2º agente) e troque o domínio.
A forma do loop é a mesma; marque as partes que você troca e reuse em qualquer tarefa.
Functional × Visual × Judgment; template em branco.
🧰 8 ingredientes de um loop sólido
O checklist do que separa um loop que segura de um loop que desmonta no primeiro tropeço.
Defina "pronto" de um jeito que uma máquina verifica, não "deixe bom".
Sem um done-state checável, o loop não tem como saber que terminou.
Done-state; verificação por máquina.
Máximo de tentativas, orçamento ou tempo. Sempre.
É o que impede o loop de rodar pra sempre e queimar tokens à toa.
max_turns; orçamento; teto de tempo.
As ações que o agente toma precisam ser confiáveis e claramente descritas.
Ferramenta mal descrita = o modelo usa errado e o loop vira ruído.
Descrição clara; ação confiável.
Guarde o histórico, mas RESUMA para o contexto não inchar — um arquivo de notas.
Contexto cheio = o modelo perde o fio e custa mais caro.
Resumo; arquivo de notas; context window.
Gerar → julgar → consertar → repetir. O maker nunca dá a própria nota.
Quem fez o trabalho é o pior juiz dele; um checker separado segura a qualidade.
Maker → checker; evaluator-optimizer.
Job grande e multi-passo: peça um plano antes de agir. Job pequeno: pule o plano.
Planejar tudo é desperdício em tarefa pequena; não planejar quebra a tarefa grande.
Plano antes da ação; quando pular.
Salve cada pensamento, ação e resultado.
Quando o loop falha de madrugada, o log é a única coisa que conta o que aconteceu.
Trace de pensamento/ação/resultado.
Loops queimam tokens rápido; comece pequeno e limitado, depois escale.
Um loop sem teto e sem noção de custo vira surpresa na fatura.
Pequeno e limitado primeiro; escalar depois.
⚠️ Os 8 erros comuns
As oito armadilhas que derrubam quem está montando o primeiro loop — e a correção de cada uma.
O loop age, nunca checa, e entrega quebrado com confiança.
"Verifique seu trabalho" é o passo mais subestimado de todos.
Verificação ausente; lixo confiante.
"Melhore o código" não dá done-state; o loop fica girando sem alvo.
Objetivo vago é a causa nº 1 de um loop que nunca "termina".
Vago × checável; alvo do loop.
Iniciante supõe que o modelo para sozinho; muitos loops (Ralph) não têm parada do lado do modelo.
Ponha máximo de tentativas e assista o 1º run — a parada é sua, não do modelo.
Hard stop; Ralph; supervisão do 1º run.
Mandar consertar tudo de uma vez faz o loop debater-se; uma mudança por volta converge.
A Anthropic foi explícita: "uma feature por vez" foi crítico.
Granularidade; uma mudança por volta.
Deixar o 1º loop dar merge, deploy ou delete = bagunça irreversível.
Escope as permissões; o worker abre PR, ele não dá merge.
Escopo de permissões; PR em vez de merge.
Sem progress + commits, um loop além de 1 context window esquece o que já tentou e se repete.
Estado em disco é o que dá memória ao loop entre janelas de contexto.
Estado externalizado; context window.
Human-in-the-loop (portões de aprovação) é supervisão, não a cognição do agente.
Não copie um guia de HITL esperando um padrão de build do loop.
HITL = supervisão humana; loop de agente = cognição.
Entregar controle total ao loop e parar de ler a saída — o alerta de Osmani.
Você continua o revisor, sobretudo no começo.
Revisor humano; não abdicar do controle.