Engenharia de loops: loops, rotinas e fluxos de trabalho do Claude Code

TL;DR: Engenharia de loops é a disciplina de fazer agentes repetirem ciclos de trabalho até que uma condição de parada seja atendida — em vez de instruí-los uma interação por vez. Boris Cherny, da Anthropic e criador do Claude Code, descreve o próprio fluxo de trabalho sem rodeios: “Eu não dou mais prompts ao Claude. Tenho loops em execução. São eles que dão prompts ao Claude e decidem o que fazer. Meu trabalho é escrever loops.”¹ O Claude Code agora oferece uma hierarquia completa de recursos para loops: /goal (repete até que um modelo separado confirme uma condição ou a julgue impossível), /loop (execuções locais recorrentes), o plugin oficial Ralph (itera até que uma promessa seja cumprida), tarefas agendadas na nuvem (antes chamadas de rotinas; cron na nuvem) e workflows dinâmicos (o Claude escreve um grafo de orquestração JavaScript e executa até 1.000 subagents com base nele). Nenhum desses recursos é o que sustenta todo o sistema: esse papel cabe à verificação. Um loop só converge quando algo fora do gerador — um teste, um modelo avaliador, uma comparação de pixels, uma verificação automatizada — determina que o trabalho está “concluído”. Faça isso direito e os ganhos dos loops se acumulam; faça errado e você terá uma caminhada aleatória caríssima. Este guia aborda todos os recursos para loops com referências de versão, o padrão Ralph e seus modos de falha, quando loops precisam se transformar em grafos, a hierarquia de verificação, a disciplina de custos e segurança e como manter uma frota permanente em operação. Atualizado para o Claude Code v2.1.312 (outubro de 2026).

O que é loop engineering?

Há dois anos, engenheiros escreviam código-fonte à mão. Depois, agentes passaram a escrever o código a partir de prompts humanos. A mudança em curso agora acontece um nível acima: agentes criam prompts para outros agentes, e o humano escreve o sistema que decide quais prompts serão enviados. Cherny avalia diretamente o tamanho dessa transformação: “Assim como a passagem do código-fonte para os agentes foi enorme, os loops são igualmente importantes e representam uma mudança tão grande quanto.”²

Sua definição é surpreendentemente simples: “Um loop é essencialmente um cron job executado localmente pelo Claude. Uma routine é a mesma coisa, mas executada na nuvem.”³ Essa prática aparentemente exótica — “centenas, às vezes milhares de agentes trabalhando por 5, 10 ou 20 horas” durante a noite,⁴ Claude Code “100% escrito pelo Claude Code há mais de seis meses”⁴ — resume-se a um pequeno conjunto de elementos básicos: um prompt disparado novamente conforme um cronograma ou uma condição, um estado que persiste entre as iterações e uma verificação que encerra a execução.

Anthropic deu nome à disciplina em junho de 2026: loops são “agentes que repetem ciclos de trabalho até que uma condição de parada seja atendida”, e “a qualidade do resultado de um loop depende do sistema ao redor dele”.⁵ Este guia trata justamente desse sistema.

Uma observação sobre a origem dos termos, porque a discussão avançou rapidamente em meados de 2026: o termo “graph engineering” — muitas vezes atribuído a Cherny em publicações virais — foi cunhado pela comunidade (na publicação de Peter Steinberger de 18 de julho, “ainda estamos falando de loops ou já migramos para graphs?”, amplificada por Hamel Husain), não pelo Anthropic nem por Cherny.⁶ A citação amplamente compartilhada “85% dos nossos engenheiros… a maneira de fazer isso é graph engineering” circula apenas em publicações de terceiros; ao preparar este guia, não conseguimos localizá-la em nenhum registro primário de suas palestras (a conversa na YC Startup School, o Odd Lots da Bloomberg e a reportagem da TechCrunch sobre o Meta @Scale), portanto, trate essa atribuição como não verificada. Sua prática real tem o formato de um graph (orquestradores que iniciam subagents implementadores, verificadores e corretores, aninhados até a profundidade 5), mas o vocabulário verificado é loops, routines e workflows — e é esse o vocabulário usado neste guia.

Caminho ideal em cinco minutos

Três comandos levam você dos prompts aos loops:

# 1. A goal loop: Claude keeps working until a SEPARATE model confirms the condition
/goal all tests pass and coverage is above 80%

# 2. A recurring local loop: re-runs on a schedule while your session is open
/loop 30m check CI on my open PRs and fix any failures

# 3. A cloud scheduled task (formerly a routine): runs on Anthropic's infrastructure whether your laptop is open or not
/schedule every morning at 7am: triage new issues, reproduce what you can, draft fixes as PRs

A diferença entre eles e um prompt é estrutural, não cosmética: cada um tem uma regra de novo disparo (uma condição, um relógio ou um cron) e precisa de uma regra de parada. Todo o restante deste guia explica como tornar essas duas regras confiáveis.

O loop central e a regra fundamental

Todo sistema de agentes executa o mesmo ciclo interno, que a documentação do Agent SDK do Anthropic consagra como coletar contexto → agir → verificar o trabalho → repetir.⁷ O próprio processo do Claude Code é um loop: avaliar o prompt, chamar ferramentas, ler os resultados e repetir até que uma resposta não tenha chamadas de ferramentas.⁸

Loop engineering envolve esse ciclo interno com loops externos — e herda sua única regra inegociável, reafirmada por todas as fontes sérias da área:

O agente que realiza o trabalho nunca o avalia.

