Projeto e Revisão de Loop
Premissa. Um LLM é um sistema feed-forward: prompt → tokens de saída, sem um "direcionamento para o objetivo" embutido entre as etapas. Para fazê-lo comportar-se como um sistema orientado a objetivos, você envolve um loop de feedback nele. Esta skill ajuda você a escrever esse loop corretamente e revisá-lo para que ele não saia do controle.
Quando usar / não usar
Use quando:
- Você quer atribuir uma tarefa repetitiva a um agente que executa várias vezes (escrever→testar, testar→corrigir, corrigir→verificar…).
- Você já tem um loop e está preocupado que ele gire em falso, trapaceie ou execute uma resposta errada até o fim.
Não use para:
- Uma tarefa única → apenas execute-a; não coloque um loop nela.
- Um timer / poll simples → use
/loop; nenhum projeto é necessário. - Como arquitetar o loop (pipelines → DAGs, recuperação de longo prazo) → essa é a camada de mecanismo; veja
autonomous-loops/continuous-agent-loop. Esta skill cobre apenas "o objetivo está certo e ele vai sair do controle?" — ela não reexplica o mecanismo.
Premissa da linha vermelha: dois níveis de feedback
| Nível | Quem controla | O que faz |
|---|---|---|
| Execução (baixo) | máquina / agente | Mede "quão longe do objetivo literal" e o reduz a zero. A máquina é forte aqui. |
| Julgamento (alto) | humano | Decide "esse objetivo em si está certo, deve mudar, deve parar." A máquina não pode sair do seu próprio loop para questionar o objetivo. |
Um termostato pode realimentar "quão longe dos 26°C", mas quando você está com febre e quer 28°C, ele não pode julgar se 26 é o alvo certo — ele apenas reduz a diferença para 26. "O que ajustar hoje" é sempre a decisão do humano. Entregar o julgamento / a aprovação / o último interruptor para a máquina = remover o feedback de alto nível = ela corre, rápido e forte, em direção a um objetivo que ninguém questionou → saída errada.
Ação 1 — Escrever um loop (5 etapas)
Etapa 0 · Subtraia primeiro: você deveria mesmo construir isso? (portão de 4 condições, qualquer falha = veto)
① a tarefa se repete semanalmente ou mais ② a verificação pode ser automatizada ③ o orçamento de tokens suporta ④ o agente tem ferramentas que realmente executam e veem o resultado
Falhe em qualquer uma → não construa um loop; faça manualmente ou de outra forma.
O que impede a maioria das pessoas não é "consigo escrever um loop", é "meu repositório merece um". Um repositório que merece um loop tem uma linha de base de reconciliação (amostra dourada / total upstream) + testes + um guardião de lint. Um repositório que não merece um loop só terá seus erros amplificados por um.
Etapa 1 · Defina um objetivo decidível por máquina (a parte difícil — o loop vive ou morre aqui)
Todo o loop depende do comparador "já terminou?" O comparador só pode funcionar se sua condição de saída puder ser julgada como sim/não por uma máquina.
- Ruim: Vago ("tornar bom", "escrever mais afiado") → o comparador não pode julgar → ou nunca passa (preso tentando novamente) ou adivinha (passa/bloqueia aleatoriamente).
- Bom: Decidível ("todos os 96 testes unitários verdes E uma lista de alterações é produzida", "campos do módulo-02 preenchidos, pytest passa, lógica de negócios intacta") → uma verificação resolve; o loop converge limpo.
Estrutura de cinco pontos para o objetivo:
- O critério de conclusão é verificável por máquina.
- Condições de contorno definidas junto com o critério de conclusão ("o que NÃO deve fazer") — anti-Goodhart; limites ausentes = licença para trapacear.
- Tem um plano de fallback para falhas — limite de tentativas N + escalar para um humano quando excedido.
- O objetivo é em camadas.
- Prefira reconciliação em vez de asserção para o critério de conclusão — ancore a um fato externo (amostra dourada / total upstream / conciliação financeira / números do back-office da plataforma) antes de suas próprias asserções. "Todos os testes passam" pode ser manipulado (afrouxar asserções, simular mocks, engolir exceções); "diferença vs a referência < 0,01" não pode.
Autoavaliação: leia o objetivo para alguém que não conhece o domínio — essa pessoa consegue executar um comando e dizer se está pronto? Se não, não é decidível o suficiente. Volte.
Etapa 2 · Escolha o tipo de loop
| Sua tarefa | Tipo de loop (cibernético) | Como para |
|---|---|---|
| Tem um teste "pronto" claro (escrever até ficar pronto / um lote de imagens processadas) | servo (loop fechado estilo /goal) | para ao atingir o objetivo |
| Sem ponto final, deve manter um estado continuamente (alerta de estoque / verificação de saúde agendada) | regulador (termostato estilo /loop) | nunca para; age apenas na mudança (banda morta suprime ruído) |
| Amostragem periódica, para em uma condição (observar um PR até o CI ficar verde) | regulador com saída | para quando a condição de saída é atendida |
| Deve "garantir que algo aconteça na hora" | envolva o acima em /schedule | cron o aciona |
Regra prática: teste "pronto" claro → servo; deve manter, sem ponto final → regulador; deve "acontecer na hora" → envolva um regulador em schedule.
Etapa 3 · Escolha um esqueleto
Tipo manutenção (cuidar de algo que existe) → despacho orientado por documento. O loop não é "executar uma verificação fixa em um timer", é "ler um documento em um timer e despachar apenas quando o documento mudar". O documento é a fila de tarefas + máquina de estado + interface humana. Três disciplinas: ① a coluna de problema é somente escrita por humano, a coluna de resultado é somente escrita pelo loop, o estado avança em uma direção e nunca retrocede; ② o código de saída é final (se o script diz exit 1, o script vence); ③ o estado avança apenas até "aguardando verificação" — a célula "pronto" é alterada apenas por um humano. O loop é o trabalhador, não o oficial de aceitação.
Tipo greenfield (construir do zero) → planejar / construir / julgar, três papéis.
| Papel | Faz | Chave |
|---|---|---|
| Planejar | decompor o objetivo em uma especificação + condições de aceitação decidíveis | a aceitação deve ser julgável por script |
| Construir | escrever de acordo com a especificação | não deve alterar as condições de aceitação |
| Julgar | executar a aceitação independentemente; passar → parar, falhar → retornar com o motivo da falha para Construir | independente + determinístico |
Três regras de ferro (todas apostam no juiz): ① o juiz deve ser independente — não o mesmo agente que Construir (avaliar o próprio trabalho sempre infla); ② regras determinísticas — pytest / diff de reconciliação / verificação de tipo / diff, nunca "parece certo"; ③ Construir não pode editar as condições de aceitação para passar. Três tentativas falhas → escalar para um humano.
Etapa 4 · Adicione amortecimento (contra oscilação / fuga)
Limite de repetições, parada forçada, humano como último interruptor = amortecimento. Feedback negativo sem amortecimento oscila (o loop Ralph-Wiggum: girando no lugar, queimando tokens).
Etapa 5 · Implemente em três estágios (não vá para o automático no primeiro dia)
① Execute uma vez manualmente (força você a declarar exatamente "como o juiz decide") → ② solidifique em uma skill / subagentes do Claude Code (um Claude principal faz loop, despachando planejar/construir/julgar) → ③ coloque no cron para automação total.
Ação 2 — Revisar um loop (lista de verificação = cinco modos de falha)
Execute o loop por cada linha. Acertar qualquer um = este loop falhará; devolva-o. Esses cinco são experiências negativas (armadilhas) — valem mais do que regras positivas.
| # | Modo de falha (como quebra) | Pergunta de revisão (acerto = vermelho) | Anticorpo |
|---|---|---|---|
| 1 | Objetivo é um lugar-comum correto → gira, queima dinheiro | A condição de saída pode ser julgada como sim/não por máquina? Ou é "gerencie bem / torne bom"? | Substitua por uma condição de resultado decidível (Ação 1·Etapa 1) |
| 2 | "Verificação" escrita como "verificar se parece ok" → agente confiantemente diz que está bom e para | O juiz é o próprio réu? A verificação se baseia em "parece certo" ou em regras determinísticas? | Reconciliação + regras de código de saída + juiz independente |
| 3 | (pior) Apenas bloqueia em "todos os testes passam" → agente deleta os testes | Existe um limite ("o que NÃO deve fazer")? Ou apenas um critério de conclusão? | Critério de conclusão + limite juntos (o anticorpo Goodhart) |
| 4 | Conta com o agente perguntando no meio → não pergunta; executa a resposta errada até o fim | Existe algum ponto de "esclarecer apenas em tempo de execução"? | Esclareça tudo com antecedência; resolva uma vez antes do lançamento |
| 5 | CLAUDE.md inchado + memória desatualizada → quanto mais rápido o loop, mais erra | Os docs/memória dos quais depende estão atualizados? Quem os mantém? | Memória em camadas + lint periódico |
Mais três linhas vermelhas (violar qualquer uma = não pode ir para automático):
- Mantenha o julgamento com o humano. A aceitação / a célula "pronto" é alterada por um humano; o loop não é o oficial de aceitação.
- A responsabilidade não é transferida. Qualquer coisa cuja falha você não pode arcar (fundir o PR errado / publicar a coisa errada / alocar dinheiro errado) → não entregue a autoridade automaticamente.
- Advertência contraintuitiva. Quanto mais um loop é "auto-melhorável / reescreve suas próprias regras", mais rigorosa a revisão humana que precisa (para ver no que ele transformou as regras) — não menos. A máquina é rápida demais para interceptar depois do fato, então o julgamento do humano deve ficar antes da ação (um portão rígido), não como um remendo posterior.
Exemplo prático — revisando um loop "guardião noturno"
Você quer um loop que execute todas as noites e corrija os testes que estão falhando.
- Objetivo ingênuo: "fazer todos os testes passarem." → A autoavaliação da Etapa 1 falha: esta é a isca para o modo de falha #3.
- Objetivo decidível (corrigido): "todos os testes verdes E nenhum arquivo de teste deletado ou enfraquecido E cobertura não reduzida E uma lista de alterações produzida." Limite agora definido junto com o critério de conclusão.
- Tipo: servo com limite de 3 tentativas (Etapa 2 + Etapa 4).
- Esqueleto: planejar/construir/julgar — o juiz é o CI executado independentemente, nunca o agente que corrige (Etapa 3).
Agora execute a lista de verificação de revisão, e ela pega o que a versão ingênua teria perdido:
- #3 acertou → o "todos os testes passam" ingênuo permite que o agente delete um teste com falha para "vencer." Corrigido pelo limite "nenhum arquivo de teste deletado/enfraquecido."
- #2 acertou → se o agente que corrige também julgasse sua própria correção, ele se aprovaria. Corrigido por "juiz = CI independente, determinístico."
- #4 acertou → se uma correção é ambígua, o agente não vai parar para perguntar às 2 da manhã; ele vai fazer um palpite. Corrigido por esclarecimento prévio: correções ambíguas são deixadas para o humano, não adivinhadas.
- Linha vermelha → o loop abre um PR, mas não faz merge automático; o humano aciona o último interruptor (a responsabilidade não é transferida).
O loop ingênuo e o loop revisado diferem por quatro linhas de restrição — e essa é a diferença entre "acorda você com uma suíte de testes deletada" e "acorda você com um PR limpo."
Fechamento em uma linha
A parte difícil de escrever um loop não é "consigo escrever um loop", é definir um objetivo que uma máquina possa reconciliar — decidível, limitado, baseado em reconciliação. O controlador deve ser determinístico e externo; mantenha o julgamento e o padrão com o humano; o sistema tende à entropia, então mantenha-o. Um loop só recompensa alguém que já pensou nele. Conte que ele pense por você, e ele pensará felizmente errado, com você, em escala.
Linhagem: feedback de dois níveis de Wiener (The Human Use of Human Beings, 1950) para a divisão julgamento/execução e linhas vermelhas; o padrão planejar/construir/julgar de Loops explained do Anatoli e Loop Engineering do Addy. Camada de mecanismo (como arquitetar o loop): veja
autonomous-loops/continuous-agent-loop. Esta skill não reimplementa mecanismo; ela cobre apenas definição de objetivo e prevenção de fuga.