invincible04/awesome-loop-engineering

Engenharia de Loop

Ajude o usuário a substituir a si mesmo como a coisa que dá instruções a um agente de codificação. O resultado é um pequeno sistema que descobre trabalho, entrega a um executor, verifica o resultado com um verificador separado, registra o que foi feito, decide o que vem a seguir e executa novamente até que um objetivo seja atingido, então para por um motivo honesto.

Seu trabalho neste skill não é escrever o loop de uma só vez para eles. É entrevistar, projetar o contrato e depois estruturar para que eles terminem com um loop que possam realmente executar e no qual possam confiar.

O que um loop é, e não é

Um loop não é um cron job. Um cron job repete cegamente. Um loop descobre trabalho, verifica-o com um verificador separado, persiste o estado, decide o que vem a seguir e para por um motivo. Se a coisa que você está construindo não pode parar sozinha, é um bug, não um loop.

Construa as condições de parada primeiro. Elas são o que permite que o usuário se afaste.

Etapa 0: decidir se um loop é a ferramenta certa

Antes de projetar qualquer coisa, aplique este teste. Um loop só vale a pena quando ambas as condições são verdadeiras:

1. Existe um critério de sucesso claro e verificável por máquina (um teste passa, um build fica verde, um esquema valida, uma rubrica retorna PASS).
2. Atingi-lo envolve tentativa e erro tediosos que o usuário faria manualmente, turno após turno.

Se o usuário não puder afirmar como uma máquina saberia que o trabalho está concluído, pare e diga isso a ele. Um loop sem uma condição de conclusão verificável não converge; ele se debate e queima tokens. Ajude-os a encontrar primeiro um proxy verificável ou recomende que continuem instruindo manualmente. Não construa um loop para evitar entender o trabalho.

Bons candidatos a loop: corrigir falhas de CI, triar uma caixa de entrada de issues, atualizações de dependências contra uma suíte de testes sólida, ajuste de desempenho com um benchmark, caça a testes instáveis, builds de documentação que precisam permanecer verdes. Maus candidatos: design aberto, qualquer coisa onde "bom" seja uma questão de gosto sem proxy, tarefas únicas.

Etapa 1: entrevistar o usuário (preencher o contrato do loop)

Faça estas perguntas. Comece com a pergunta de verificação — é ela que decide se o loop é viável. Não faça todas as onze de uma vez; faça em pequenos lotes e infira o que puder com segurança a partir do repositório.

1. Objetivo. Qual é o trabalho recorrente que você continua fazendo manualmente? O que o loop deve tornar verdadeiro?
2. Condição de conclusão (pergunte primeiro, pergunte com afinco). Como uma máquina saberia que está concluída, sem nenhum humano observar? Nomeie o comando ou verificação exata.
3. Gatilho. O que inicia uma execução: um agendamento (a cada N minutos/noturno) ou um evento (push, nova issue, webhook, falha de CI)?
4. Descoberta / Captação. Como uma execução escolhe no que trabalhar? (ler status de CI, consultar o rastreador de issues, ler um fix_plan.md, escanear alertas)
5. Espaço de trabalho. Onde ele atua, e o que é estritamente proibido? (uma árvore de trabalho git ou sandbox; nunca forçar push, tocar em segredos, alterar dependências, atingir produção)
6. Contexto. O que cada execução deve ler para não redescobrir o projeto do zero? (um SKILL.md / AGENTS.md, a especificação, o arquivo de memória)
7. Delegação. Qual agente faz o trabalho (o executor) e qual separado verifica (o verificador)? Eles não devem ser a mesma chamada.
8. Verificação. Quais portões devem passar para que "concluído" seja verdadeiro? (testes unitários, lint, tipos, uma rubrica LLM-como-juiz retornando PASS/FAIL com evidências)
9. Memória / estado. Onde o progresso é armazenado para que uma execução possa retomar após uma reinicialização? (um arquivo markdown, um rastreador de issues, um state.json no disco)
10. Orçamento. Os limites rígidos: iterações máximas, tempo de execução máximo, tokens máximos e um limite de dólares se uma credencial puder gastar dinheiro.
11. Transferência. Quando ele escala para um humano em vez de continuar? (ambíguo, alto risco, ou a mesma falha duas vezes sem novas evidências)

Registre as respostas em templates/loop-contract.template.md. Se o usuário não conseguir responder à pergunta #2 com uma verificação concreta, retorne à Etapa 0.

Etapa 2: escrever o contrato do loop

Preencha o modelo em um loop-contract.md real no repositório do usuário. Este é o artefato de design a partir do qual o loop é construído e revisado. Mantenha-o curto e concreto. Cada campo deve nomear um comando, um caminho ou um número, não uma sensação.

Etapa 3: escolher a menor forma que se encaixa na ferramenta

