sxivansx/loop-engineering

Engenharia de Loop

Configure um loop: um sistema autônomo que aciona o agente para que você não precise fazer isso. Você define a meta e a condição de parada uma única vez; o loop encontra trabalho, executa, verifica, registra o que aconteceu e é executado novamente até que a meta seja atingida. Este skill implementa esse loop dentro do seu projeto existente: ele lê como você já testa, compila e gerencia tarefas, e então adapta o loop às suas convenções em vez de impor genéricas.

Um loop é construído a partir de seis primitivas. Configure apenas aquelas que a meta exige.

Primitiva	Papel no loop	Mecanismo do Claude Code
Gatilho	inicia cada ciclo, em um agendamento ou evento	/goal (trabalha ao longo de turnos até que uma condição seja atendida), /loop, tarefas agendadas, hooks, GitHub Actions
Estado	a memória do loop entre ciclos, em disco	um arquivo markdown (LOOP.md) ou um rastreador de issues via MCP
Descoberta	encontra o que trabalhar neste ciclo	uma etapa de triagem que lê CI, issues, diffs, uma fila
Executor	realiza uma unidade do trabalho	um subagente em .claude/agents/
Verificador	verifica o executor, de forma independente	um subagente diferente em .claude/agents/
Condição de parada	a regra que encerra o loop	uma verificação que o verificador executa

Para qualquer loop que execute sem supervisão, adicione um monitor: um agente de supervisão que observa o loop como um todo e o interrompe em caso de desvio (sair da meta), rotação (nenhum progresso líquido) ou violação de limite (muitos ciclos, muito tempo). O executor e o verificador mantêm cada item correto; o monitor mantém todo o loop apontado para a meta, para que ele não possa vagar silenciosamente e executar por horas.

Dois complementos opcionais adicionais: worktrees (git worktree) isolam executores paralelos para que não editem os mesmos arquivos, e conectores MCP permitem que o loop toque em ferramentas reais (abrir um PR, atualizar um ticket, postar status). Adicione-os quando a meta exigir paralelismo ou efeitos colaterais externos.

Procedimento de configuração

Isso é executado dentro de um projeto existente. Siga estas etapas quando invocado. Confirme com o usuário antes de qualquer coisa com efeitos colaterais: tarefas agendadas, pushes, gravações de tickets, deploys.

1. Leia o projeto primeiro. Antes de qualquer scaffolding, conheça o repositório: como ele executa testes, build e lint (verifique package.json, Makefile, configuração de CI, CLAUDE.md); quais convenções e skills existentes ou .claude/agents/ ele já possui; e de onde vem o trabalho (CI, um rastreador de issues, um backlog, uma fila). O loop precisa se ajustar a este projeto. Reutilize seus comandos e convenções reais, não invente novos.

2. Defina a meta e a condição de parada. Pergunte ao usuário pela meta única do loop e pela condição verificável que significa concluído (testes exit 0, a fila está vazia, zero verificações com falha). Um loop sem condição de parada é a única coisa que você nunca deve enviar. Se o usuário não conseguir nomear uma, defina um fallback limitado (parar após N ciclos) e diga isso em voz alta. No Claude Code, /goal <condição> torna isso executável: Claude continua trabalhando entre turnos até que a condição seja atendida, e /goal clear encerra antecipadamente.

3. Escreva o arquivo de estado. Copie ${CLAUDE_SKILL_DIR}/templates/LOOP.md para a raiz do repositório e preencha meta, condição de parada, cadência e o portão humano. Ele tem três seções vivas que o loop mantém: ## Abertos (encontrado, não concluído), ## Concluídos (com a evidência que o verificou), ## Bloqueados (precisa de um humano), além de uma seção ## Regras que é o conjunto de instruções permanentes que todo agente no loop segue. O loop lê isso primeiro a cada ciclo e escreve por último.

4. Crie o subagente executor. Copie ${CLAUDE_SKILL_DIR}/templates/loop-maker.md para .claude/agents/loop-maker.md e aponte para as convenções e o comando de teste que você encontrou na etapa 1. Ele executa exatamente um item de ## Abertos, segue as skills e convenções existentes do projeto e nunca marca seu próprio trabalho como concluído. Se um arquivo com esse nome já existir, atualize-o em vez de sobrescrever cegamente.

5. Crie o subagente verificador. Copie ${CLAUDE_SKILL_DIR}/templates/loop-checker.md para .claude/agents/loop-checker.md. É um agente diferente do executor, executa a verificação real do projeto (o comando real de teste, build ou lint da etapa 1, não uma descrição dele) e é o único agente autorizado a mover um item para ## Concluídos.

6. Crie o subagente monitor (recomendado para qualquer loop sem supervisão). Copie ${CLAUDE_SKILL_DIR}/templates/loop-monitor.md para .claude/agents/loop-monitor.md e execute-o a cada poucos ciclos ou em um temporizador mais lento que o loop. Ele observa o loop como um todo, em vez de qualquer item individual: verifica se o loop ainda está convergindo para a meta e interrompe o loop e escala para um humano em caso de desvio (trabalho que não serve à meta), rotação (nenhum progresso líquido, itens saltando entre Abertos e Bloqueados) ou violação de limite. Isso é o que impede um loop de vagar silenciosamente e executar por horas.