• Documentação do /goal do Anthropic: “a conclusão é decidida por um modelo novo, não pelo modelo que realiza o trabalho”.⁹
• Ensaio do Anthropic sobre design de harness: “Separar o agente que realiza o trabalho daquele que o avalia é uma ferramenta poderosa para lidar com esse problema.”¹⁰
• Cherny, sobre o que os profissionais deixam passar: “A verificação provavelmente é o aspecto mais importante que as pessoas não fazem direito.”³ Em seu exemplo prático, ao instruir uma migração de Electron para Swift em duas semanas: “execute o aplicativo Electron na máquina virtual Mac, faça uma captura de tela e examine-a pixel por pixel. Compare-a com a versão em Swift. Não pare até terminar.”³

A razão é mecânica, não moral: um modelo ao qual se pergunta “você terminou?” apresenta um viés positivo de autoavaliação, e uma transcrição confiante pode convencer uma condição de saída avaliada por modelo a declarar “concluído” antes da hora.¹¹ A verificação externa — uma suíte de testes, um compilador, uma comparação de pixels ou um modelo novo sem interesse na resposta — é o único sinal que resiste a isso.

A escada da autonomia

As superfícies de loop no Claude Code formam uma escada que vai de “pressione Enter novamente” a “é executado sem você”. Cada degrau troca mais autonomia por uma carga maior de verificação:

(A estrutura em degraus segue a taxonomia de julho de 2026 do pardel.dev, o mapa independente mais claro desse espaço.¹¹)

Uma opção local fica entre os degraus 3 e 5: as tarefas agendadas do Desktop rodam na sua máquina sem uma sessão aberta, em intervalos a partir de 1 minuto quando o Claude as define (1 hora nos formulários), e a documentação as indica “quando você precisa de acesso a arquivos e ferramentas locais”.¹²

A disciplina dessa escada: comece no degrau mais baixo que resolva seu problema e só avance quando a verificação desse degrau estiver comprovada. Um /goal cuja condição não possa ser expressa como algo verificável ainda não está pronto para se tornar uma tarefa agendada na nuvem.

As superfícies de loop em detalhes

(Este guia aborda as próprias superfícies de loop. O guia do Claude Code é a referência completa do CLI — configurações, permissões, hooks, MCP — e o guia de arquitetura de agentes explica como os componentes do harness se combinam; os loops são executados sobre ambos.)

/goal — o loop avaliador-otimizador

/goal <condition> mantém o Claude trabalhando até que a condição seja atendida: “Após cada turno, um modelo verifica se a condição foi atendida. Se o modelo julgar que ela ainda não foi atendida, o Claude inicia outro turno em vez de devolver o controle a você.”⁹ Nos bastidores, “/goal é um wrapper em torno de um Stop hook baseado em prompt e restrito à sessão”, por isso ele fica indisponível sempre que os hooks estão desativados (disableAllHooks, ou allowManagedHooksOnly nas configurações gerenciadas). O avaliador é o modelo pequeno e rápido que você configurou, e ele retorna um de três veredictos, cada um com um breve motivo:⁹

Ele também funciona em modo headless: claude -p "/goal ..." executa o loop até a conclusão.

Notas de elaboração: torne a condição observável (“os testes passam”, “o endpoint retorna 200”, “zero erros de TypeScript”), não aspiracional (“o código está limpo”). Um verificador vago não oferece direção ao loop — e uma transcrição confiante pode persuadir uma condição avaliada por modelo a concordar, portanto, combine /goal com uma verificação automatizada sempre que houver uma disponível.¹¹ A documentação declara o limite abertamente: o avaliador “não executa comandos nem lê arquivos de forma independente, então escreva a condição como algo que a própria saída do Claude consiga demonstrar”.⁹ Coloque também a regra de parada dentro da condição: uma cláusula como or stop after 20 turns é avaliada como o restante dela, e uma condição pode ter até 4.000 caracteres. Se o Claude continuar respondendo ao avaliador sem usar ferramentas por vários turnos seguidos, o Claude Code interrompe o loop e devolve o controle a você com o goal ainda definido.⁹

O tratamento de falhas, reforçado pela primeira vez na v2.1.234,³⁴ agora cobre todas as formas pelas quais um turno pode falhar:

Quando um host, como o aplicativo desktop ou uma sessão na nuvem, gerencia as credenciais, uma falha de autenticação mantém o goal ativo, porque o próprio host restaura o acesso. E quando um trabalho em segundo plano mantém um goal aguardando, o Claude verifica o andamento após 30 minutos, de novo 1 hora depois e, a partir daí, a cada 2 horas, iniciando no máximo três verificações ociosas entre os seus prompts (CLAUDE_CODE_GOAL_CHECKIN_MINUTES define o primeiro intervalo; 0 desativa as verificações e as novas tentativas automáticas).⁹

/loop — execuções locais recorrentes

/loop [interval] <prompt> executa novamente um prompt conforme um cronograma: fixo (/loop 5m check the deploy), em ritmo próprio (o Claude escolhe o próximo intervalo, entre um minuto e uma hora, com base no que observou) ou apenas /loop para uma rotina de manutenção integrada. Nos bastidores estão CronCreate/CronList/CronDelete (cron de 5 campos, 50 tarefas por sessão e expiração em 7 dias) e a ferramenta Monitor, que transmite a saída de um script em segundo plano em vez de fazer polling.¹² O próprio exemplo de lançamento de Cherny: “/loop cuide de todos os meus PRs. Corrija automaticamente os problemas de build e, quando surgirem comentários, use um agente em uma worktree para resolvê-los.”¹³ Para substituir o prompt de manutenção integrado, escreva um loop.md (.claude/loop.md no projeto, que tem precedência, ou ~/.claude/loop.md); “Edições em loop.md entram em vigor na próxima iteração”, e o conteúdo além de 25.000 bytes é truncado.¹²