Mapeie o contrato para o agente do usuário. Escolha o mecanismo mais simples que o satisfaça; não recorra à orquestração multiagente quando um /goal resolver. Veja reference/tool-mapping.md para detalhes.

• Claude Code: /goal para a condição de parada verificada, subagentes em .claude/agents/ para a separação executor/verificador, hooks ou uma tarefa agendada para o gatilho, claude -p ... --output-format json para execuções headless.
• Codex: a aba Automações para o gatilho, codex exec --json para execuções headless, codex exec resume --last para continuar, subagentes para o verificador.
• Greenfield / do zero: um loop bash no estilo Ralph, while :; do cat PROMPT.md | agent; done, com uma tarefa por turno e um fix_plan.md. Melhor quando ainda não há uma base de código para quebrar; combine com um portão e um orçamento para que possa parar. Veja reference/ralph.md.

Etapa 4: estruturar os arquivos

Gere artefatos concretos e executáveis (adapte os nomes à stack do usuário):

• O prompt do executor com as regras inegociáveis incorporadas (veja as leis abaixo).
• O verificador: seja um portão de shell (o comando de teste/lint exato) ou um prompt de verificador que retorna PASS/FAIL mais evidências e pode ESCALATE. Comece a partir de reference/verifier-rubric.md.
• O arquivo de memória (fix_plan.md ou state.json) que uma execução lê primeiro e escreve por último.
• O executor: o loop while, linha de cron, Ação do GitHub ou automação que o dispara, incluindo o portão ("se o build já estiver verde, não faça nada") e o limite de orçamento.

Etapa 5: endurecer antes de deixar executar

Guie o usuário através de reference/hardening-checklist.md antes da primeira execução não supervisionada. Sempre faça um dry-run com um orçamento apertado e uma credencial em sandbox antes de escalar.

As quatro condições de parada honestas

Cada loop deve ser capaz de parar por exatamente uma destas e dizer qual:

• objetivo atingido: o verificador separado confirma a condição de conclusão.
• orçamento esgotado: um limite de iteração, token, tempo ou dólar foi atingido.
• travado: a mesma falha duas vezes sem novas evidências (pare de se debater).
• precisa de um humano: alto risco ou ambíguo, então escala. Este é um estado de sucesso, não uma falha.

As leis inegociáveis

Incorpore as regras 1–5 nas instruções de cada executor. As regras 6–7 não podem ser incorporadas em um executor — elas são de responsabilidade do engenheiro, portanto certifique-se de que o usuário as mantenha.

1. O executor nunca avalia seu próprio trabalho. Um verificador separado decide "concluído". O modelo que escreveu o código é muito generoso ao corrigir sua própria lição de casa.
2. Nunca enfraqueça ou delete um teste, ou reduza uma verificação, para fazê-lo passar. Corrija a causa. Se o teste estiver errado, escale; não o edite silenciosamente.
3. Um loop que não consegue parar é um bug. Conecte as quatro condições de parada antes da primeira execução.
4. A memória vive no disco, não no contexto. Leia-a primeiro a cada turno, escreva-a por último. O agente esquece entre execuções; o repositório não.
5. Corrija apenas a causa; não amplie o escopo. A menor mudança que poderia estar correta.
6. A verificação continua sendo responsabilidade do engenheiro. "Concluído" é uma afirmação, não uma prova. O verificador é o ativo que o usuário possui; o executor é uma commodity que melhora gratuitamente a cada lançamento de modelo.
7. A frota é dimensionada para a taxa de revisão do usuário, não para o número de pistas da ferramenta. O humano é o gargalo serial. Geralmente, o número certo de agentes paralelos é um dígito baixo.

O que o loop nunca faz por você

Diga isso claramente ao usuário para que ele mantenha o trabalho certo:

• Verificação. Um loop executando sem supervisão também é um loop cometendo erros sem supervisão. O verificador separado faz "concluído" significar algo; não o torna certo.
• Compreensão. Quanto mais rápido o loop entrega, mais rápido a dívida de entendimento cresce. Agende tempo para ler o que ele construiu.
• Intenção. Por que este trabalho é importante, e o que "bom" significa, tem que vir de um humano. O loop não sabe a diferença entre usá-lo para se mover mais rápido em um trabalho que você entende e usá-lo para evitar entender o trabalho. Você sabe.

Construa o loop. Mas construa-o como alguém que pretende continuar sendo o engenheiro, não apenas a pessoa que aperta o play.

Leitura adicional (opcional)

Se o usuário quiser a teoria por trás dessas etapas em profundidade — a anatomia do loop e o contrato de 11 partes, /goal vs /loop, memória, economia de tokens e o imposto de orquestração, e os riscos — aponte-o para o manual Awesome Loop Engineering: https://github.com/invincible04/awesome-loop-engineering (legível online em https://invincible04.github.io/awesome-loop-engineering/).