Ralph Loop: como evitar trabalho inacabado com Claude Code

O problema que ninguém te conta sobre agentes de código

Se você já usou o Claude Code para algo além de scripts triviais, conhece a frustração. Você descreve uma tarefa complexa — uma API REST com autenticação, validação, testes e documentação — e o Claude trabalha por alguns minutos, gera código, roda uns comandos e, com toda a confiança do mundo, declara: “Pronto! A implementação está completa.”

Você vai conferir. Os testes não passam. Faltam endpoints. Casos de borda foram ignorados. O build quebra.

Esse é o problema central do Claude Code: ele encerra a tarefa quando acredita que está finalizada, não quando ela realmente está. Para scripts simples, isso funciona bem. Mas à medida que a complexidade cresce — tarefas com múltiplas dependências, integrações entre módulos, regras de negócio elaboradas — a distância entre “acho que terminei” e “está de fato pronto” aumenta dramaticamente.

O motivo é estrutural. O Claude opera dentro de uma janela de contexto finita. Em tarefas longas, o início da conversa vai sendo comprimido ou descartado — um fenômeno chamado de compaction ou context rot. O modelo literalmente perde a noção do que já fez, do que falta fazer e de quais erros já cometeu. É como pedir a alguém que monte um quebra-cabeça de mil peças, mas apagando a memória a cada cinquenta peças encaixadas.

O resultado é previsível: trabalho inacabado entregue com aparência de completo.

Ralph Loop: a solução que ninguém esperava

Existe uma técnica que resolve esse problema de forma surpreendentemente direta. Ela se chama Ralph Loop, foi criada por Jeffrey Huntley, e o nome é uma homenagem ao personagem Ralph Wiggum de Os Simpsons — aquele garoto que persiste em qualquer tarefa com uma ingenuidade inabalável, sem perceber que está falhando, até que eventualmente tropeça numa solução.

A analogia é precisa. O Ralph Loop força o Claude a continuar tentando, rodada após rodada, até que o trabalho esteja genuinamente concluído. Não é um framework sofisticado. Não é um sistema de orquestração de IA com grafos de dependências e agentes coordenados. É, na essência, um laço while em bash.

A genialidade está no que acontece dentro desse laço.

O fracasso como motor, não como exceção

A premissa fundamental do Ralph Loop é tratar o fracasso como parte do fluxo de trabalho, e não como exceção. Em vez de esperar que o Claude acerte tudo de primeira — expectativa que falha sistematicamente em tarefas complexas — a técnica assume que ele vai errar e projeta um sistema onde cada erro alimenta a próxima tentativa.

A cada nova iteração, o Claude relê o que aconteceu nos ciclos anteriores: o que funcionou, o que quebrou, quais testes falharam, quais arquivos foram modificados. Ele não começa do zero — ele aprende com o histórico. O resultado é um processo de aprimoramento progressivo onde cada rodada gera código um pouco melhor, um pouco mais completo, um pouco mais robusto.

Esse mecanismo transforma o esperado fracasso do Claude em vantagem. Em vez de uma única tentativa que entrega 60% do trabalho, você obtém uma sequência de iterações que converge para 90%, 95% ou mais.

Arquitetura central: como o Ralph Loop funciona

A mecânica é simples de entender. O ciclo começa com dois elementos: um prompt descrevendo a tarefa e um termo de conclusão — normalmente a palavra DONE, formatada de maneira específica. O laço bash executa o Claude com esse prompt e inspeciona a saída. Se o termo de conclusão aparecer corretamente, o ciclo para. Se não aparecer, o processo reinicia.

Mas o reinício não é cego. Antes de cada nova iteração, o Ralph Loop relê três arquivos de estado que funcionam como a memória do sistema:

prd.json é a lista de tarefas com flags booleanas — true ou false — indicando o que já foi concluído e o que ainda falta. É o mapa objetivo do trabalho. O Claude consulta esse arquivo no início de cada rodada para saber exatamente onde focar seus esforços.

progress.txt funciona como memória de curto prazo. A cada ciclo, o Claude registra nesse arquivo o que aprendeu: quais erros encontrou, quais abordagens funcionaram, quais caminhos levaram a becos sem saída. Na próxima iteração, ele lê essas anotações antes de agir, evitando repetir os mesmos erros.