A limitação relevante: /loop existe dentro de um processo do Claude Code em execução. “As tarefas só disparam enquanto o Claude Code está em execução e ocioso.” Saia e elas deixam de disparar; coloque a sessão em segundo plano e o loop continua rodando sem um terminal; retome com --resume ou --continue e as tarefas agendadas com CronCreate voltam, mas um /loop em ritmo próprio não volta, então execute-o de novo.¹² Para o trabalho que precisa sobreviver à sessão, a documentação compara três superfícies:¹²

Para o trabalho que precisa rodar com a sua máquina desligada, existem as tarefas agendadas na nuvem.

O plugin Ralph — iterar até cumprir a promessa

O plugin oficial ralph-loop do Anthropic transforma em produto o padrão de força bruta favorito da comunidade. Ele se chama ralph-loop no repositório anthropics/claude-plugins-official desde 6 de janeiro de 2026, quando o Anthropic o renomeou de ralph-wiggum “por orientação jurídica”. Em 26 de outubro de 2026, o repositório claude-code excluiu sua própria cópia desatualizada de ralph-wiggum, e o marketplace dele agora instala o ralph-loop a partir do repositório oficial, de modo que “os IDs de plugin existentes continuam funcionando”.¹⁴ O mecanismo: um Stop hook intercepta a tentativa do Claude de encerrar a sessão e reinsere o prompt, fazendo o modelo iterar continuamente em uma única sessão. /ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<string>" inicia o processo; /cancel-ralph o interrompe. O README deixa claro que --max-iterations é “seu principal mecanismo de segurança” — a correspondência exata da string de conclusão pode falhar para sempre.¹⁴ Um limite do harness fica por baixo de todo loop de Stop hook: “Se o hook bloquear oito paradas seguidas sem nenhuma chamada de ferramenta entre elas, o Claude Code ignora o próximo bloqueio e encerra o turno” (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP aumenta o limite).²⁹ Isso encerra um loop que parou de progredir; não encerra um loop Ralph que continua chamando ferramentas, então o limite de iterações continua importando.

Workflows dinâmicos — o Claude escreve o graph

Introduzidos no Claude Code v2.1.154 (maio de 2026) e detalhados na publicação de lançamento do Anthropic de 2 de junho de 2026, os workflows dinâmicos representam o maior salto conceitual: “agora, o Claude pode escrever seu próprio harness em tempo real, criado especificamente para a tarefa em questão”.¹⁵ Você descreve a tarefa, diz “use um workflow” ou inclui a palavra-chave ultracode; o Claude escreve um script de orquestração em JavaScript, no qual agent() inicia um subagent com saídas opcionais no schema do JSON, pipeline() executa um por item de uma lista, parallel() executa um conjunto de uma só vez, e await/loops/condicionais comuns controlam o fluxo; um runtime o executa em segundo plano. /effort ultracode vai além: o Claude “planeja um workflow para cada tarefa substancial da sessão”, e uma sessão assim “atinge um limite da sessão ou semanal mais cedo do que o mesmo trabalho com ele desativado”.¹⁶ “Um workflow transfere o plano para o código… O próprio script do workflow mantém o loop, as ramificações e os resultados intermediários, de modo que o contexto do Claude contenha apenas a resposta final.”¹⁶

Limites e formato, segundo a documentação:¹⁶

Scripts salvos em .claude/workflows/ tornam-se comandos slash reutilizáveis. Uma execução é retomada a partir dos resultados de agentes salvos quando o Claude a reinicia, mas um agente que falhou “é executado novamente, assim como todo agente que o script inicia depois dele, mesmo os que foram concluídos”, e uma execução que você coloca em segundo plano ou encerra no meio “não continua sozinha”.¹⁶

A topologia característica é distribuir / refutar / convergir: agentes de busca independentes, seguidos por verificadores adversariais instruídos a refutar cada descoberta, iterando até que as respostas resistam às contestações. O Anthropic agora oferece uma instância dela: o workflow integrado /deep-research “distribui buscas na web sobre uma pergunta por vários ângulos, obtém e cruza as fontes que encontra, vota em cada afirmação e retorna um relatório com citações, do qual são filtradas as afirmações que não resistiram à verificação cruzada”, e quando seus verificadores não conseguem checar uma afirmação, “o relatório lista essa afirmação como não verificada em vez de contá-la como refutada”.¹⁶ O principal resultado divulgado no lançamento: a migração para Rust da base de código de 535.496 linhas em Zig do Bun — resultando em uma base de código Rust com mais de 1 milhão de linhas — em 11 dias (de 3 a 14 de maio de 2026), realizada por 64 agentes em paralelo, segundo o relato de Jarred Sumner.¹⁵

Agent teams — o graph entre pares

Por trás de CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (adicionado como research preview na v2.1.32, fevereiro de 2026; a documentação agora diz “Agent teams são experimentais e ficam desativados por padrão”): um líder de equipe e colegas que “trabalham de forma independente, cada um em sua própria janela de contexto, e se comunicam diretamente entre si”. Isso forma um graph entre pares em vez de uma árvore de subagents, coordenado por meio de uma lista compartilhada de tarefas com dependências, reivindicação de arquivos por bloqueio e caixas de mensagens por agente. Quality gates impostas por hooks colocam verificações automatizadas entre um colega de equipe e a declaração de “concluído”: TaskCompleted com código de saída 2 bloqueia a conclusão, e TeammateIdle com código de saída 2 mantém um colega de equipe trabalhando.¹⁷ Dois comportamentos que você precisa conhecer antes de ativar o recurso: enquanto agent teams estiverem ativados, “um subagent que o Claude nomeia é iniciado como colega de equipe, então equipes podem se formar mesmo quando você não pediu uma”, e “Um colega de equipe não pode aprovar um prompt de permissão nem fornecer consentimento em seu nome”.¹⁷

Routines — loops que continuam após você fechar o laptop

