Introdução aos Loops no Claude Code

Há muita discussão atualmente sobre "projetar loops" em vez de apenas dar comandos ao seu agente de codificação. Se você passar algum tempo no X tentando definir o que realmente é um loop, encontrará várias respostas diferentes.

Na equipe do Claude Code, definimos loops como agentes que repetem ciclos de trabalho até que uma condição de parada seja atendida. Categorizamos alguns tipos diferentes de loops com base em:

• Como são acionados
• Como são interrompidos
• Qual primitiva do Claude Code é usada
• Qual tipo de tarefa é mais adequada para cada um.

Abordaremos os principais tipos de loop, quando usar cada um e como manter a qualidade do código enquanto gerenciamos o uso de tokens. Nem todas as tarefas exigem loops complexos; comece com a solução mais simples e use esses padrões seletivamente.

Loques baseados em turnos

• Acionado por: Um comando do usuário.
• Critério de parada: Claude decide que concluiu a tarefa ou precisa de mais contexto.
• Melhor usado para: Tarefas mais curtas que não fazem parte de um processo ou cronograma regular.
• Uso gerenciado por: Escreva comandos específicos e melhore a verificação usando habilidades para reduzir o número de turnos.

Cada comando que você envia inicia um loop manual com você direcionando cada turno. Claude reúne contexto, age, verifica seu trabalho, repete se necessário e responde. Chamamos isso de loop agentivo.

Por exemplo, peça ao Claude para criar um botão de "curtir". Ele lê seu código, faz a edição, executa os testes e devolve algo que acredita funcionar. Você então verifica manualmente o trabalho e escreve o próximo comando.

Você pode melhorar a etapa de verificação codificando suas etapas manuais como um SKILL.md para que Claude possa verificar mais do seu próprio trabalho, de ponta a ponta. Isso deve incluir ferramentas ou conectores para permitir que Claude veja, meça ou interaja com o resultado. Quanto mais quantitativas forem as verificações, mais fácil será para Claude se auto-verificar.

Por exemplo, no seu arquivo SKILL.md, você pode especificar:

1---
2name: verificar-alteracao-frontend
3description: Verifique qualquer alteração de UI de ponta a ponta antes de declará-la concluída.
4---
5
6# Verificando alterações de frontend
7Nunca relate uma alteração de UI como completa com base apenas em uma edição bem-sucedida. Verifique-a da mesma forma que um revisor humano faria:
8
91. Inicie o servidor de desenvolvimento e abra a página editada no navegador.
10
112. Interaja diretamente com a alteração. Para um novo controle (botão, campo de entrada, alternância): clique nele, confirme a mudança de estado esperada e tire um print antes/depois.
12
133. Verifique o console do navegador: zero novos erros ou avisos.
14
154. Use o MCP do Chrome Devtools, execute um trace de desempenho e audite os Core Web Vitals.
16
17Se alguma etapa falhar, corrija o problema e execute novamente a partir da etapa 1 — não entregue trabalho parcialmente verificado.

Loop baseado em meta (/goal)

• Acionado por: Um comando manual em tempo real.
• Critério de parada: Meta alcançada OU número máximo de turnos atingido.
• Melhor usado para: Tarefas que têm critérios de saída verificáveis.
• Uso gerenciado por: Definindo critérios de conclusão específicos e limites explícitos de turnos, "pare após 5 tentativas."

Às vezes, um único turno não é suficiente, especialmente para tarefas mais complexas. Agentes se saem melhor quando podem iterar. Você pode estender quanto tempo Claude continua iterando definindo como é a conclusão com /goal.

Quando você define os critérios de sucesso, Claude não precisa decidir o que é "bom o suficiente" e encerrar o loop precocemente. Cada vez que Claude tenta parar, um modelo avaliador verifica sua condição e o envia de volta ao trabalho até que a meta seja atingida ou um número de turnos definido por você seja alcançado.

É por isso que critérios determinísticos, como número de testes aprovados ou atingir um determinado limite de pontuação, são tão eficazes.

Por exemplo:

1/goal obter a pontuação Lighthouse da página inicial em 90 ou mais, pare após 5 tentativas.

Loop baseado em tempo (/loop e /schedule)

• Acionado por: Um intervalo de tempo especificado.
• Critério de parada: Você o cancela, ou o trabalho é concluído (o PR é mesclado, a fila está vazia).
• Melhor usado para: Trabalhos recorrentes ou para interfacear com ambientes/sistemas externos.
• Uso gerenciado por: Defina intervalos maiores ou reaja com base em eventos em vez de tempo.

Alguns trabalhos agentivos são recorrentes: a tarefa permanece a mesma e apenas as entradas mudam. Por exemplo, resumir mensagens do Slack todas as manhãs. Outros trabalhos dependem de sistemas externos, e uma maneira simples de interfacear com um é verificá-lo em um intervalo e reagir ao que mudou. Por exemplo, um PR que pode receber revisões de código ou falhar no CI.

Para esses casos, você pode acionar quando Claude executa com /loop que reexecuta um comando em um intervalo. Por exemplo:

