Começando com loops

• Em vez de instruir um agente de codificação a cada prompt, a operação de agentes está migrando para um padrão em que um ciclo de trabalho se repete até que uma condição de parada seja satisfeita
• A equipe do Claude Code classifica loops por quatro critérios: forma de acionamento, forma de parada, primitives usadas e tipos de tarefa adequados
• Os principais tipos de loop são quatro: Turn-based, Goal-based, Time-based e Proactive
• Nem toda tarefa precisa de loops complexos; comece pela solução mais simples e aplique padrões seletivamente
• A qualidade da saída de loops depende dos sistemas ao redor, portanto manter a qualidade do código e gerenciar o uso de tokens é essencial

---

Definição de loops e critérios de classificação

• A equipe do Claude Code define loop como um agente que repete um ciclo de trabalho até que uma condição de parada seja satisfeita
• Apresenta quatro critérios para classificar loops
  • Como é acionado
  • Como é interrompido
  • Quais primitives do Claude Code usa
  • Para que tipo de tarefa é mais adequado
• Loops complexos nem sempre são necessários; priorize soluções simples primeiro e depois use padrões seletivamente

Loop Turn-based

• É acionado por um prompt do usuário e para quando o Claude julga que a tarefa foi concluída ou quando precisa de mais contexto
• Adequado para tarefas curtas que não fazem parte de um processo regular ou de uma agenda
• A forma de gerenciamento é reduzir o número de turnos por meio de prompts específicos e melhoria da verificação usando skills
• Todo prompt inicia um loop manual em que o usuário direciona cada turno; isso é chamado de agentic loop
  • O Claude coleta contexto → executa ações → verifica a tarefa → repete se necessário → responde
  • Ex.: ao pedir a criação de um botão de like, ele lê o código, edita, executa testes e retorna o resultado; depois o usuário verifica manualmente e escreve o próximo prompt
• A etapa de verificação pode ampliar o escopo de autocheck do Claude ao codificar procedimentos manuais em SKILL.md
  • É necessário incluir ferramentas e conectores para visualizar, medir ou interagir com o resultado
  • Quanto mais quantitativa for a verificação, mais fácil é a autoverificação

• Exemplo de SKILL.md (verify-frontend-change)

  • Regra para verificar de ponta a ponta uma alteração de UI antes de declará-la concluída
  • Não relatar conclusão apenas porque a edição deu certo; verificar como um revisor humano
    • Iniciar o servidor de dev e abrir a página editada no navegador
    • Interagir diretamente com os elementos alterados (clicar em botões, inputs, toggles), confirmar mudanças de estado e capturar screenshots antes/depois
    • Confirmar no console do navegador que há zero novos erros ou avisos
    • Executar um trace de performance com Chrome Devtools MCP e auditar Core Web Vitals
  • Se uma etapa falhar, corrigir e reexecutar a partir da etapa 1; não retornar em estado de verificação parcial

Loop Goal-based (/goal)

• É acionado por prompts manuais em tempo real e para quando o objetivo é atingido ou quando chega ao número máximo de turnos
• Adequado para tarefas com critérios de encerramento verificáveis
• A forma de gerenciamento é definir critérios de conclusão específicos e limites explícitos de turnos, como "parar após 5 tentativas"
• Em tarefas complexas em que um único turno não basta, o agente melhora o desempenho ao iterar (iterate)
• Ao definir o estado de conclusão com /goal, o Claude não encerra cedo por julgar sozinho que está "bom o suficiente"
  • Sempre que o Claude tenta parar, um modelo avaliador verifica as condições; ele retrabalha até atingir o objetivo ou alcançar o número de turnos especificado
  • Critérios determinísticos, como número de testes passando ou um limiar específico de pontuação, funcionam bem
• Exemplo
  • /goal get the homepage Lighthouse score to 90 or above, stop after 5 tries.

Loop Time-based (/loop e /schedule)

• É acionado em intervalos de tempo especificados e para quando o usuário cancela ou quando a tarefa é concluída (merge de PR, fila vazia)
• Adequado para tarefas recorrentes ou interfaces com ambientes e sistemas externos
• A forma de gerenciamento é usar intervalos mais longos ou reagir com base em eventos, não em tempo
• Algumas tarefas agentic são repetitivas: a tarefa é a mesma e só a entrada muda, como resumir mensagens do Slack todas as manhãs
• Tarefas dependentes de sistemas externos fazem interface verificando a cada intervalo e reagindo a mudanças, como um PR que recebe code review ou falha no CI
• /loop reexecuta o prompt a cada intervalo
  • /loop 5m check my PR, address review comments, and fix failing CI