Uma tarefa agendada na nuvem (antes chamada de routine) é “uma configuração salva do Claude Code: um prompt, um ou mais repositórios e um conjunto de conectores, agrupados uma vez e executados automaticamente”, que roda na infraestrutura de nuvem gerenciada pelo Anthropic ou no ambiente self-hosted da sua organização.¹⁸ O nome antigo sobrevive onde a mudança quebraria algo: o endereço web (claude.ai/code/routines), o alias /routines para /schedule e o caminho de API /fire. Há três tipos de gatilho, que podem ser combinados: um agendamento (mínimo de 1 hora para uma cadência recorrente, ou uma execução única em um horário definido), disparo por API (POST .../routines/{id}/fire) e eventos de GitHub. São criadas por meio de /schedule, do aplicativo Desktop ou de claude.ai/code/routines. A sessão de uma execução começa no modo automático, a menos que ele esteja indisponível; um classificador permite ou bloqueia cada ação, e a execução para e aguarda em casos como uma ação que pede confirmação mesmo no modo automático (uma regra ask) ou bloqueios repetidos. É exatamente por isso que a ressalva da documentação é essencial: o resultado de uma execução diz “como a sessão terminou, não se o Claude concluiu o trabalho que o seu prompt descreve, então abra a execução e leia a transcrição para ver o que aconteceu”.¹⁸ Duas correções desde setembro mostram que essa lacuna é real: até a v2.1.286, execuções cuja sessão na nuvem nunca começou apareciam como Succeeded, e até a v2.1.302, execuções apareciam “como Completed depois que sua sessão na nuvem parou inesperadamente”.³⁶ A mesma versão impediu que uma execução que falhou no meio fosse executada novamente desde o início, “o que podia repetir trabalho, como publicar o mesmo relatório duas vezes”, um motivo para tornar idempotente o trabalho disparado.³⁶

O Anthropic executa “talvez 20 ou 30 dessas routines todos os dias” em suas próprias bases de código — limpeza de código morto, cobertura de testes e lançamento de experimentos.³

O elenco de apoio

Subagents em segundo plano (padrão desde a v2.1.198) mantêm o trabalho delegado fora do seu contexto; o painel /agents permite monitorá-los. Mensagens entre sessões (v2.1.224) transformam sessões independentes em um graph de troca de mensagens por meio de SendMessage, com uma doutrina de segurança que vale a pena adotar: uma mensagem de outra sessão “nunca conta como seu consentimento”.¹⁹ A partir de uma sessão conectada ao Remote Control, elas também alcançam suas sessões em outras máquinas (v2.1.225+) e na nuvem. Para esperas entre loops, a entrada notify_when_idle (v2.1.236+)³⁶ pede a uma sessão nesta máquina um único aviso quando ela ficar ociosa ou for encerrada, e o Claude Code se inscreve “sem iniciar um turno nem gastar tokens na sessão observada”.¹⁹ Runners self-hosted (v2.1.224, Team/Enterprise) executam sessões na nuvem e tarefas agendadas na nuvem (antes chamadas de routines) nas suas próprias máquinas, a infraestrutura para frotas em escala organizacional.²⁰

O padrão Ralph

A comunidade chegou aqui primeiro. Em julho de 2025, Geoffrey Huntley publicou o ensaio que deu à técnica o nome do personagem de The Simpsons: Ralph é literalmente

while :; do cat PROMPT.md | claude-code ; done

— seu comando de uma linha, exatamente como publicado — um repositório, uma tarefa por iteração, contexto novo a cada passagem, com especificações e arquivos de progresso no sistema de arquivos mantendo o estado entre as iterações, e testes e linters funcionando como “contrapressão”.²¹ A versão moderna sem interface desse mesmo formato é claude -p "$(cat PROMPT.md)" em um loop de shell, que é essencialmente o que o próprio harness de compilador C de Anthropic executou.²³ Os resultados que ele relatou (MVP de um contrato de US$ 50 mil por US$ 297 em tokens; seis repositórios em uma noite num hackathon) vieram com limites igualmente claros: apenas projetos começando do zero, implementações provisórias e duplicadas como falhas recorrentes, e “LLMs são espelhos da habilidade de quem opera”.

Anthropic nunca usa esse nome em seu material de engenharia, mas o padrão agora é doutrina oficial em duas frentes: o ensaio de novembro de 2025 sobre agentes de longa duração prescreve exatamente esse formato — um agente inicializador criando listas de funcionalidades e arquivos de progresso, seguido de novos agentes de programação a cada janela de contexto que “iniciam a sessão lendo o arquivo de notas de progresso e os logs de commits do git”²² — e o projeto de compilador C de fevereiro de 2026 executou dezesseis agentes Claude em paralelo — “Criei um harness que coloca Claude em um loop simples”, como descreve Nicholas Carlini — com bloqueios de tarefas baseados em arquivos e git como camada de sincronização, produzindo cerca de 100 mil linhas de Rust ao longo de aproximadamente 2.000 sessões por cerca de US$ 20 mil.²³ A frase do ensaio sobre verificação resume toda a teoria do padrão: “é importante que o verificador de tarefas seja quase perfeito”.

Por que um contexto novo supera uma única sessão longa: a eficácia diminui conforme o contexto da sessão se enche — o consenso entre profissionais situa o limiar de desvio em torno de 100 mil tokens — e os resumos de compactação são paráfrases com perdas que transformam erros em afirmações confiantes.²⁴ A arquitetura do Ralph, com novas instâncias e arquivos, contorna ambos os problemas. (Os loops dentro da sessão do plugin oficial abrem mão de parte disso em troca de conveniência; para execuções longas, a versão sem interface e com estado externo continua sendo o padrão mais sólido.)

O caso que serve de alerta sobre o padrão também é instrutivo: um profissional executou o plugin com um prompt vago e max_iterations: 0 — que significa infinito, não desativado — e Claude fez a si mesmo a mesma pergunta de esclarecimento 1.966 vezes, com o hook Stop sequestrando todas as mensagens seguintes.²⁵ Limites de iteração não são opcionais.

