A Técnica Ralph Wiggum

Atualização (jan 2025): A Anthropic lançou gestão nativa de tarefas com dependências, bloqueadores e coordenação entre sessões através de CLAUDE_CODE_TASK_LIST_ID. Muitas das soluções de contorno do Ralph já estão integradas no produto. Os princípios principais abaixo ainda se aplicam. O novo sistema apenas trata da ligação nativa.

Passa uma lista de tarefas para um agente. Ele pega numa, escreve o código, corre os testes, faz commit. Depois pega na seguinte. E na seguinte. Tudo isso corre enquanto dormes.

Isso é Ralph Wiggum. Sem relação com o miúdo dos Simpsons. É o loop de programação autónomo que está a transformar silenciosamente a forma como os engenheiros entregam software.

O que torna Ralph diferente

A maioria das pessoas usa o Claude Code como uma app de chat. Prompt. Espera. Lê. Prompt outra vez. Ótimo para trabalhos rápidos. Para entregar funcionalidades reais, você torna-se a parte lenta.

Ralph inverte isso. Em vez de controlar cada passo, constróis um loop que mantém o Claude a trabalhar até o trabalho estar feito. O truque está nos stop hooks do Claude Code: eles disparam no momento em que o agente tenta parar, o que significa que podes intercetar essa tentativa e empurrar o agente de volta ao trabalho.

Aqui está o padrão central:

1. Claude trabalha numa tarefa
2. Claude tenta parar (produz conclusão)
3. Um stop hook interceta e verifica: o trabalho está realmente feito?
4. Se não, passa o prompt de volta e continua
5. Se sim, deixa concluir

O passo 4 é tudo. O teu agente não desiste na primeira vez que acha que terminou. Desiste quando o trabalho foi verificado.

A Promessa de Conclusão

Ralph baseia-se numa "promessa de conclusão". Uma palavra ou frase específica que significa realmente terminado. Quando o Claude está convicto de que a tarefa está concluída, emite essa promessa (normalmente só a palavra "complete").

// In your Ralph loop configuration
completion_promise: "complete"
max_iterations: 25

Cada vez que o Claude tenta parar, o hook procura essa promessa. Falta? O loop continua. Presente? O loop termina. Saídas prematuras são bloqueadas, e as saídas reais passam de forma limpa.

Regra crítica: Sem promessa, sem paragem. Isso força o agente a continuar até genuinamente achar que o trabalho está feito.

Verificação: O Núcleo Inegociável

Boris Cherny, que criou o Claude Code, tem uma regra que recusa quebrar: dá sempre ao Claude uma forma de verificar o seu trabalho.

Essa regra é o motivo pelo qual Ralph funciona. Salta a verificação e acabas com um loop que corre para sempre ou para demasiado cedo. Adiciona-a e o loop sabe quando está realmente terminado.

Três abordagens de verificação combinam bem com Ralph:

1. Verificação Orientada por Testes

Escreve os testes primeiro. Claude corre-os, vê-os falhar, escreve código, corre-os outra vez. O loop mantém-se a repetir até tudo estar verde.

Workflow:
1. Run all tests in /tests/feature-x/
2. If tests fail, implement code to make them pass
3. Run tests again
4. Repeat until all tests pass
5. Output "complete" only when test suite is green

Este é o caminho mais fiável. Os testes não mentem. Passa ou falha. Nada ambíguo.

2. Verificação por Agente em Segundo Plano

Lança um segundo agente cujo único trabalho é verificar o trabalho do agente principal. Boris usa isto para corridas longas:

After completing work, use a background agent to:
1. Review all changed files
2. Run the full test suite
3. Check for regressions
4. Report any issues found

Obténs uma verificação independente. Se o agente em segundo plano encontrar problemas, o loop principal volta imediatamente ao trabalho.

3. Validação no Stop Hook

O próprio stop hook pode correr validação. Verifica um ficheiro de progresso, corre o linter, verifica o build. A validação falha? Bloqueia a paragem e envia o agente de volta.

// Stop hook pseudocode
if (agent_trying_to_stop) {
  validation_result = run_tests();
  if (validation_result.failed) {
    return { decision: "block", reason: "Tests failing, continue work" };
  }
  return { decision: "allow" };
}

O Fluxo de Trabalho em Duas Fases

O primeiro erro que a maioria das pessoas comete: planeiam e implementam na mesma janela de contexto.

Separa-as.

Fase 1: Sessão de Planeamento

• Gera especificações através de conversa
• Revê e edita manualmente
• Cria um plano de implementação com referências explícitas a ficheiros
• Mantém a especificação como uma "ancora" que previne invenção

Fase 2: Sessão de Implementação

• Contexto limpo (limpa a conversa anterior)
• Alimenta apenas o documento do plano
• Corre o loop Ralph
• Deixa o agente iterar até estar completo

Porquê a separação? Porque a degradação da janela de contexto é real. Depois de suficiente vai e vem, o Claude começa a basear-se em mensagens antigas anteriores. Um início limpo com apenas o plano mantém o foco apertado.

O teu plano torna-se a âncora. Cada iteração do loop olha para ele. É isso que impede o agente de se desviar para algo que não pediste.

Implementação Prática: A Abordagem PRD

A versão de Ryan Carson parece assim:

1. Começa com um PRD (Documento de Requisitos do Produto)

• O que estamos a construir?
• O que está no âmbito?
• O que está explicitamente fora do âmbito?

2. Converte em histórias de utilizador com critérios de aceitação

• Cada história é uma unidade pequena e testável
• Os critérios de aceitação definem "feito"

