---
title: "Guia de Claude Code Loop Engineering: 4 Loops e design de automação segura"
locale: pt
category: tutorial
category_name: "Tutorial"
translation_status: machine
license: cc_by
author: "Injoys Admin"
source_url: https://injoys.com/en/articles/claude-code-loop-engineering-guide
published_at: 2026-07-17T09:40:17+09:00
---

# Guia de Claude Code Loop Engineering: 4 Loops e design de automação segura

> O Loop do Claude Code é uma estrutura de controle que faz o agente repetir observação, ação e verificação até uma condição de encerramento. Explica as diferenças entre os quatro tipos de Loop e métodos práticos de design que incluem evidências de verificação, hard stop, idempotência, custos e privilégio mínimo.

## Key Points

- O Loop do Claude Code não é um loop de código, mas uma estrutura de execução de agente que repete observação, ação e verificação até uma condição de encerramento.
- Turn-based transfere o procedimento de verificação; Goal-based, o julgamento de encerramento; Time-based, o momento de reexecução; e Proactive transfere o início da tarefa e a orquestração ao sistema.
- Um bom Loop deve ter condições de conclusão mensuráveis, evidências externas de verificação, encerramento forçado, idempotência e privilégio mínimo.
- O modelo de avaliação `/goal` julga apenas as evidências expostas na conversa, portanto é preciso relatar claramente a saída dos testes, o código de encerramento e o escopo das alterações.
- Transformações determinísticas devem ser tratadas por Script, e Dynamic Workflow e múltiplos agentes só devem ser aplicados a trabalhos de grande escala que realmente exijam paralelismo.

O Loop do Claude Code não é simplesmente um recurso para executar o modelo por mais tempo. O ponto central está em posicionar **Trigger, Verifier, Success condition, Hard stop, Permission boundary** ao redor de um AI Agent que age probabilisticamente, transformando tarefas repetitivas em um sistema controlável. Este artigo organiza de uma só vez as diferenças entre Turn-based, Goal-based, Time-based e Proactive Loop, além dos princípios de design prático.

## 1. O que é Loop no Claude Code

Aqui, Loop não é uma instrução `for` ou `while` de uma linguagem de programação. O Loop descrito pela equipe do Claude Code é uma estrutura de execução em que o Agent observa o estado atual, age, verifica o resultado e volta a trabalhar até que a condição de encerramento seja satisfeita.

```text
Início da tarefa
  ↓
Entendimento do estado e do código
  ↓
Elaboração do plano
  ↓
Alteração de código ou execução de ferramenta
  ↓
Teste·verificação
  ↓
Condição de conclusão satisfeita?
  ├─ Não: próxima iteração
  └─ Sim: encerrar e relatar resultado
```

Ao distinguir Loops, as quatro perguntas a seguir são úteis.

1. O que inicia a tarefa?
2. O que encerra a tarefa?
3. Qual recurso do Claude Code controla a repetição?
4. Para que tipo de tarefa ele é adequado?

Não é necessário transformar todo trabalho em um Loop complexo. Para tarefas cujo resultado pode ser confirmado imediatamente, como corrigir um erro de digitação em um arquivo ou fazer uma simples mudança de nome, um prompt comum é mais eficiente. Loop deve ser escolhido apenas quando várias rodadas de observação·correção·verificação forem realmente necessárias.

## 2. Comparação entre quatro tipos de Loop

| Tipo | Condição de início | Condição de encerramento | Recursos usados principalmente | Tarefas adequadas | Responsabilidade transferida pela pessoa |
|---|---|---|---|---|---|
| Turn-based | Prompt do usuário | Quando Claude julga que concluiu ou precisa de informações adicionais | Conversa comum, Skills, ferramentas de teste·navegador | Implementações·correções curtas e pontuais | Procedimento de verificação repetida |
| Goal-based | Usuário especifica a condição de conclusão | Modelo avaliador confirma o cumprimento da condição ou usuário interrompe | `/goal`, Auto mode se necessário | Tarefas com estado de conclusão mensurável, como testes·build·migração | Julgamento de encerramento |
| Time-based | Horário·intervalo·agenda definidos | Usuário cancela ou uma tarefa externa termina | `/loop`, `/schedule` | Monitoramento de PR·CI·deploy, resumo periódico, Polling de status | Próximo momento de execução |
| Proactive | Agenda, API, eventos do GitHub etc. | Cumprimento do objetivo da tarefa individual, desativação da Routine | Routines, `/goal`, Skills, Dynamic Workflows, Auto mode | Trabalho contínuo como classificação de issues, tratamento de bugs, migração em larga escala | Descoberta de tarefas, execução de prompts, orquestração |

O ponto central dessa classificação não é “quão inteligente é a AI”, mas **qual responsabilidade de controle a pessoa transfere ao sistema**. No Turn-based, a pessoa cria o próximo prompt; no Goal-based, transfere o julgamento de conclusão; no Time-based, transfere o momento de reexecução. Na etapa Proactive, até a responsabilidade de detectar o surgimento de tarefas e executar o prompt adequado passa para o sistema.