Quando loops viram grafos

Um único loop pressupõe que suas iterações sejam independentes ou estritamente sequenciais. Assim que o trabalho paralelo passa a ter dependências — a tarefa B precisa da saída de A, dois agentes editariam o mesmo arquivo — loops sem estrutura entram em conflito, e você precisa de uma estrutura explícita: uma lista de tarefas com arrays de dependências, reserva de arquivos e disciplina de merge. Esse é o verdadeiro ponto do debate entre loops e grafos: loops para um repositório e um objetivo; grafos quando o trabalho paralelo precisa de ordenação.²⁶

As opções de grafos, em ordem crescente de infraestrutura:

1. Workflows dinâmicos — dependências expressas no fluxo de controle de JavaScript; barreiras apenas quando uma etapa realmente precisa de todos os resultados anteriores. As topologias que Anthropic cita: distribuição e síntese, verificação adversarial, geração e filtragem, torneio (“Crie N agentes que tentem realizar a mesma tarefa usando abordagens diferentes” e depois avalie os resultados em pares) e repetição até a conclusão.¹⁵
2. Equipes de agentes — uma lista de tarefas compartilhada com rastreamento de dependências; um colega de equipe criado enquanto o líder está no modo de planejamento envia seu plano para aprovação, e o Claude Code o aprova automaticamente; o líder só o revisa se você colocar um colega de equipe in-process em execução no modo de planejamento (Shift+Tab); o grafo é composto de dados, não de código.¹⁷ Uma configuração padrão mudou nesse modelo, primeiro na v2.1.233:³⁴ as ferramentas de acompanhamento de tarefas (TaskCreate, TaskGet, TaskUpdate, TaskList, TodoWrite) agora ficam “disponíveis por padrão apenas no Opus 4.7, Sonnet 4.6, Haiku 4.5 e modelos anteriores”, um conjunto padrão que vale a partir da v2.1.268.³⁸ Agentes sem elas “se coordenam por mensagens em vez de usar a lista de tarefas compartilhada”,¹⁷ então, em um modelo atual numa sessão local comum, a lista de tarefas não está lá a menos que você a ative; sessões em segundo plano e na nuvem recebem as ferramentas em todos os modelos.³⁸ Ative-as com CLAUDE_CODE_ENABLE_TODO_TOOLS=1, --allowedTools TaskCreate ou uma lista --tools que as inclua. Uma variável exportada não chega a um colega de equipe em painel dividido; para dar as ferramentas a ele, inicie o líder com claude --settings '{"env":{"CLAUDE_CODE_ENABLE_TODO_TOOLS":"1"}}'.³⁸
3. Orquestradores externos — a expansão de escala promovida pela comunidade: o Gas Town de Steve Yegge executa de 20 a 30 instâncias de Claude Code sobre DAGs de “beads” persistidos em git (75 mil linhas de Go em 17 dias, segundo ele próprio, também “uma máquina de consumir dinheiro” que exige muita habilidade de quem opera);²⁷ claude-flow/Ruflo (cerca de 31 mil estrelas) organiza enxames em uma hierarquia de rainha e operárias; mecanismos no estilo LangGraph acrescentam uma máquina de estados tipada por cima, com Claude Code dentro dos nós.

A formalização dessa trajetória pelo próprio Cherny é a escala Etapas de adoção de IA, publicada por Anthropic em julho de 2026: Com aprovação (0 agentes) → Assistida (~1) → Paralela (~10) → Autonomia supervisionada (~100, em que “a maioria dos agentes é iniciada por Claude, não por humanos”) → Nativa de IA (1.000+). Seu conselho: “a cada etapa… você precisa encontrar e eliminar o próximo conjunto de gargalos e criar o próximo conjunto de mecanismos de proteção”.²⁸

Engenharia de verificação

Tudo acima é infraestrutura. Esta seção é o produto.

A escala de escalonamento de Anthropic, segundo a documentação atual de boas práticas, parte de uma dica: “Dê ao Claude algo que ele possa executar e que retorne aprovação ou reprovação. Quando ele tiver isso, pode seguir sozinho e você não precisa ficar observando.” Os degraus então vão do Claude decidindo ao harness impondo: uma linha no prompt (run the auth tests after, and keep going until they pass) → uma condição de /goal que “um modelo separado verifica com base na conversa após cada turno”, o que “importa em execuções longas em segundo plano, nas quais o Claude às vezes encerra um turno com um resumo do progresso enquanto ainda há itens em aberto” → um hook Stop, “imposto pelo Claude Code (o harness), de modo que o turno não termina até que a verificação de tipos passe ou o limite de bloqueios seja atingido” → a revisão “Por alguém que não escreveu o código”, em que /code-review “revisa o diff em um subagent novo que nunca viu sua conversa. Ele não é influenciado pelo raciocínio que produziu o código.”²⁹ A exigência de evidência associada: “peça ao Claude evidências: o comando que ele executou e a saída, ou a captura de tela”, porque “Em uma sessão que você não estava acompanhando, essa também é a única evidência que você tem”.²⁹ A refutação adversarial, o degrau em que essa escala terminava, agora está na documentação de workflows, cujo prompt de exemplo pede que um workflow “verifique adversarialmente cada descoberta antes de relatá-la”.¹⁶

A mesma documentação classifica cada instrução entre o que o Claude decide e o que o Claude Code impõe. Três de suas linhas são as regras de parada, de orçamento e de merge de um loop:²⁹

Um loop sem supervisão precisa de uma entrada da coluna da direita em cada linha; a coluna da esquerda é tudo o que um loop tem quando ninguém escreveu uma. A documentação também aposenta um hábito de prompt: frases como “continue, repita o loop até terminar, não tenha preguiça” têm “mais probabilidade de causar excesso de trabalho do que de resolver uma paralisação”, e “em execuções que ninguém está acompanhando, /goal ou um hook Stop impõe isso”.²⁹