7. Defina a cadência de revisão de código e auditoria de segurança (pergunte ao usuário). Pergunte com que frequência o loop deve executar cada uma e registre ambas em LOOP.md. Ofereça opções claras e sempre inclua nunca:

   • Revisão de código (/code-review): a cada alteração, antes de cada PR ou merge, a cada N ciclos, semanalmente ou nunca.
   • Auditoria de segurança (/security-review): a cada alteração, antes de cada PR ou merge, semanalmente, mensalmente ou nunca.

   Na cadência escolhida, o loop executa essa passagem embutida e arquiva o que encontra em ## Abertos como novos itens de trabalho, para que o executor os corrija e o verificador verifique a correção. Se o usuário escolher nunca, pule essa passagem completamente e registre nunca em LOOP.md para que o loop não a reintroduza.

8. Defina a descoberta. Escreva a etapa de triagem que preenche ## Abertos a cada ciclo a partir de onde o trabalho deste projeto realmente vive (status de CI, issues abertas, commits recentes, uma fila de trabalho) e como ela transforma descobertas em itens discretos e individualmente verificáveis. Torne-a determinística sempre que possível.

9. Escolha o isolamento (opcional). Se mais de um executor for executado por ciclo, dê a cada um seu próprio git worktree e branch para que nunca escrevam o mesmo arquivo. Um worktree por item.

10. Conecte os conectores (opcional). Se o loop precisar abrir PRs, atualizar tickets ou postar status, conecte o servidor MCP correspondente. Caso contrário, a saída do loop permanece local e um humano a repassa.

11. Configure o gatilho. Escolha o mecanismo mais leve que se encaixa na cadência:

    • execute até que a meta seja atendida, nesta sessão → /goal <condição de parada> (Claude trabalha entre turnos até que a condição seja verdadeira; /goal clear encerra antecipadamente)
    • repita em uma cadência, sob demanda → /loop
    • periódico e sem supervisão → uma tarefa agendada (ou cron / um GitHub Action para loops do lado do CI)
    • reaja a um evento (push, PR, alteração de arquivo) → um hook ou um GitHub Action

    Confirme com o usuário antes de criar qualquer tarefa agendada.

12. Teste, verifique e ative. Execute um ciclo manualmente. Leia tudo o que ele produziu. Confirme que o verificador realmente bloqueia saída ruim e que o estado foi gravado. Só então ative o gatilho.

Guardrails (innegociáveis)

• O verificador nunca é o executor. O agente que escreveu o código não pode declará-lo correto.
• A condição de parada é verificável, não baseada em impressões. "Parece concluído" não é uma condição de parada. Um comando que sai com 0 é.
• O estado é gravado a cada ciclo. Se o loop esquecer o que tentou, ele se repete. O modelo esquece; o arquivo não.
• Um portão humano permanece em qualquer coisa irreversível. Enviar, implantar, excluir, gastar dinheiro. O loop rascunha, uma pessoa confirma. Um loop sem supervisão comete erros sem supervisão.
• Bloqueado é melhor que adivinhar. Quando o loop não pode verificar ou prosseguir, ele escreve em ## Bloqueados e interrompe aquele item. Ele não envia um palpite.
• Um loop longo é observado e limitado. Qualquer loop sem supervisão é executado com um monitor e um limite. Se ele se desviar da meta ou ultrapassar o limite, o monitor o interrompe e escala. Um loop nunca pode executar para sempre na direção errada.

Como o loop se parece depois de configurado

seu-projeto/
├── LOOP.md                   # meta, condição de parada, limites, regras, Abertos/Concluídos/Bloqueados
├── .claude/
│   └── agents/
│       ├── loop-maker.md      # executa uma unidade de trabalho
│       ├── loop-checker.md    # a verifica, de forma independente
│       └── loop-monitor.md    # observa todo o loop em busca de desvio e fuga
└── (gatilho: /goal, /loop, uma tarefa agendada ou um GitHub Action)

Antipadrões: não envie estes

• Um loop sem condição de parada (executa para sempre, queima tokens).
• Um agente que escreve e avalia seu próprio trabalho.
• Um loop sem arquivo de estado (re-deriva tudo, repete trabalho, esquece o que falhou).
• Um loop sem supervisão sem monitor ou limites (desvia-se da meta e executa por horas antes que alguém perceba).
• Envio sem supervisão sem portão humano em ações irreversíveis.
• Um loop carregando muitos trabalhos não relacionados. Um loop, uma meta, uma condição de parada. Divida o restante em seus próprios loops.

Arquivos neste skill

• templates/LOOP.md: o arquivo de estado a ser copiado para o repositório de destino.
• templates/loop-maker.md: a definição do subagente executor.
• templates/loop-checker.md: a definição do subagente verificador.
• templates/loop-monitor.md: a definição do subagente monitor (guarda contra desvio e fuga).
• examples/keep-ci-green.md: um loop completo trabalhado, da meta ao gatilho.