## 3. Turn-based Loop: transferir o procedimento de verificação

Turn-based Loop é a forma básica como a maioria dos desenvolvedores usa o Claude Code.

```text
Human → Claude → Human → Claude
```

Quando o usuário faz uma solicitação, Claude encontra arquivos relacionados, modifica o código, testa e relata o resultado. Internamente, várias observações·ações·verificações podem ocorrer, mas a autoridade para iniciar a próxima tarefa permanece com o usuário.

### Alterar código e completar uma funcionalidade são coisas diferentes

Mesmo que Claude relate que “concluiu a implementação e os testes”, os seguintes problemas podem permanecer no produto real.

- O estado não muda após clicar no botão.
- Ocorrem erros no console do navegador.
- O layout mobile quebra.
- Atributos de acessibilidade estão ausentes.
- Os testes passam, mas o fluxo real no navegador falha.
- Arquivos não relacionados à mudança também foram modificados.

Portanto, o critério de conclusão não deve ser “o código foi alterado”, mas “o funcionamento foi confirmado por evidência externa”.

### Reutilizar a verificação com `SKILL.md`

Skill é uma forma de armazenar instruções e procedimentos usados repetidamente em `SKILL.md`. Claude pode carregá-la automaticamente ao julgar que há relevância, ou ela pode ser executada diretamente com `/skill-name`. Em vez de colocar sempre procedimentos operacionais longos em `CLAUDE.md`, separar para carregar a Skill apenas no momento necessário permite usar o contexto de forma mais eficiente.

```markdown
---
name: verify-ui-change
description: Verifica a alteração de UI no ambiente real de execução antes de marcá-la como concluída.
---

# Verificação de alteração de UI

1. Execute o servidor de desenvolvimento.
2. Abra a tela alterada no navegador.
3. Interaja de fato com o novo controle.
4. Confirme se a mudança de estado esperada ocorre.
5. Verifique novos erros e avisos no console do navegador.
6. Verifique acessibilidade e principais indicadores de desempenho.
7. Se falhar, corrija e verifique novamente desde o início.
8. Relate evidências como comandos executados, resultados e screenshots.
```

Uma boa Skill contém uma checklist executável, não recomendações abstratas. “Revisar com mais cuidado” é uma regra muito mais fraca do que “confirmar que `npm test` termina com código de saída 0”.

### Força das evidências de verificação

| Evidência | Confiabilidade | Motivo |
|---|---:|---|
| Explicação do Agent dizendo “parece estar normal” | Baixa | É apenas inferência, não resultado de execução |
| Diff de código e revisão estática | Média | As mudanças são visíveis, mas o comportamento em Runtime não é confirmado |
| Saída real de testes e código de saída | Alta | Existe resultado externo reproduzível |
| Interação no navegador, screenshots, resultados de console·desempenho | Muito alta | Verifica diretamente o caminho do usuário e o estado em Runtime |
| Review Agent independente e CI chegam à mesma conclusão | Muito alta | Reduz o viés de auto-confirmação do Agent implementador |

A documentação oficial do Claude Code também descreve bundled Skills como `/run`, para verificar uma aplicação em execução, e `/verify`, para validar mudanças no ambiente real de execução. Se a forma de executar o projeto for complexa, é mais seguro registrar em uma Skill própria da equipe os comandos exatos de inicialização, variáveis de ambiente e procedimentos de preparação de dados.

## 4. Goal-based Loop: transferir o julgamento de encerramento

Goal-based Loop não exige que o usuário decida a cada vez “se deve trabalhar mais uma vez”. O usuário define o estado de conclusão, e Claude continua por vários Turns até que essa condição seja satisfeita.

```text
Usuário define Goal
  ↓
Turn de trabalho do Claude
  ↓
Modelo avaliador separado verifica a condição de conclusão
  ├─ Não satisfeita: transmite o motivo ao próximo Turn
  └─ Satisfeita: encerra o Goal
```

`/goal` está documentado como disponível no Claude Code v2.1.139 ou superior. Apenas um Goal pode estar ativo em uma sessão.

### O que o modelo avaliador realmente vê

Ao fim de cada Turn, um small fast model separado avalia a condição de conclusão e o conteúdo da conversa, julgando como `satisfeita` ou `não satisfeita`. A configuração padrão é um modelo avaliador da família Haiku. Uma limitação importante é que o modelo avaliador não lê arquivos diretamente nem executa testes separadamente.

Portanto, o Claude que executou a tarefa deve deixar claramente na conversa as seguintes evidências.

- Comandos executados
- Número de testes e resultados de aprovação·falha
- Código de saída
- Resultado do build
- Lista de arquivos alterados
- Causas de falhas restantes
- Resultado da confirmação de que as restrições de escopo foram respeitadas

O modelo avaliador julga não “o que realmente aconteceu”, mas “quais evidências aparecem na conversa”.

### Quatro elementos de um bom Goal

Um bom Goal inclui os quatro elementos a seguir.