As três classes de feedback, segundo o ensaio Agent SDK: feedback baseado em regras (“regras claramente definidas para uma saída, seguidas de uma explicação de quais regras não foram cumpridas e por quê” — a melhor forma), feedback visual (capturas de tela, diferenças entre pixels) e LLM como juiz (critérios imprecisos — nas palavras de Anthropic, “em geral, não é um método muito robusto”).⁷ Dê preferência a elas nessa ordem; uma verificação determinística disponível vale mais que um juiz que dá opiniões.

Condições de convergência. A análise crítica mais incisiva sobre loops — a de Yoko Li, de agosto de 2026 — reduz a convergência a quatro requisitos: um estado de destino definido, um estado atual observável, edições locais precisas e regras de parada fora do gerador. Seu experimento instrumentado traz o número que vale lembrar: 67% do gasto de tokens do loop não produziu nenhuma melhoria, porque nada avisava ao loop que os ganhos haviam passado a ser logarítmicos.³⁰ Limites de orçamento não servem apenas para controlar custos; são uma regra de parada de último recurso.

Integridade dos testes. Da doutrina de Anthropic sobre agentes de longa duração: “É inaceitável remover ou editar testes, pois isso pode levar a funcionalidades ausentes ou com bugs”.²² Loops burlam especificações — passam nos testes visíveis enquanto deixam de atender à intenção implícita —, por isso o próprio verificador precisa ser protegido do agente que avalia.

Avalie os resultados, não os caminhos. Do ensaio sobre avaliações: “Avalie o que o agente produziu, não o caminho que percorreu”, use avaliadores baseados em código quando os critérios forem objetivos e avaliadores baseados em modelos para rubricas, e faça a calibração: “Você não saberá se seus avaliadores estão funcionando bem a menos que leia as transcrições e as notas de muitas tentativas”.³¹

Mais uma distinção que boa parte da discussão deixa passar: quando todas as verificações de um loop são determinísticas, não há lugar para um modelo nesse loop. Um monitor de desvios que compara timestamps, um verificador de links, um monitor de builds — tudo isso são scripts de shell agendados: zero tokens, segundos por execução, perfeitamente repetíveis. Reserve os loops orientados por modelos para iterações que exigem discernimento. O loop mais barato é aquele que nunca chama um modelo.

Disciplina de custos e segurança

A objeção mais forte da comunidade à engenharia de loops é o custo, e os relatos de incidentes confirmam isso: um bug na criação de subagents consumindo 4M de tokens em cinco minutos; loops noturnos consumindo milhares de dólares; limites de uso atingidos “muito mais rápido do que o esperado”.³² Uma dessas barreiras mudou desde então: a partir da v2.1.234, uma sessão continua automaticamente quando um limite de uso do claude.ai é restabelecido (a configuração autoContinueAtUsageLimit; desative em /config → “Continue automatically at usage limit”).³⁴³⁷ O alcance é restrito. “A continuação automática vem ativada por padrão em sessões interativas conectadas com uma assinatura do claude.ai”; o Claude Code não inicia a espera por conta própria para “Uma redefinição a mais de 24 horas de distância”, como um limite semanal; sair do Claude Code encerra a espera; e o Claude Code “nem chega a oferecer a espera” em “Sessões em segundo plano e execuções com -p”, o que inclui o Ralph headless e claude -p "/goal ...".³⁷ Dentro de uma sessão elegível, os loops acompanham esse comportamento: um /goal pausado é retomado na redefinição,⁹ e, desde a v2.1.271, uma execução de workflow aguarda o fim do limite em vez de fazer seus agentes falharem, no máximo duas vezes por execução.¹⁶ Um loop noturno que permanece em uma sessão interativa aberta agora pode sobreviver ao limite; um que roda headless ou em uma sessão em segundo plano ainda para nele. Isso torna os controles de orçamento abaixo ainda mais importantes. A disciplina que surgiu, com cada elemento associado a um controle já disponível:

Essa última linha merece um parágrafo próprio, porque é assim que os profissionais mais ousados mantêm a segurança: faça do pull request o limite do impacto. Os agentes permanentes de Cherny em segundo plano — um melhorando continuamente a arquitetura, outro procurando abstrações duplicadas — enviam PRs sem acionamento humano;² nada é integrado sem revisão. Um loop sempre ativo cujo pior caso é “uma branch não integrada” pode operar intensamente; um loop que escreve na main não pode. As tarefas agendadas na nuvem trazem isso como padrão: “o Claude envia seu trabalho para uma branch com o prefixo claude/, a menos que seu prompt o instrua a enviar para outra branch”, e a proteção de branch ou os rulesets do GitHub decidem para onde uma execução pode enviar.¹⁸ Promova loops gradualmente: comece apenas com observação (relatórios, sem gravações), conquiste confiança ao longo de execuções sem surpresas e depois avance para a proposta de alterações — com a prova de ordenação (“a limpeza só é executada depois que a verificação retorna o novo marcador”) e uma declaração exaustiva do alcance do impacto registradas antes de instalar o agendamento. A economia desse caminho de promoção é o tema de Loops vencem onde a verificação é barata: o custo da verificação, e não a construção do loop, determina o que pode funcionar sem supervisão.