agents.md é a memória de longo prazo. Contém padrões, convenções e conhecimentos relevantes organizados por pasta do projeto. Se o Claude descobriu que determinada biblioteca tem uma peculiaridade de configuração, ou que o projeto segue um padrão arquitetural específico, essa informação fica registrada aqui e sobrevive a todas as iterações futuras.

Juntos, esses três arquivos resolvem o problema da compaction. Mesmo que o contexto da conversa se degrade ao longo de dezenas de iterações, o conhecimento acumulado permanece acessível em disco. O Claude reconstrói seu entendimento a cada ciclo, como se folheasse um caderno de anotações antes de retomar o trabalho.

O stop hook: interceptando a saída prematura

Um componente crucial do Ralph Loop é o stop hook do plugin Anthropic. Ele resolve um problema específico: o Claude tem uma tendência natural de tentar encerrar a execução quando acha que terminou, mesmo que o critério objetivo de conclusão não tenha sido atingido.

O stop hook intercepta essas tentativas de saída. Quando o Claude tenta finalizar sem retornar o termo de conclusão no formato esperado, o hook bloqueia a saída e reinicia o processo, forçando-o a reler os arquivos de estado e continuar trabalhando. É como um supervisor que não deixa o funcionário ir embora até que o checklist esteja completo.

Esse mecanismo é o que dá ao Ralph Loop sua característica definidora: persistência. O Claude pode achar que terminou quantas vezes quiser — o ciclo só para quando o critério objetivo, verificável e binário for satisfeito.

Critérios binários: a alma do sistema

Nada no Ralph Loop funciona se os critérios de conclusão forem vagos. A técnica depende fundamentalmente de prompts com critérios objetivos e binários — condições que são inequivocamente verdadeiras ou falsas.

Bons critérios incluem coisas como: cobertura de testes acima de 80%, todos os endpoints listados no PRD retornando status 200 para inputs válidos, o build completando sem erros, todos os testes unitários passando, e migrações de banco de dados executando sem falhas.

Critérios ruins são aqueles que dependem de julgamento subjetivo: “a interface está bonita”, “o código está limpo”, “a experiência do usuário está boa”, “a documentação é abrangente”.

O Claude não consegue avaliar objetivamente se uma UI está “bonita”. Mas ele consegue verificar se npm run test retorna exit code 0. Essa diferença é tudo. Cada item no prd.json deve ser algo que o Claude pode confirmar ou negar com um comando, um teste ou uma verificação automatizada.

Tarefas pequenas e verificáveis

Tão importante quanto definir bons critérios é dividir o trabalho em pedaços pequenos. Cada tarefa no PRD deve idealmente demandar uma única iteração do Ralph Loop para ser concluída. Se uma tarefa exige múltiplas iterações só para si mesma, ela é grande demais e precisa ser quebrada.

Na prática, isso significa que uma feature como “implementar autenticação JWT” não deveria ser uma tarefa única, mas sim cinco ou seis: criar o middleware de verificação de token, implementar o endpoint de login, implementar o endpoint de refresh, adicionar testes para tokens válidos, adicionar testes para tokens expirados, adicionar testes para tokens malformados.

Essa granularidade serve a dois propósitos. Primeiro, permite que o Claude tenha sucesso mais frequente, o que mantém o ciclo produtivo. Segundo, facilita a identificação de onde exatamente o processo travou quando algo dá errado.

Documentar cada ciclo é igualmente vital. Os arquivos de memória — progress.txt e agents.md — não se preenchem sozinhos de forma mágica. O prompt do Ralph Loop deve instruir o Claude a registrar aprendizados, erros encontrados e decisões tomadas ao final de cada iteração. Esse registro é o que permite o aprendizado incremental que diferencia o Ralph Loop de uma simples repetição mecânica.

Feedback loops automáticos: a autoverificação

O Ralph Loop só funciona se o Claude puder verificar seu próprio trabalho. Sem feedback automatizado, ele fica no escuro — sem saber se o que fez está correto ou não. Os feedback loops automáticos são o que permitem essa autoverificação.

Na prática, isso significa que a cada rodada do ciclo, o Claude deve executar testes, rodar builds, fazer verificações de lint e qualquer outra validação automatizada disponível no projeto. Os resultados dessas execuções alimentam a próxima iteração: se um teste falhou, o Claude sabe exatamente o que precisa corrigir.