1. **Condição de sucesso mensurável**: testes passando, build bem-sucedido, fila vazia, alcance de limiar de pontuação
2. **Método de verificação**: especificar com qual comando ou ferramenta o sucesso será comprovado
3. **Restrição de escopo de mudança**: diretórios modificáveis, arquivos proibidos, Side effect permitido
4. **Condição de encerramento forçado**: máximo de Turns, tempo máximo, número de falhas consecutivas, interrupção em caso de erro de permissão

```text
/goal todos os testes relacionados a auth e o lint devem ter sucesso,
e o git diff deve incluir apenas src/auth e arquivos de teste relacionados.
Em cada Turn, relatar o resultado da execução e o código de saída.
Interromper ao atingir no máximo 12 turns ou 45 minutos e resumir as falhas restantes.
```

As principais condições de encerramento do próprio `/goal` são o julgamento de sucesso do modelo avaliador ou o `/goal clear` do usuário. Para impor limite de Turn·tempo, isso deve ser explicitado dentro da condição do Goal.

### Condições boas e ruins

| Boa condição | Má condição |
|---|---|
| `npm test` termina com código de saída 0 | Tornar o código perfeito |
| Todos os 48 testes relacionados a autenticação passam | Melhorar ao máximo a experiência do usuário |
| Todos os pontos de chamada de API são alterados para a nova interface e o build tem sucesso | Refatorar para uma estrutura melhor |
| A fila de issues alvo fica vazia e o resultado é registrado em cada issue | Processar o maior número possível de issues |

Objetivos ambíguos podem encerrar cedo demais ou repetir melhorias indefinidamente.

### Verificação de status e interrupção

- `/goal`: confirmar condição ativa, tempo de execução, número de Turns avaliados, uso de tokens, motivo da avaliação recente
- `/goal clear`: interromper Goal ativo
- Definir novo Goal: substituir o Goal existente
- `--resume` ou `--continue`: permite restaurar Goal incompleto

Ao retomar, as condições são mantidas, mas o número de Turns, tempo e linha de base de tokens podem ser reinicializados; por isso, é recomendável gerenciar Hard stop junto com métricas operacionais.

### `/goal` e permissões são coisas separadas

`/goal` apenas inicia automaticamente o próximo Turn, não amplia permissões de ferramentas. Se escrita de arquivos, comandos de teste ou operações Git exigirem aprovação, a aprovação ainda pode ser necessária durante o Goal.

Para execução não assistida, é possível usar Auto mode em conjunto, mas Auto mode não é um recurso que “permite incondicionalmente todas as ferramentas”. O classificador bloqueia operações destrutivas, difíceis de reverter ou direcionadas para fora da fronteira de confiança, e regras explícitas de `ask` e `deny` são aplicadas antes do classificador.

## 5. Time-based Loop: transferir o momento de reexecução

Se o Goal-based Loop trata de “quando parar”, o Time-based Loop trata de “quando executar novamente”. Ele é adequado para tarefas em que o estado de sistemas externos muda com o passar do tempo.

- Verificar se há novas reviews em um PR
- Verificar se CI ou deploy terminou
- Verificar status de build de longa duração
- Resumir mensagens do Slack diariamente
- Verificar novos itens em uma fila de issues

### `/loop`: execução repetida dentro da sessão atual

```text
/loop 10m verificar o PR atual, incorporar novas reviews,
e se houver CI com falha, analisar a causa e corrigir.
```

As principais formas descritas na documentação atual são as seguintes.

| Entrada | Comportamento |
|---|---|
| `/loop 5m <prompt>` | Executa o Prompt em um intervalo fixo especificado |
| `/loop <prompt>` | Claude escolhe o intervalo a cada repetição |
| `/loop` | Executa o Prompt built-in de manutenção ou o `loop.md` do projeto |
| `/loop 20m /review-pr 1234` | Reexecuta uma Skill permitida no intervalo especificado |

`/loop` depende da sessão atual do Claude Code. O computador e a sessão precisam estar em execução, e ao iniciar uma nova conversa as tarefas no escopo da sessão desaparecem. Tarefas não expiradas podem ser restauradas com `--resume` ou `--continue`, mas tarefas repetitivas expiram por padrão 7 dias após a criação. Ciclos perdidos também não são executados retroativamente.

Como Jitter pode ser aplicado ao Scheduler da sessão, ele pode não ser adequado para requisitos operacionais que precisam “executar obrigatoriamente no horário exato”.

### `/schedule`: Cloud Routine gerenciada pela Anthropic

`/schedule` cria uma Routine que combina Prompt, Repository, Connector e Trigger para execução na infraestrutura gerenciada pela Anthropic. Ela pode executar mesmo com o notebook fechado, e a documentação oficial a apresenta como Research Preview.

Os Triggers suportados por Routine são os seguintes.

- Agenda repetida
- Agenda única em um momento futuro específico
- Chamada de API autenticada
- Evento de GitHub Pull request ou Release

Vários Triggers podem ser conectados a uma única Routine. Por exemplo, uma PR Review Routine pode rodar todas as noites e também reagir ao evento `pull_request.opened`.