Nenhuma entrada de loop conta como consentimento. Quatro regras documentadas se alinham: uma mensagem de outra sessão “nunca conta como seu consentimento”;¹⁹ um colega de equipe “não pode aprovar um prompt de permissão nem fornecer consentimento em seu nome”;¹⁷ o prompt disparado de uma tarefa agendada na nuvem “não pode servir como aprovação ou consentimento para ações durante a execução”, e o texto enviado com um disparo por API “chega envolvido em um bloco <routine-fire-payload> que o marca como dados não confiáveis”;¹⁸ e, no modo automático, o prompt que um script de workflow passa para agent() “não conta como uma solicitação sua” porque “o Claude Code o marca como texto calculado pelo script”.¹⁶ Copie a regra para os seus próprios loops: texto produzido por uma máquina é dado, e a aprovação vem de uma pessoa.

A objeção mais profunda não é o custo, mas a capacidade de revisão — loops produzem código mais rápido do que humanos conseguem revisá-lo de forma criteriosa.³³ Não há resposta engenhosa; só há honestidade ao definir o escopo: loops sem supervisão só cabem onde a verificação pode ser feita por máquina. Se você não consegue verificar, não publique.

O que um estudo controlado diz sobre os componentes de um harness

A maioria das recomendações sobre harness, incluindo as deste guia, vem de profissionais que alteram uma coisa por vez em produção. Um estudo de setembro de 2026 da UMass Amherst, Emory, UNC Charlotte e Zoom fez isso em condições controladas: um harness criado para esse fim, “cujo loop de execução é fixo enquanto três componentes variam: planejamento, espaço de ações e gerenciamento de contexto”, executado em “176 configurações pareadas abrangendo cinco estratégias de gerenciamento de contexto, quatro orçamentos de janela de contexto e ablações direcionadas de planejamento e espaço de ações” no SWE-Bench Verified e no Terminal-Bench 2.1, com quatro modelos de pesos abertos, três tamanhos do Nemotron-3 e o Mistral-Medium-3.5-128B.³⁵ Suas quatro conclusões, nas palavras dos autores:

• “O gerenciamento de contexto se torna cada vez mais valioso à medida que o orçamento da janela de contexto diminui, com a maior parte do benefício vindo da prevenção de falhas por estouro de contexto.”
• “Aplicar a supressão baseada em regras antes da sumarização baseada em LLM oferece a melhor eficiência geral entre as estratégias de gerenciamento de contexto, enquanto tornar o conteúdo suprimido recuperável acrescenta mecanismos que os modelos raramente usam e não gera ganho de acurácia.”
• “O planejamento deixa de ser um apoio à acurácia para modelos mais fracos e passa a reduzir custos para modelos mais fortes, com pouca mudança na acurácia.”
• “Ferramentas predefinidas melhoram o desempenho de modelos com menor proficiência em bash, enquanto modelos proficientes em bash conseguem operar de forma eficaz com uma interface exclusivamente bash e atingir custos substancialmente menores, especialmente em tarefas centradas na linha de comando.”

Na minha leitura, três dessas conclusões se aplicam diretamente à engenharia de loops. O gerenciamento de contexto é uma proteção contra estouros: um loop de longa duração deve definir um orçamento para sua janela e suprimir saídas volumosas de ferramentas antes de resumir qualquer coisa, e pode dispensar a construção de mecanismos de recuperação que o modelo não usará. Para um modelo capaz, o planejamento é um ajuste de custo, não uma alavanca de acurácia, algo que vale saber antes de adicionar uma fase de planejamento a um loop que usa um modelo forte. E o resultado com bash exclusivo é a separação exec/modelo um nível acima: quando quem executa é capaz, ações menos numerosas e mais abrangentes custam menos. As ressalvas são as do próprio estudo. Quatro modelos, dois benchmarks e um harness construído para o experimento, em vez de um agente disponível no mercado, portanto os resultados servem como orientações, não como configurações.³⁵

Operando uma frota

O estado final da engenharia de loops não é um único loop; é uma frota permanente. Como a prática fica quando se estabiliza:

• Especificações como arquivos. Cada loop é uma especificação versionada — nome, nível, agendamento, objetivo, verificador, ferramentas permitidas, orçamento, tempo limite — armazenada no repositório ao qual serve. Se você já digitou a mesma verificação manual três vezes, ela vira uma especificação. O Anthropic oferece uma versão pequena da ideia: um arquivo loop.md substitui o prompt integrado do /loop sem argumentos, e as edições nele entram em vigor na próxima iteração.¹²
• Dois níveis, promoção conquistada. Loops de observação leem qualquer coisa, gravam apenas no próprio diretório de relatórios e podem ser agendados imediatamente. Loops de ação alteram o mundo e exigem a prova de ordenação, a declaração do alcance do impacto e um verificador que não seja o criador — tudo registrado antes de o agendamento existir. Loops começam como observadores e conquistam a promoção.
• A separação exec/modelo. Verificações determinísticas rodam como scripts (zero tokens, 1–2 segundos); loops com modelos ficam reservados para decisões que exigem julgamento. A rotina diária de uma frota pode não custar nada.
• Contratos de relatório. Uma linha por verificação, PASS|FAIL <check>: <reason>, acrescentada a um arquivo de relatório datado. Se você não consegue definir uma linha de PASS compreensível à primeira vista, o loop não está pronto. Um loop de resumo lê os relatórios da frota para que a pessoa leia uma página, não trinta.
• Referências que se mantêm atualizadas sozinhas. Os melhores monitores de desvios derivam as expectativas do artefato que protegem — os próprios registros de data e hora de um guia, os próprios hashes de um lockfile — de modo que atualizar o artefato atualiza o monitor, sem uma segunda fonte de verdade que possa ser esquecida.
• Agendamento que persiste. Frotas locais rodam no agendador do sistema operacional (launchd, cron, timers do systemd), que invoca um script executor, ou nas tarefas agendadas do Desktop quando a máquina fica ligada; frotas na nuvem são tarefas agendadas na nuvem (antes chamadas de rotinas). Loops vinculados à sessão (/loop) servem para o trabalho que você acompanha ou para uma sessão em segundo plano.¹²