3. Estrutura para consumo pelo agente

• Formato JSON ou markdown
• Caixas de verificação claras para seguir o progresso
• Links para localizações relevantes do código

4. Corre o loop

• O agente pega na próxima história por completar
• Implementa-a
• Corre a verificação (testes)
• Marca-a como completa
• Passa para a seguinte

O benefício: simplesmente vais embora. Acordas com funcionalidades terminadas, testes verdes e commits já no log.

Verificação de UI: A Armadilha Escondida

Um problema que apanha toda a gente mais cedo ou mais tarde: os testes ficam verdes, mas a UI parece errada.

Aqui está o porquê. Ralph pode felizmente confirmar que o código corre enquanto permanece completamente cego a bugs visuais. O componente renderiza, os testes passam, e o botão ainda está fora do ecrã ou o texto está cortado a meio.

Corrige-o com um protocolo de verificação baseado em capturas de ecrã.

After implementing UI changes:
1. Take screenshots of affected components
2. Rename each with "verified_" prefix after review
3. Do NOT output completion promise yet
4. Let the next iteration confirm all files are verified
5. Only then output "complete"

Isso força pelo menos duas passagens do loop para qualquer alteração de UI. A passagem um implementa e captura capturas de ecrã. A passagem dois confirma que cada captura de ecrã foi revista. A verificação visual não pode ser ignorada.

A perceção chave: Instrui o Claude que renomear as capturas de ecrã NÃO ganha a promessa de conclusão. A próxima iteração é o que sinaliza que está feito. Isso bloqueia as saídas prematuras.

Economia: Por que Isso Muda Tudo

Um agente de programação a correr sem parar no Sonnet custa aproximadamente $10,42 USD por hora (medido ao longo de uma taxa de consumo de 24 horas).

Menos que o salário mínimo na maioria dos lugares. E estás a pagar por uma máquina que pode:

• Limpar pendências durante a noite
• Correr múltiplas funcionalidades em paralelo
• Nunca ficar cansada ou distraída
• Escalar com mais computação

Portanto o gargalo muda. Deixa de ser "quanto estou disposto a gastar?" e torna-se "quanto trabalho fiável consigo definir?"

Equipas a correr loops fiáveis vão ficar muito à frente de equipas que não estão. A diferença já está a crescer.

Falhas Comuns e Correções

O Loop Nunca Termina

Causa: Tarefa impossível ou critérios de conclusão em falta Correção: Define um número máximo de iterações (ex.: 25). Adiciona critérios de conclusão explícitos ao teu prompt.

O Loop Termina Muito Cedo

Causa: Claude produz a promessa antes do trabalho estar feito Correção: Fortalece a tua verificação. Adiciona testes. Usa o protocolo de capturas de ecrã para UI. Torna "feito" objetivamente mensurável.

A Qualidade Degrada ao Longo das Iterações

Causa: Janela de contexto a encher com tentativas falhadas Correção: Implementa estado de checkpoint. Marca o trabalho completo num ficheiro externo. Deixa o loop retomar de forma limpa se o contexto encher.

O Agente Inventa Funcionalidades

Causa: A especificação é vaga ou está em falta Correção: A tua especificação é a "ancora" que previne a invenção. Torna-a específica. Inclui referências explícitas ao código existente. Diz ao Claude o que NÃO deve fazer.

A Configurar o Teu Primeiro Loop Ralph

Mantém-no pequeno na primeira execução. Escolhe uma funcionalidade que conheces bem, com testes que já existem.

1. Instala o plugin Ralph (ou implementa tu mesmo o padrão de stop hook)

2. Cria o teu ficheiro de prompt:

Study the implementation plan in /docs/plan.md
Pick the single most important incomplete task
Implement it following existing patterns
Run tests with: npm test
On pass: mark task complete in plan.md, commit changes
On fail: fix the issue and run tests again
Output "complete" only when all tasks are done and tests pass

1. Define restrições:

• Iterações máximas: 25
• Promessa de conclusão: "complete"
• Gates de qualidade: os testes devem passar, o linting deve passar

2. Observa a primeira execução. Não saias ainda. Cancela se o comportamento parecer errado. Ajusta o teu prompt. Corre de novo.

3. Aumenta gradualmente a autonomia à medida que a confiança cresce.

A Filosofia Ralph

Ralph não é sobre tirar os humanos da programação. É sobre tirar os humanos do loop tedioso entre tentativas.

O design ainda é teu. As especificações ainda são tuas. Defines o que "feito" significa. Revisas o resultado final.

O que Ralph toma é a maratona de debug das 2 da manhã. O interminável ciclo de testar-corrigir-testar. A troca entre funcionalidades. Isso é o que ele trata.

Boris continua a voltar à mesma linha: a verificação impulsiona tudo. Dá ao Claude uma forma de verificar o seu próprio trabalho, e vai correr de forma fiável durante horas. Tira isso e estás a arriscar.

Começa com a verificação. Envolve os teus loops à volta dela. O futuro da programação autónoma não são prompts mais inteligentes. São melhores sistemas de feedback.

Próximos Passos

• Tenta a gestão nativa de tarefas para persistência integrada e coordenação entre sessões
• Aprende sobre hooks para implementar comportamentos de paragem personalizados
• Explora fluxos de trabalho assíncronos para correr múltiplos loops
• Lê sobre engenharia baseada em threads para escalar os teus fluxos de trabalho autónomos
• Verifica loops de feedback para padrões de verificação

Pessoas que ficam boas no Ralph não são apenas utilizadores de Claude Code. Estão a construir sistemas que entregam código enquanto dormem.