### Comparação entre `/loop` e `/schedule`

| Categoria | `/loop` | `/schedule` Routine |
|---|---|---|
| Local de execução | Computador e sessão atuais | Cloud gerenciada pela Anthropic |
| Execução após desligar o computador | Geralmente não disponível | Disponível |
| Sessão aberta necessária | Necessária | Desnecessária |
| Arquivos locais não commitados | Acessíveis | Inacessíveis, Repository é clonado novamente a cada execução |
| Intervalo mínimo | 1 minuto segundo a documentação oficial | 1 hora segundo a documentação oficial |
| Persistência | Centrado na sessão, tarefas repetitivas expiram em 7 dias | Routine salva na conta |
| Prompt de permissão | Herda a política da sessão atual | Execução autônoma sem aprovação interativa |
| Uso adequado | Monitoramento curto de PR·deploy | Automação operacional contínua |

### Quando Event é melhor que Polling

Se um PR com poucas alterações for verificado a cada 1 minuto, a maioria das execuções terminará sem fazer nada. Se o sistema externo puder enviar eventos, a estrutura abaixo é mais eficiente.

```text
Falha de CI ou atualização de PR
  ↓
GitHub Trigger ou Routine API
  ↓
Executar Claude apenas quando necessário
```

O design baseado em Event reduz atrasos e diminui chamadas desnecessárias ao modelo e consumo de tokens. Quando Polling for inevitável, é recomendável aumentar o intervalo de acordo com a frequência real de mudanças e aplicar Backoff quando não houver mudanças por longo período.

### Condições obrigatórias de tarefas baseadas em tempo

1. **Idempotência**: mesmo recebendo o mesmo evento várias vezes, não devem surgir comentários duplicados, PRs duplicados ou deploys duplicados.
2. **Estado de processamento**: deve-se registrar o último Event ID, Commit SHA, Review Comment ID etc.
3. **Estado de encerramento**: deve ser possível determinar encerramento, como PR merge·close, Queue empty, Deploy success·rollback.
4. **Escopo de escrita**: Side effects devem ser limitados, como permitir comentários, proibir Merge, fazer Push apenas em Branch `claude/*`.
5. **Tratamento de falhas**: são necessárias regras de retentativa e Escalation em caso de falha de serviço externo, expiração de autenticação, Rate limit ou falta de permissão.

## 6. Proactive Loop: transferir descoberta de tarefas e orquestração

Proactive Loop não é um único comando, mas uma arquitetura de automação contínua que combina vários recursos.

```text
Trigger
+ Goal
+ Skills
+ Dynamic Workflow
+ Auto mode
+ Repository·Connector·Browser·CI ferramentas
```

Mesmo sem uma pessoa digitando prompts em tempo real, novas tarefas são detectadas, processadas, verificadas e relatadas.

### Exemplo: tratamento automático de feedback de bugs

```text
Receber GitHub Issue ou feedback no Slack
  ↓
Classificar duplicidade·prioridade·reprodutibilidade
  ↓
Criar teste de reprodução
  ↓
Explorar soluções candidatas
  ↓
Implementar a solução escolhida
  ↓
Review Agent independente procura contraexemplos
  ↓
Verificações de teste·build·segurança
  ↓
Draft PR e relatório de resultado
```

As responsabilidades por componente são as seguintes.

| Componente | Responsabilidade |
|---|---|
| Trigger ou `/schedule` | Determinar quando iniciar uma nova tarefa |
| `/goal` | Definir o que é estado de conclusão nesta execução |
| Skill | Padronizar procedimentos de reprodução, implementação, verificação e relatório |
| Dynamic Workflow | Execução paralela e ramificação condicional de múltiplos Subagents |
| Auto mode | Executar chamadas de ferramentas permitidas sem esperar aprovação |
| Permission policy | Fixar escopos de proibição·aprovação·permissão automática |

### Dynamic Workflow e Worktree

Dynamic Workflow é uma estrutura em que o Runtime executa um Script de orquestração JavaScript escrito por Claude. Em chamadas comuns de Subagent, Claude escolhe o próximo Agent a cada Turn; em Workflow, Loop, processamento paralelo, ramificação e armazenamento de resultados intermediários passam para o Script.

```text
Workflow Script
  ├─ Agent A: análise de requisitos
  ├─ Agent B: design de testes
  ├─ Agent C: exploração de candidatos de implementação
  ├─ Agent D: revisão de segurança
  └─ Judge: comparação baseada em evidências
```

Como os resultados intermediários ficam em variáveis do Script, e não no Context da conversa principal, tarefas em grande escala podem ser organizadas de forma mais reproduzível. A documentação atual especifica limites de Runtime de até 16 Agents simultâneos e até 1,000 Agents por execução, mas limitações em estágio de produto Preview podem mudar.

Se for necessário testar vários candidatos de implementação ao mesmo tempo, é possível separar os espaços de trabalho com Git Worktree.

```text
repo/
worktree-solution-a/
worktree-solution-b/
worktree-solution-c/
```