É a frase de Cherny, “meu trabalho é escrever loops”, concretizada: o trabalho humano passa a ser especificar verificações, verificadores e orçamentos — e ler os relatórios.

Os dois primeiros loops que vale a pena construir

Se você está começando uma frota do zero, dois loops se pagam imediatamente — ambos comprovados no harness deste próprio site:

O loop de aprovação — criador e revisor para qualquer coisa que você publique. Um novo avaliador (sem memória das rodadas anteriores) pontua o artefato segundo um patamar explícito; você aplica todos os apontamentos; outro avaliador pontua novamente; o loop para ao atingir o patamar ou um limite rígido de rodadas. Duas observações de campo após usá-lo em uma rodada de quinze posts: correções podem introduzir novos defeitos (a correção de uma rodada atribuiu incorretamente um número, e o avaliador da rodada seguinte detectou o erro), e avaliadores erram nos dois sentidos — um “corrigiu” com convicção uma afirmação verdadeira, por isso correções específicas são verificadas na fonte antes de serem aplicadas. O revisor não é a autoridade; a fonte é.

O zelador — o ponto de entrada para o nível de ação. Uma correção pequena e objetivamente verificável por execução, em uma branch, com testes passando antes da abertura do PR, e o loop nunca faz o merge. Duas regras mantêm a segurança: qualquer ambiguidade é sinalizada, não corrigida (a primeira execução supervisionada recusou corretamente um falso positivo do detector), e uma falha preexistente na main é relatada como tal, nunca incorporada ao diff do loop.

Um detalhe de operação de frotas que vale copiar: dê aos loops com modelos sem supervisão uma reserva de sessão — adie qualquer execução enquanto houver uma sessão interativa ativa no mesmo repositório. Dois processos gravando em um único checkout acabarão intercalando commits; a reserva faz o loop ceder a vez à pessoa por construção.

Perguntas frequentes

O que é engenharia de loops?

A prática de fazer agentes de IA repetirem ciclos de trabalho até que uma condição de parada seja atendida, em vez de enviar prompts a cada turno. O trabalho de engenharia passa da escrita de prompts para o projeto do loop: sua regra de reativação (uma condição, um agendamento, um evento), seu estado entre iterações, seu verificador e seu orçamento. Anthropic deu nome à disciplina em junho de 2026; seus recursos no Claude Code são /goal, /loop, o plugin Ralph, tarefas agendadas na nuvem (antes chamadas de rotinas) e workflows dinâmicos.

O que é um loop Ralph?

Um padrão de autonomia por força bruta batizado por Geoffrey Huntley em julho de 2025: executar Claude Code em um loop while do shell, fornecendo o mesmo prompt com contexto novo a cada iteração, com arquivos de progresso e git preservando o estado entre as passagens e testes atuando como contrapressão. Anthropic disponibiliza um plugin oficial ralph-loop (renomeado de ralph-wiggum em janeiro de 2026) que executa o loop dentro da sessão por meio de um hook Stop, com --max-iterations como principal mecanismo de segurança.

Como executo Claude Code em um loop?

Escolha o nível mais baixo que atenda à necessidade: /goal <condition> para iterar até que um avaliador separado confirme uma condição; /loop <interval> <prompt> para execuções recorrentes enquanto uma sessão do Claude Code estiver em execução; /ralph-loop para iterar em uma tarefa até uma promessa de conclusão; /schedule para criar uma tarefa agendada na nuvem que roda via cron sem depender da sua máquina. Sem interface interativa, claude -p dentro de um loop de shell com uma verificação externa é a forma clássica.

Loops substituem a escrita de prompts?

O prompt não desaparece — ele muda de lugar. Você o escreve uma vez, na especificação do loop, e o loop o aciona novamente; cada vez mais (workflows dinâmicos, a frase de Cherny “na verdade, é outro Claude que escreve os prompts”), um agente orquestrador escreve os prompts de cada tarefa. O que substitui a elaboração de prompts como ofício humano é o projeto da verificação: definir condições que uma máquina ou um modelo com contexto novo possa verificar.

Qual é a diferença entre um loop, uma rotina e um workflow no Claude Code?

Um loop (/loop) executa novamente um prompt de forma agendada dentro de uma sessão local do Claude Code e deixa de disparar quando esse processo é encerrado; uma sessão em segundo plano o mantém rodando. Uma tarefa agendada na nuvem (antes chamada de rotina) é a mesma ideia preparada para rodar em infraestrutura de nuvem: acionada por cron, API ou eventos de GitHub, sem precisar de um notebook. Um workflow é o grafo de orquestração de uma única execução: um script JavaScript escrito por Claude que cria e coordena até 1.000 subagents, com loops e ramificações mantidos no código, em vez de no contexto.

Quanto custam os loops de agentes?

A faixa honesta é “de zero a um prejuízo enorme”, e a variável é o projeto. Monitores determinísticos não custam nada — são scripts agendados. Loops com modelos têm o uso contabilizado por iteração: imponha limites (--max-iterations, --max-budget-usd), torne os ganhos observáveis para que o loop possa parar quando eles diminuírem e trate cada limite como uma regra de parada, não como um inconveniente. Os relatos de falhas — milhares de dólares em uma noite, 4M de tokens em minutos — compartilham uma causa raiz: nenhuma condição externa de parada.

Quando um loop deve virar um grafo?

Quando surgem dependências no trabalho paralelo: uma tarefa precisa da saída de outra, ou dois agentes alterariam os mesmos arquivos. Loops lidam com um repositório e um objetivo; grafos (workflows dinâmicos, equipes de agentes, orquestradores externos) acrescentam ordenação de dependências, reserva de arquivos e disciplina de merge. Adote grafos apenas quando as colisões realmente aparecerem — a estrutura adicional exige esforço de observabilidade e configuração.

Histórico de alterações