Para projetos de backend, testes unitários e de integração geralmente bastam. Para frontend, a situação exige mais: automação de browser com ferramentas como Playwright ou Cypress se torna essencial. O Claude precisa conseguir abrir a aplicação, interagir com elementos, verificar estados visuais e capturar erros — tudo de forma automatizada, sem intervenção humana.

Sem esses loops de feedback, o Ralph Loop degenera: o Claude continua iterando, mas sem saber se está avançando ou andando em círculos.

Os três níveis de uso: da chave de fenda à britadeira

A técnica não foi projetada para ser usada em modo autônomo desde o primeiro dia. Jeffrey Huntley define três níveis progressivos, usando uma analogia de ferramentas, e a progressão entre eles é obrigatória — pular níveis é receita para frustração e desperdício.

Nível 1 — Screwdriver (chave de fenda)

No primeiro nível, você monitora cada iteração manualmente. É o modo de aprendizado.

Execute o Ralph Loop e observe cada ciclo do início ao fim. Leia o que o Claude está escrevendo nos arquivos de estado após cada rodada. Compare o que ele marcou como concluído no prd.json com o que realmente está funcionando. Preste atenção em como ele interpreta seus critérios de sucesso — muitas vezes a interpretação não é a que você esperava.

Observe quais tipos de tarefa o Claude acerta de primeira e quais exigem múltiplas iterações. Verifique se os critérios no PRD são claros o suficiente ou se geram ambiguidade. Confirme se os feedback loops estão funcionando — os testes estão sendo executados? Os resultados estão sendo lidos corretamente?

Avance para o próximo nível quando conseguir prever o comportamento do Claude com razoável acurácia — quando olhar para uma tarefa no PRD e souber de antemão se ele vai acertar de primeira ou precisar de três tentativas.

Nível 2 — Power Drill (furadeira elétrica)

No segundo nível, você deixa o Ralph Loop rodar múltiplas iterações e confere periodicamente.

Inicie o ciclo e vá fazer outra coisa — revisar código, responder emails, trabalhar em outra tarefa. Volte a cada 20 ou 30 minutos para conferir o progresso. Revise os arquivos progress.txt e prd.json para entender onde o Claude está. Se notar que ele ficou preso em loop num problema específico, intervenha manualmente ajustando o PRD ou adicionando uma nota no agents.md.

Observe se o Claude está convergindo — cada iteração deveria mostrar progresso mensurável. Fique atento a loops improdutivos, onde ele repete os mesmos erros. Monitore se a qualidade do progress.txt está se degradando, com anotações genéricas em vez de específicas.

Avance para o próximo nível quando suas verificações periódicas consistentemente revelarem progresso real, com poucas intervenções manuais necessárias.

Nível 3 — Jackhammer (britadeira)

No terceiro nível, você configura o Ralph Loop para rodar de forma autônoma durante a noite.

Prepare um PRD detalhado com critérios objetivos para todas as tarefas. Garanta que todos os feedback loops estejam funcionando: testes, builds, linters, automação de browser se necessário. Configure notificações para acompanhar o andamento. Inicie a execução antes de dormir.

Pela manhã, revise tudo: leia o progress.txt de trás para frente, confira o prd.json, rode os testes você mesmo, inspecione o código gerado. Em bons ciclos, o Ralph Loop atinge entre 80% e 95% de conclusão automatizada. Os 5% a 20% restantes invariavelmente exigem julgamento humano: decisões de design, ajustes de UX, casos extremos que não foram antecipados no PRD.

A revisão manual pela manhã não é opcional — é parte do processo. O Ralph Loop é uma ferramenta de aceleração, não de substituição.

Para acompanhar execuções longas, configure webhooks para enviar atualizações por WhatsApp (via Twilio ou serviço similar) ou Slack. A cada N iterações, ou quando uma tarefa do PRD for marcada como concluída, envie uma notificação. Configure também alertas para quando o ciclo ficar preso — se três iterações consecutivas não mudarem nenhum flag no prd.json, algo precisa de atenção.

Quatro padrões de uso

O Ralph Loop se aplica a cenários recorrentes no desenvolvimento de software. Estes são os quatro padrões mais comuns.

Padrão 1 — Construção incremental de feature