Quando cada Agent trabalha em uma Branch e diretório independentes, é possível reduzir problemas de sobrescrever os mesmos arquivos simultaneamente. O Judge Agent deve comparar os candidatos com base em cumprimento dos requisitos, resultados de testes, risco de regressão, escopo de mudança, complexidade, desempenho, segurança e consistência com a arquitetura existente.

### Mais Agents nem sempre é melhor

Se apenas aumentar o número de Agents em uma tarefa sem paralelismo, o custo e a latência aumentam. Se vários Agents compartilharem a mesma suposição incorreta, o erro também pode ser ampliado.

Dynamic Workflow é adequado nos seguintes casos.

- Migration aplicando a mesma transformação a centenas de arquivos
- Audit de segurança·qualidade em toda a base de código
- Comparação de Plans sob várias perspectivas independentes
- Research que exige dividir muitos itens e fazer verificação cruzada
- Tarefas em que é difícil colocar todos os resultados intermediários no Context de um único Agent

Para pequenas correções de bug, refatoração de um arquivo ou adição simples de testes, um Turn-based Loop comum ou `/goal` é melhor.

## 7. Sistema para manter a qualidade do código em Loop

A qualidade dos resultados de Loop depende fortemente não apenas do modelo em si, mas também do sistema de verificação ao redor do modelo.

### 7.1 Organizar a base de código

Claude segue fortemente os padrões do código existente. Se houver APIs antigas, implementações duplicadas, estrutura de testes pouco clara, módulos enormes ou regras inconsistentes de tratamento de exceções, o Loop pode replicar rapidamente esses problemas.

As bases essenciais são as seguintes.

- Formatter e lint
- Limites claros de diretórios e módulos
- Unit·Integration·E2E Test confiáveis
- Distinção entre APIs em uso e Deprecated APIs
- Regras de desenvolvimento específicas do projeto
- Ambiente Build·Dev reproduzível

### 7.2 Criar Definition of Done por tipo de mudança

| Tipo de mudança | Verificação mínima |
|---|---|
| API | Testes de contrato, compatibilidade retroativa, atualização de exemplos de Schema·documentação |
| Frontend | Interação real no navegador, erros de console, acessibilidade, telas responsivas |
| Database | Forward·Rollback Migration, escopo de Lock, plano de execução |
| Dependency | Build, principais testes de regressão, verificação de License·Security |
| Infrastructure | Plan Diff, privilégio mínimo, Rollback, verificação de exposição de segredos |

É melhor fixar esses critérios em Skill, Hook, Script ou CI Rule do que repeti-los longamente em cada Prompt.

### 7.3 Fornecer documentação atualizada e versões exatas

Loop pode repetir suposições incorretas várias vezes. É preciso facilitar a localização da Version exata usada no projeto, documentação oficial, documentos internos de Architecture, especificações de API, Migration Guide e exemplos aprovados.

### 7.4 Separar Agent implementador e Review Agent

O Agent que implementou já é influenciado pelo design e pelo raciocínio que escolheu. Um Review Agent em novo Context pode fazer as seguintes perguntas de forma mais independente.

- Os testes foram enfraquecidos para fazê-los passar?
- Arquivos fora do escopo foram alterados?
- A fronteira de segurança foi quebrada?
- Caminhos de falha e testes de valores-limite ficaram de fora?
- Houve regressão em funcionalidades existentes?

É mais eficaz escrever o Review Prompt como “assuma que a implementação está errada, encontre contraexemplos e anexe evidência de reprodução a cada apontamento” do que “resuma os pontos positivos”.

### 7.5 Conectar falhas individuais a melhorias de sistema

Se o mesmo erro se repete, não basta corrigir apenas aquele resultado. É preciso alterar um dos itens abaixo para dificultar a recorrência do tipo de falha.

- Adicionar Regression Test
- Reforçar o procedimento de verificação da Skill
- Adicionar regra em `CLAUDE.md`
- Adicionar Hook ou lint Rule
- Adicionar regra Deny de permissão
- Reforçar a condição de conclusão do Goal
- Complementar a Review Checklist

Boa Loop Engineering não é o trabalho de corrigir uma falha uma vez, mas **criar um sistema em que esse tipo de falha tenha dificuldade de reaparecer**.

## 8. Gerenciamento de Token e custo

O custo de Loop pode aumentar bastante em relação a um único Prompt.

```text
Custo total ≈
custo dos Turns do Agent principal
+ custo de avaliação do Goal
+ custo de Subagent
+ custo de repetição de Workflow
+ custo de Context para ler resultados de ferramentas
+ frequência de execução baseada em tempo
```

A cobrança exata varia conforme Plan, Model e Provider, mas os princípios que determinam a estrutura de custo são os mesmos.

### Princípios práticos para reduzir custo

