O que ver: sete marcos em fila. Cada seção abaixo é um marco. Você não precisa adivinhar nada — só seguir o caminho, da esquerda para a direita, e no fim tem um loop rodando.
🎯 Escolha uma tarefa com resposta certa
O primeiro passo decide o sucesso de todos os outros: pegue uma tarefa cujo "pronto" seja checável por algo além da sua opinião. Os testes passam, o formato bate, o script roda sem erro. Se só você sabe dizer se ficou bom, o loop não tem como saber que terminou.
✓ Resposta certa (bom 1º loop)
- ✓"Fazer o teste que está falhando passar."
- ✓"Converter este CSV para JSON no formato X."
- ✓"Fazer o script rodar sem lançar erro."
✗ Resposta de opinião (evite por agora)
- ✗"Deixar o site mais bonito."
- ✗"Melhorar a arquitetura."
- ✗"Escrever um texto envolvente."
🧭 O conselho da Anthropic, lido com cuidado
A Anthropic recomenda o loop para tarefas abertas, onde você não consegue prever os passos com antecedência. Verdade — mas no seu primeiro loop, estreite o escopo para algo que tenha um checker embutido. Aberto na execução, fechado na checagem: o agente descobre o caminho, e um teste decide se chegou.
📝 Escreva o objetivo numa frase
Agora cristalize a tarefa em uma frase que descreve o estado final. Exemplo: "Todo teste em /tests passa ao rodar npm test." Essa frase vira o done-state — o sinal exato que diz ao loop "pode parar".
✓ Frase com done-state
- ✓"Todo teste em /tests passa ao rodar npm test."
- ✓"O endpoint /health responde 200 em curl."
- ✓"O build compila sem warnings."
✗ Frase sem fim
- ✗"Limpe isso aqui."
- ✗"Deixe o código melhor."
- ✗"Resolva os problemas."
💡 Teste da frase
Leia sua frase e pergunte: "um computador conseguiria decidir, sozinho, se isso está feito?" Se a resposta é não, sua frase ainda é uma opinião disfarçada. Reescreva até virar algo que um comando consiga verificar.
🔧 Decida as ferramentas e o que NÃO tocar
Defina o que o agente pode e — mais importante — o que ele não pode tocar. No primeiro run: permita editar /src e /tests e rodar os testes; nada de merge, deploy ou delete. O worker abre um PR; você dá o merge.
🧱 Os guardrails são o trabalho de verdade
Há uma frase que vale guardar: "os guardrails são o trabalho de verdade, não os agentes." Qualquer um liga um agente num loop em cinco minutos. O que separa um loop seguro de um desastre é o tempo que você gasta decidindo o que ele não pode fazer. Worker abre PR, humano dá merge — esse é o padrão seguro de partida.
✓ Permitido no 1º run
- ✓Editar /src e /tests
- ✓Rodar a suíte de testes
- ✓Abrir um PR com as mudanças
✗ Proibido no 1º run
- ✗Dar merge sozinho
- ✗Fazer deploy / publicar
- ✗Apagar arquivos ou testes
💾 Dê um lugar pro estado
Um loop que dura mais que uma volta precisa de memória externa. Peça ao agente para escrever o progresso em PROGRESS.md e dar um commit a cada mudança relevante. Assim, se ele perder o fio, retoma exatamente de onde parou — em vez de recomeçar do zero.
🔁 O harness da Anthropic, em 5 batidas
A pesquisa de agentes de longa duração da Anthropic descreve um ritmo simples que cada volta repete:
Ler o estado — abre o PROGRESS.md e relembra onde estava.
Progresso incremental — faz UMA mudança que avança.
Self-verify — confere o próprio trabalho (roda os testes).
Commit — grava a mudança com uma nota no PROGRESS.md.
Deixar limpo — fecha o ambiente para a próxima volta retomar.
🔄 Conecte o ciclo de 4 passos
Agora o coração: o ciclo que se repete a cada volta. Reunir contexto → fazer UMA mudança → verificar (rodar testes) → repetir. Uma mudança por volta não é preguiça — é deliberado. "Trabalhar em uma feature por vez" foi descrito como crítico para o loop convergir.
Leia o diagrama: a cada volta o agente relê o estado, faz uma única mudança e roda os testes. Se passou, para. Se não, volta para o começo — uma feature por vez, até convergir.
💡 Por que UMA mudança por volta
Quando você manda o agente consertar tudo de uma vez, ele se debate: muda dez coisas, dois testes quebram por motivos diferentes, e ele não sabe qual mudança causou o quê. Uma mudança por volta deixa o sinal limpo — cada teste que passa ou falha aponta para exatamente uma alteração.
🛑 Ponha um hard stop antes de rodar
Antes de apertar play, escreva o freio. Uma frase basta: "Pare quando todos os testes passarem, ou após 10 tentativas — o que vier primeiro." Isso é o hard stop, e ele nunca é opcional.
⚠️ O que acontece sem hard stop
Sem um freio, dois desastres esperam por você: "bizarre emergent behavior" — o loop entra em estados estranhos, tentando soluções cada vez mais malucas — e a conta de tokens, que sobe sem parar enquanto ele gira em falso. Um teto duro fecha as duas portas de uma vez.
🧩 A regra de ouro
Um loop tem duas condições de parada: a boa (o objetivo cumprido — testes passam) e a de segurança (o teto — máximo de tentativas). A primeira você espera; a segunda você impõe. Nunca confie que o modelo vai parar sozinho.
👀 Rode, observe, aperte o prompt
O passo final: assista o primeiro run ao vivo. E quando algo der errado, conserte as instruções — não a saída. Editar o resultado à mão é tapar o buraco; editar o prompt é consertar a fábrica.
🏺 "Clay on the pottery wheel"
Há uma metáfora ótima para isso: o loop é barro na roda do oleiro. Quando ele falha, você não conserta o vaso quebrado — você ajusta a pressão das mãos (o prompt, o guardrail, o critério) e joga o barro de volta na roda. Cada falha aponta um domínio do prompt para apertar.
Seu primeiro loop, completo. Junte os 7 passos num único prompt. Cole no Claude Code e observe:
# SEU PRIMEIRO LOOP — cole no Claude Code
# 1. Objetivo (a frase / done-state)
Objetivo: fazer todo teste em /tests passar ao rodar `npm test`.
# 2. Ferramentas e limites (permissões + guardrail)
Você pode editar </src> e </tests> e rodar os testes.
NÃO dê merge, deploy ou delete. Não apague testes para fazê-los passar.
Quando terminar, abra um PR com as mudanças — eu dou o merge.
# 3. Estado (PROGRESS.md + commit)
A cada mudança que melhora algo, escreva 1 linha em PROGRESS.md
e dê um commit com uma nota curta.
# 4. O ciclo de 4 passos (uma mudança por volta)
Repita: (1) leia o estado e rode `npm test`, (2) faça UMA correção
no arquivo mais responsável pela 1ª falha, (3) rode `npm test` de novo
para verificar, (4) se ainda falhar, volte ao passo 1.
# 5. Hard stop (max_turns em palavras)
Pare quando todos os testes passarem, ou após 10 tentativas —
o que vier primeiro.Como verificar: abra um projeto pequeno com 1 ou 2 testes quebrados, cole o prompt e não saia da frente. Você deve ver o agente rodar npm test, ler as falhas, fazer uma correção, rodar de novo, e anotar no PROGRESS.md — repetindo até passar ou bater 10 tentativas. Se ele tentar algo fora de /src e /tests, seu guardrail falhou: aperte a instrução e rode de novo.
Seu loop entrega um teste passando, mas a correção ficou feia. O que você faz?
🧾 Resumo do Módulo
Próximo:
3.2 — Loops para copiar e rodar