Você tem um PRD descrevendo uma feature nova — digamos, uma API REST completa para gerenciamento de usuários. O PRD é dividido em 15 a 20 tarefas granulares: criar modelo de dados, implementar endpoint de criação, implementar endpoint de listagem com paginação, adicionar validação de entrada, implementar autenticação, escrever testes para cada endpoint, documentar a API.

O Ralph Loop consome esse PRD e trabalha tarefa por tarefa, marcando cada uma no prd.json conforme conclui. A expectativa é que o ciclo leve de 2 a 4 horas ininterruptas para uma API de complexidade média. Ao final, você terá uma implementação funcional que cobre a grande maioria dos requisitos, faltando apenas ajustes finos que exigem decisão humana.

Padrão 2 — Geração de testes para atingir metas de cobertura

Seu projeto tem 45% de cobertura de testes e precisa chegar a 80%. O PRD lista cada módulo que precisa de testes, com o percentual atual e o alvo. O critério de sucesso é objetivo: a cobertura medida pelo relatório de coverage atingir o número definido.

Esse é um dos cenários onde o Ralph Loop mais brilha, porque o feedback loop é naturalmente perfeito — o comando de cobertura retorna um número que pode ser comparado diretamente com a meta. O Claude gera testes, roda a cobertura, vê que está em 62%, gera mais testes, roda novamente, vê que está em 74%, e assim por diante até atingir o alvo.

Padrão 3 — Revisão multi-persona

Neste padrão, cada iteração do Ralph Loop simula uma persona diferente do time de desenvolvimento. A primeira rodada assume o papel de um especialista em segurança, revisando o código em busca de vulnerabilidades, injections e exposição de dados sensíveis. A segunda assume o papel de QA, testando fluxos completos, edge cases e comportamento com inputs inválidos. A terceira faz revisão de código, avaliando legibilidade, padrões, desempenho e manutenibilidade.

O PRD para esse padrão lista os critérios de cada persona separadamente. A cada iteração, o Claude adota uma perspectiva diferente e verifica se os critérios daquela persona foram atendidos. O resultado é uma revisão multidimensional que simula o trabalho de uma equipe inteira.

Padrão 4 — Validação rápida de prova de conceito

Às vezes você não precisa de código perfeito — precisa saber se uma ideia funciona. Uma nova arquitetura, uma stack diferente, uma abordagem não convencional para um problema. O Ralph Loop pode ser usado com um padrão de qualidade deliberadamente mais baixo: sem exigência de cobertura de testes alta, sem revisão de segurança, apenas funcionalidade básica.

Nesse modo, o PRD é enxuto — 5 a 10 tarefas focadas em provar que o conceito é viável. O ciclo normalmente se resolve em 5 a 10 iterações, gerando um protótipo funcional que você pode avaliar e decidir se vale investir tempo em uma implementação completa.

Simplicidade técnica, poder na execução

O Ralph Loop é, no fundo, um while true com leitura de arquivos. Não há mágica algorítmica, não há modelos treinados especificamente para orquestração, não há infraestrutura complexa. Qualquer desenvolvedor que saiba escrever um script bash consegue implementá-lo em uma tarde.

Mas a simplicidade técnica mascara a disciplina que a técnica exige para funcionar bem. Sem uma arquitetura correta — os arquivos de estado, os feedback loops, o stop hook — o laço vira apenas repetição sem aprendizado. Sem critérios claros e binários, o Claude não sabe quando parar e quando continuar. Sem memória persistente nos arquivos de progresso e agentes, o context rot consome toda a eficácia do processo. E sem progressão consciente entre os três níveis de operação, você vai automatizar a geração de lixo em escala.

O componente mais importante de todo o sistema não é técnico: é o julgamento humano. O Ralph Loop automatiza a execução, mas o planejamento — a decomposição do trabalho, a definição dos critérios, a estruturação do PRD — continua sendo responsabilidade do desenvolvedor. Da mesma forma, a revisão final do que o loop produziu exige olhos humanos. A técnica não elimina o trabalho humano; ela muda radicalmente onde esse trabalho é investido: do teclado para o planejamento e a revisão.

Quando entendido e aplicado com disciplina, o Ralph Loop transforma o Claude Code de uma ferramenta que entrega 60% do trabalho numa que entrega 90% ou mais — com a consciência de que os últimos 10% sempre serão seus.