1. **Não usar Loop para tarefas pequenas.** Erros de digitação, mudanças de nome e erros de tipo em um arquivo devem ser tratados em um único Turn.
2. **Usar condição de sucesso junto com Hard stop.** Considerar sucesso, máximo de Turns, tempo máximo, falhas consecutivas e erros de permissão.
3. **Testar Workflows grandes em escopo pequeno.** Validar custo e qualidade em 5 arquivos, um diretório ou algumas Issues antes de expandir.
4. **Tratar tarefas determinísticas com Script.** Substituições AST, conversões JSON, Formatting e geração de formatos fixos são mais baratos e reproduzíveis com Scripts verificados.
5. **Ajustar o ciclo de Polling à frequência real de mudanças.** Usar Event Trigger sempre que possível.
6. **Observar o uso em andamento.** Verificar uso de Skill·Subagent·MCP·Turn·Token em `/usage`, `/goal`, `/workflows`.
7. **Não continuar tentando quando o mesmo erro se repete.** Definir limite de falhas consecutivas e fazer Escalation para uma pessoa.

### Model e Effort são alavancas diferentes

- **Model** altera a capacidade básica de raciocínio e o escopo dos problemas solucionáveis.
- **Effort** altera o número de arquivos lidos, o número de ferramentas usadas, a amplitude da verificação e até que ponto tarefas de várias etapas são levadas adiante.

Se Claude confirmou todos os arquivos e testes necessários, mas o julgamento em si continua errado, pode ser necessário um Model mais forte. Por outro lado, se arquivos importantes não são lidos, testes são pulados ou a refatoração termina no meio, aumentar Effort pode ser mais apropriado.

## 9. Permissões e fronteiras de segurança

O design mais perigoso em Proactive Loop é conceder permissões amplas ao Agent e deixar frouxas as condições de sucesso e interrupção.

Auto mode reduz Prompts comuns de permissão, mas Tool calls difíceis de reverter, destrutivas ou direcionadas para fora da fronteira de confiança podem ser bloqueadas pelo classificador. Além disso, `permissions.ask` e `permissions.deny` explícitos têm prioridade sobre Auto mode.

### Exemplo de camadas de permissão

| Nível | Exemplo |
|---|---|
| Permitir automaticamente | Leitura de código, testes·lint·Build, análise, criação de Branch `claude/*`, criação de Draft PR |
| Aprovação humana | Aplicar em Default Branch, deploy em produção, aplicar DB Migration, enviar mensagens externas a clientes |
| Sempre proibido | Force push, saída de Secret, exclusão de dados de produção, bypass de permissões, remoção de logs de auditoria |

É mais seguro fixar em Rules permanentes de `ask`·`deny` do que dizer uma vez na conversa “não faça Push”. Isso porque regras da conversa podem enfraquecer com compressão de Context ou mudança de sessão.

Cloud Routine clona novamente o Repository a cada execução e opera com permissões conectadas de GitHub·Connector. Os seguintes escopos devem ser minimizados.

- Repository e Branch acessíveis
- Network Domain permitido
- Connector a usar
- Variáveis de ambiente e Secret
- Permissões de escrita em sistemas externos
- Escopo de criação de PR·Push·Merge

O estado “encerramento normal” na lista de execuções de Routine pode significar apenas que a Session terminou sem erro de Infrastructure, e não garante que o objetivo de negócio teve sucesso. Transcript, Test evidence e Diff gerado devem ser revisados separadamente.

## 10. Template de design de Loop para projetos de desenvolvimento

O YAML abaixo não é uma sintaxe real do Claude Code, mas um Template para revisão de design.

```yaml
trigger:
  type: manual | interval | schedule | github_event | api_event

scope:
  repositories:
    - target-repository
  allowed_paths:
    - src/**
    - tests/**
  prohibited_paths:
    - production/**
    - secrets/**

task:
  objective: objetivo a alterar ou processar
  input: Issue, Event, File ou estado recém-recebido

verification:
  commands:
    - unit-test
    - integration-test
    - lint
    - build
  runtime_checks:
    - browser-interaction
    - console-errors
    - accessibility
  evidence:
    - command-output
    - exit-code
    - test-summary
    - screenshots

success:
  condition: estado de conclusão que pode ser julgado como verdadeiro ou falso

stop:
  max_turns: 12
  max_duration_minutes: 45
  max_consecutive_failures: 3
  stop_on_permission_error: true
  escalate_on_external_outage: true

side_effects:
  idempotency_key: event-id-or-commit-sha
  allow_branch_push: claude/*
  require_human_for_merge: true
  require_human_for_deploy: true

review:
  independent_agent: true
  adversarial_review: true

observability:
  report_progress: true
  report_token_usage: true
  report_changed_files: true
  report_remaining_failures: true
```

Os itens mais importantes não são a frase do prompt em si, mas os cinco pontos a seguir.

```text
Trigger
Verifier
Success condition
Hard stop
Permission boundary
```

## 11. Qual Loop escolher

| Situação | Abordagem recomendada |
|---|---|
| Tarefa que termina com uma única correção e verificação | Turn-based |
| Tarefa que exige várias tentativas, mas tem estado de conclusão claro | `/goal` |
| Tarefa que precisa esperar por um tempo o estado de CI·PR·deploy externo | `/loop` |
| Trabalho que precisa executar repetidamente mesmo com o notebook fechado | `/schedule` Routine |
| Trabalho que precisa reagir imediatamente a eventos do GitHub ou Alert | Event-triggered Routine |
| Trabalho que exige processar centenas de itens em paralelo e fazer verificação cruzada | Dynamic Workflow |
| Transformação cujas regras de entrada e saída são totalmente determinísticas | Script ou CI Job |