1/loop 5m verifique meu PR, aborde comentários de revisão e corrija o CI com falha

/loop é executado no seu computador, então se você o desligar, ele para. Você pode mover o loop para a nuvem criando uma rotina com /schedule.

Loops proativos

• Acionado por: Um evento ou cronograma, sem humano em tempo real.
• Critério de parada: Cada tarefa termina quando sua meta é atingida. A própria rotina é executada até que você a desligue.
• Melhor usado para: Fluxos recorrentes de trabalho bem definido: relatórios de bugs, triagem de issues, migrações, atualizações de dependências, etc.
• Uso gerenciado por: Roteando rotinas para modelos menores e mais rápidos e usando o modelo mais capaz para decisões de julgamento.

As primitivas acima, juntamente com outros recursos do Claude Code como modo automático e fluxos de trabalho dinâmicos (pré-visualização de pesquisa) podem ser compostas em um loop para trabalhos de longa duração.

Por exemplo, para lidar com feedback recebido, você pode usar:

1. `/schedule` (pré-visualização de pesquisa) para executar uma rotina que verifica novos relatórios
2. `/goal` para definir como é a conclusão e habilidades para documentar como verificar
3. Fluxos de trabalho dinâmicos para orquestrar agentes que triam cada relatório, corrigem e revisam a correção
4. Modo automático para que a rotina seja executada sem parar para pedir permissão

Juntando tudo, um comando poderia ser assim:

1/schedule a cada hora: verifique o canal project-feedback em busca de relatórios de bugs. /goal: não pare até que cada relatório encontrado nesta execução seja triado, resolvido e respondido. Ao corrigir um bug, use um fluxo de trabalho para explorar três soluções em árvores de trabalho paralelas e tenha um juiz que as revise adversarialmente.

Mantendo a qualidade do código

A qualidade da saída de um loop depende do sistema ao seu redor. Ao projetar o sistema:

• Mantenha o próprio código limpo: Claude segue padrões e convenções que já existem em sua base de código.
• Dê a Claude uma maneira de verificar seu próprio trabalho: Codifique o que é bom para você e sua equipe com habilidades.
• Torne a documentação facilmente acessível: A documentação de frameworks e bibliotecas tem práticas recomendadas atualizadas.
• Use um segundo agente para revisões de código: Um revisor com contexto novo é menos tendencioso e não é influenciado pelo raciocínio do agente principal. Você pode usar a habilidade integrada /code-review ou Code Review para Github.

Quando um resultado individual não atende ao padrão, não pare apenas de corrigir o problema individual, tente codificá-lo para melhorar o sistema para todas as iterações futuras.

Gerenciando o uso de tokens

Para gerenciar o uso de tokens, os loops devem ter limites claros:

• Escolha a primitiva e o modelo certos para o trabalho: Tarefas menores não precisam de vários agentes ou loops. Algumas tarefas podem usar modelos mais baratos e rápidos.
• Defina critérios claros de sucesso e parada: Seja específico sobre como é a conclusão para que Claude possa chegar à solução mais cedo (mas não cedo demais).
• Pilote antes de uma execução grande: Fluxos de trabalho dinâmicos podem gerar centenas de agentes. Avalie o uso em uma fatia menor do trabalho primeiro.
• Use scripts para trabalho determinístico: Executar um script é mais barato do que raciocinar sobre as etapas. Por exemplo, uma habilidade de PDF pode fornecer um script de preenchimento de formulário que Claude executa a cada vez, em vez de redescobrir o código.
• Não execute rotinas com mais frequência do que o necessário: Combine o intervalo com a frequência com que a coisa que você está monitorando muda.
• Revise o uso: O comando /usage detalha o uso recente por habilidades, subagentes e MCPs, /goal sem argumentos mostra o número de turnos e o uso de tokens até agora, /workflows mostra o uso de tokens de cada agente e você pode parar um agente a qualquer momento.

Começando

Para resumir:

Loop

Você delega

Use quando

Recorra a

Baseado em turnos

A verificação

Você está explorando ou decidindo

Habilidades de verificação personalizadas

Baseado em meta

A condição de parada

Você sabe como é a conclusão

/goal

Baseado em tempo

O gatilho

O trabalho acontece fora do seu projeto em um cronograma

/loop

,

/schedule

Proativo

O comando

O trabalho é recorrente e bem definido

Tudo acima e fluxos de trabalho dinâmicos

Para começar com loops, observe o trabalho que você já faz. Escolha uma tarefa onde você é o gargalo e pergunte qual parte você poderia delegar: você pode escrever a verificação? A meta é clara o suficiente? O trabalho chega em um cronograma?

Depois de ter uma ideia, execute o loop, observe os resultados, como onde ele trava ou exagera, e não tenha medo de iterar.

Para mais informações, leia a documentação do Claude Code sobre execução de agentes em paralelo, bem como as páginas sobre loop, schedule, goal e fluxos de trabalho dinâmicos.

Este artigo foi escrito por @delba_oliveira