• /loop roda no computador do usuário e para ao encerrar; com /schedule, é possível criar uma routine e migrá-la para a nuvem

Loop Proactive

• É acionado por eventos ou agenda sem intervenção humana em tempo real
• Cada tarefa termina quando o objetivo é atingido; a routine em si continua até o usuário desligá-la
• Adequado para fluxos de trabalho repetitivos e bem definidos, como relatórios de bug, triagem de issues, migrações e upgrades de dependências
• A forma de gerenciamento é rotear a routine para modelos menores e mais rápidos, usando o modelo mais poderoso apenas nas partes que exigem julgamento
• Combina as primitives acima com auto mode, dynamic workflows (research preview) etc. para compor loops de longa duração

• Exemplo de configuração para tratamento de feedback

  • Executar uma routine para verificar novos relatórios com /schedule (research preview)
  • Definir conclusão com /goal e documentar métodos de verificação com skills
  • Orquestrar agentes de classificação, correção e revisão para cada relatório com Dynamic workflows
  • Executar a routine sem confirmação de permissões com Auto mode
  • Exemplo de prompt integrado: /schedule every hour: check the project-feedback channel for bug reports. /goal: don't stop until every report found this run is triaged, actioned, and responded to. When fixing a bug, use a workflow to explore three solutions in parallel worktrees and have a judge adversarially review them.

Manter a qualidade do código

• A qualidade da saída de loops depende dos sistemas ao redor, por isso o design do sistema é importante
• Manter a base de código limpa: o Claude segue os padrões e convenções da base de código existente
• Fornecer meios de autoverificação: codificar nos skills os critérios da equipe para um "bom estado"
• Facilitar o acesso à documentação: a documentação de frameworks e bibliotecas contém as best practices mais recentes
• Usar um segundo agente para code review: um revisor com contexto novo tem menos viés e não é influenciado pelo raciocínio do agente principal; use o skill integrado /code-review ou Code Review para Github
• Quando resultados individuais ficam abaixo do padrão, não se limite a corrigir issues isoladas; codifique melhorias no próprio sistema

Gerenciar o uso de tokens

• Loops devem ter fronteiras claras e seguir os princípios abaixo
• Escolher a primitive e o modelo adequados: tarefas pequenas não precisam de múltiplos agentes ou loops; algumas tarefas podem usar modelos mais baratos e rápidos
• Definir critérios claros de sucesso e parada: especificar o estado de conclusão para evitar chegar cedo demais a um encerramento
• Fazer um piloto antes de execuções em grande escala: dynamic workflows podem criar centenas de agentes; meça o uso primeiro em um escopo pequeno
• Usar scripts para tarefas determinísticas: executar scripts é mais barato do que inferir etapas; por exemplo, um PDF skill fornece um script para preencher formulários em vez de regenerar código toda vez
• Não executar routines mais do que o necessário: alinhar o intervalo à frequência de mudança do que está sendo monitorado
• Revisar o uso: /usage analisa uso por skills, subagents e MCPs; /goal sem argumentos mostra o número atual de turnos e uso de tokens; /workflows mostra o uso de tokens de cada agente e permite interromper a qualquer momento

Como começar

• Resumo por tipo de loop
  • Turn-based: delega a verificação (check), usado para exploração e decisão, aproveita skills de verificação customizados
  • Goal-based: delega a condição de parada, usado quando se conhece o estado de conclusão, utiliza /goal
  • Time-based: delega o acionamento, usado quando o trabalho surge por agenda fora do projeto, utiliza /loop e /schedule
  • Proactive: delega o prompt, usado para tarefas repetitivas e bem definidas, utiliza tudo acima e dynamic workflows
• Para começar, observe o trabalho que você já faz e escolha uma tarefa em que você é o gargalo, avaliando que partes podem ser delegadas
  • É possível escrever checks de verificação?
  • O objetivo está suficientemente claro?
  • A tarefa chega por uma agenda?
• Quando surgir uma ideia, execute um loop e observe onde ele trava ou roda em excesso; não tenha medo de melhorar iterativamente