A ordem de escolha deve se basear não no “recurso mais poderoso”, mas na “estrutura de controle mais simples que atinge o objetivo”.

## 12. Ordem segura de adoção

1. Escolha uma tarefa de gargalo que uma pessoa verifica repetidamente.
2. Primeiro, transforme o procedimento de verificação em Skill, Script e CI.
3. Estabilize a qualidade da verificação no modo Turn-based.
4. Se o estado de conclusão for claro, adicione `/goal`.
5. Use `/loop` apenas quando for necessário esperar um estado externo.
6. Se for necessária execução de longo prazo, mova para `/schedule` Routine.
7. Expanda para Dynamic Workflow e Proactive Loop apenas depois de verificar idempotência, permissões e custo.

## 13. Mal-entendidos frequentes

| Mal-entendido | Interpretação correta |
|---|---|
| Loop é execução infinita | É uma estrutura de repetição limitada com condição de sucesso e Hard stop |
| O relatório de conclusão do Agent é verificação | São necessários saída de comandos externos, código de saída e resultado em Runtime |
| `/goal` permite automaticamente todas as permissões | Ele apenas inicia automaticamente o próximo Turn; a política de permissões é separada |
| `/loop` é um Scheduler de operação de longo prazo | É centrado na sessão e tem expiração de 7 dias e restrições de ambiente de execução |
| Quanto mais Agents, melhor o resultado | A paralelização só tem valor quando papéis·perspectivas·verificações são diferentes |
| Toda tarefa repetitiva deve ser feita por LLM | Partes determinísticas são mais baratas e reproduzíveis com Script |

## Conclusão

Loop Engineering não é uma técnica para executar AI por mais tempo, mas o **design de um sistema de controle que faz a AI descobrir por si mesma quando erra, corrigir dentro de um limite de custo e parar em pontos perigosos**.

LLM é forte em exploração, raciocínio, implementação, análise de exceções e comparação de alternativas. O sistema deve cuidar do momento de execução, escopo de mudança, método de verificação, critério de encerramento, limite de custo e fronteira de aprovação. Quanto mais clara essa divisão de papéis, mais a automação do Claude Code deixa de ser uma simples ferramenta de geração de código e se aproxima de um sistema de operação de desenvolvimento reproduzível e auditável.

## FAQ

### Em que o Loop do Claude Code é diferente de laços de repetição comuns for·while?
Laços de repetição comuns repetem de forma determinística os comandos definidos no código. O Loop do Claude Code é uma estrutura de controle de agente em que o Agent observa o código e o estado externo, infere a próxima ação, executa ferramentas, valida o resultado e então volta a trabalhar conforme a condição de encerramento.

### Quando o Turn-based Loop é mais adequado?
Ele é adequado para tarefas curtas, pontuais, cujos resultados o usuário pode revisar imediatamente. Porém, se o procedimento de validação se repetir, como em UI·API·banco de dados, é melhor transformar esse procedimento em uma Skill ou Script para que Claude faça a própria validação usando os mesmos critérios.

### O modelo de avaliação de `/goal` verifica diretamente arquivos e resultados de testes?
Não. O modelo de avaliação não chama ferramentas nem lê arquivos diretamente; ele julga as condições do Goal e as evidências que aparecem na conversa. O Claude responsável pela tarefa deve deixar claramente no resultado o comando de teste, o código de saída, os arquivos alterados e a causa da falha.

### O que deve entrar em boas condições de `/goal`?
É necessário incluir um estado de conclusão mensurável, o comando ou a ferramenta que comprovará esse estado, o escopo que pode ser alterado e o escopo proibido, além de um Hard stop como máximo de Turn·tempo·falhas consecutivas. Uma condição como “testes e lint com código de saída 0 e sem Diff fora dos caminhos especificados” é melhor do que “refatorar de forma limpa”.

### `/goal` tem um máximo automático de Turn ou limite de tempo?
O Goal continua até que o modelo de avaliação determine o sucesso ou o usuário interrompa com `/goal clear`. Para limitar o orçamento de execução, é preciso incluir diretamente nas condições do Goal cláusulas de Turn·tempo, como “interromper após no máximo 12 turnos ou 45 minutos”.

### Ao usar `/goal`, as permissões de ferramentas também são autorizadas automaticamente?
Não. `/goal` inicia automaticamente o próximo Turn, mas as políticas de permissão para gravação de arquivos, Shell, Git e Connector externo permanecem as mesmas. Se precisar de execução sem supervisão, considere o Auto mode, mas controle separadamente as operações arriscadas com regras `ask`·`deny`.

### Qual é a maior diferença entre `/loop` e `/schedule`?
`/loop` é um meio de Polling de curto prazo que executa repetidamente na sessão atual do Claude Code e no computador atual. `/schedule` salva Prompt, Repository, Connector e Trigger como uma Cloud Routine e executa na infraestrutura gerenciada pela Anthropic, portanto não exige uma sessão aberta nem um notebook ligado.

### Se eu desligar o computador, `/loop` continua em execução?
Em geral, não continua em execução. `/loop` é uma tarefa no escopo da sessão e exige que o Claude Code esteja em execução. Para automações de longo prazo, é necessário usar um Scheduler sustentável, como Cloud Routine, Desktop scheduled task ou GitHub Actions.

### Por que Event Trigger é melhor do que Polling por tempo?
Porque não cria chamadas desnecessárias ao modelo quando não há mudanças e pode executar logo após uma alteração real. Para sistemas que podem emitir eventos, como falha de CI, atualização de PR ou Alert, conectá-los via GitHub Trigger ou Routine API é melhor tanto em custo quanto em latência.

### Por que colocar o procedimento de validação em `SKILL.md` em vez de `CLAUDE.md`?
`CLAUDE.md` é adequado para regras curtas que devem ser aplicadas sempre ao projeto como um todo, enquanto a Skill é adequada para agrupar procedimentos e arquivos de suporte necessários apenas em tarefas específicas. Separar uma checklist longa de validação como Skill permite carregá-la apenas em trabalhos relevantes e executá-la novamente diretamente.

### Em que Dynamic Workflow é diferente de uma chamada comum de Subagent?
No método comum de Subagent, Claude escolhe o próximo executor a cada Turn, e os resultados se acumulam no Context. No Dynamic Workflow, um JavaScript Script gerencia execução paralela, ramificações, repetição e resultados intermediários, permitindo organizar grandes Migration·Audit·validações cruzadas de forma mais reproduzível.

### Usar vários Agent sempre melhora a qualidade?
Não. Se os papéis e pontos de vista se sobrepõem, eles podem repetir os mesmos erros e apenas aumentar o custo. O valor de Agent paralelos surge quando as responsabilidades são separadas, como implementação, desenho de testes, revisão de segurança, análise de regressão e Judge, e quando se exige evidência independente para cada conclusão.

### Como evitar trabalho duplicado em Time-based ou Proactive Loop?
É necessário armazenar chaves de idempotência como Event ID, Commit SHA e Review Comment ID, além do último status de processamento. A etapa de verificação deve incluir regras para não processar novamente mensagens já respondidas, PRs já criados e Commits já processados.

### Que tipo de tarefa é boa para o primeiro Loop a ser automatizado?
São boas as tarefas que uma pessoa verifica repetidamente, mas que têm poucos efeitos colaterais perigosos e cujo estado de conclusão pode ser medido com clareza. Por exemplo, é seguro começar pelo resumo das causas de CI com falha em PRs, pela detecção de inconsistências entre documentos e código e pela validação de testes e lint definidos, e depois ampliar gradualmente as permissões de correção e Push.

## Sources

- [Engenharia de loops: primeiros passos com loops | Claude da Anthropic](https://claude.com/blog/getting-started-with-loops)
- [Estender Claude com habilidades - Documentação do Claude Code](https://code.claude.com/docs/en/skills)
- [Manter Claude trabalhando em direção a uma meta - Documentação do Claude Code](https://code.claude.com/docs/en/goal)
- [Executar prompts em uma programação - Documentação do Claude Code](https://code.claude.com/docs/en/scheduled-tasks)
- [Automatizar o trabalho com rotinas - Documentação do Claude Code](https://code.claude.com/docs/en/routines)
- [Orquestrar subagentes em escala com fluxos de trabalho dinâmicos - Documentação do Claude Code](https://code.claude.com/docs/en/workflows)
- [Escolher um modelo Claude e o nível de esforço no Claude Code | Claude da Anthropic](https://claude.com/blog/claude-model-and-effort-level-in-claude-code)
- [Configurar o modo automático - Documentação do Claude Code](https://code.claude.com/docs/en/auto-mode-config)

## Images

![Robô de IA e painel de código cercados por setas de ciclo e ícones de meta, tempo, segurança e custo](https://injoys.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MTg3OSwicHVyIjoiYmxvYl9pZCJ9fQ==--cac49ec584371c2261bd3272e7574ca38ecc1f85/ChatGPT%20Image%202026%E1%84%82%E1%85%A7%E1%86%AB%207%E1%84%8B%E1%85%AF%E1%86%AF%2016%E1%84%8B%E1%85%B5%E1%86%AF%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%2006_56_28.webp)
![Agente de IA em área protegida com verificação, parada forçada, controle de permissões e monitoramento de recursos](https://injoys.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MTg4NiwicHVyIjoiYmxvYl9pZCJ9fQ==--e5ead4b7a604375b9c6a192eb3a981cf4c93b3c9/ChatGPT%20Image%202026%E1%84%82%E1%85%A7%E1%86%AB%207%E1%84%8B%E1%85%AF%E1%86%AF%2016%E1%84%8B%E1%85%B5%E1%86%AF%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%2007_02_56.webp)