Engenharia de Loops de IA: Quatro Loops – De um Problema no GitHub a um Recurso Integrado

Há algumas semanas, parei de ficar monitorando um pull request e deixei que um agente o fizesse.

A tarefa era daquele tipo tedioso e exaustivo que toda equipe conhece. Um PR é aberto, a CI é executada, algo falha, você corrige, envia, espera dez minutos para a CI retornar e então a próxima etapa falha. A cobertura caiu abaixo do limite. O Checkstyle está insatisfeito. Um teste instável falhou na nova tentativa. A ferramenta de análise estática encontrou um novo “code smell” (cheiro de código ruim). Cada rodada consiste em cinco minutos de trabalho e dez minutos de espera, e você repete isso cinco vezes antes do PR finalmente ser aprovado.

Então, escrevi um loop. Ele verifica cada critério de qualidade no PR e, se algum estiver vermelho, corrige o código, faz o commit, envia as alterações e aguarda a próxima execução da CI antes de verificar novamente. Ele para quando o PR estiver totalmente verde e pronto para merge, ou após dez iterações, o que ocorrer primeiro. O limite de dez iterações é a parte importante: é a diferença entre “um agente que me ajuda” e “um agente que desperdiça tokens indefinidamente em um problema que não consegue resolver”.

Então percebi que a mesma ideia também se aplicava a uma etapa anterior do processo. O pull request é o fim da história. Antes dele existir, há toda uma fase de construção: transformar uma especificação em tarefas, implementar cada tarefa, validar e revisar. Eu já executo essa fase por meio do meu framework de desenvolvimento orientado a especificações , então os sensores já estavam lá. Envolver esses sensores em um loop me deu um segundo loop que leva uma funcionalidade da especificação para uma branch limpa e revisada, pronta para o primeiro loop assumir o controle.

Este post trata desse padrão: engenharia de loops , o design de loops ágeis que convergem para um objetivo em vez de se prolongarem indefinidamente ou desistirem prematuramente. E aborda como um conjunto de loops se compõe em um pipeline que leva uma funcionalidade desde a sua concepção até a sua integração, com pontos de verificação humanos posicionados exatamente onde o julgamento é necessário.

Pense em um problema de agendamento comum: seu aplicativo precisa enviar um relatório para um cliente todos os dias às 9h. Você escreve a lógica que gera o relatório, agenda a execução para as 9h e ela faz a mesma coisa todas as vezes. A engenharia de loops segue a mesma ideia: agendar uma tarefa repetitiva, só que, em vez de executar um script fixo, o que é executado nesse agendamento é um agente de IA que observa, decide e age.

Neste post, abordaremos:

• O que é, de fato, um loop agentivo e as seis partes que todo bom loop possui.
• Um formato de loop que você pode reutilizar para quase qualquer tarefa do tipo “concluir esta etapa”.
• Loop 1, o loop do navio : um loop do Claude Code que leva um PR do GitHub ao estado pronto para mesclagem.
• Quatro formatos de loop diferentes (controle de qualidade, escalador de cobertura, atualização de dependência, estabilizador de teste instável) compostos dentro desse loop.
• Loop 2, o loop de construção : um loop SDD que leva uma especificação a um branch limpo e revisado com commit automático.
• Por que o ciclo de construção é o mais avançado e a confiança que você precisa conquistar antes de executá-lo.
• Ciclo 3, o ciclo de refinamento de especificações : transformando um problema bruto em uma especificação aprovada para revisão.
• Ciclo 4, o ciclo de revisão-resposta : processar os comentários de um revisor humano até que não restem mais comentários.
• Como os quatro elementos se combinam em um fluxo de trabalho que vai da emissão à fusão, com intervenção humana em exatamente dois pontos.
• Os guarda-corpos que mantêm cada circuito seguro, delimitado e barato.

O que é, de fato, um Loop Agencial?

Um loop não significa “executar o agente novamente”. Um loop é um sistema de controle. O agente observa o mundo, compara-o com um objetivo, age para reduzir a diferença e, em seguida, observa novamente. A habilidade não está na ação em si. Programar agentes já é eficiente em agir. A habilidade reside em definir o que o agente observa e quando ele pode parar .

Todo loop que valha a pena construir tem seis partes. Se você conseguir nomear todas as seis partes da sua tarefa, você tem um loop. Se não conseguir, você tem um comando que está executando manualmente.

• Critérios de objetivo/sucesso. A definição precisa e verificável de “concluído”. Não se trata de “fazer o RP ficar bom”. Algo que um script possa responder com sim ou não: todas as verificações aprovadas, cobertura igual ou superior a 90%, zero novos problemas de análise estática.
• Sensores. Como o agente observa o estado atual. Esta é a parte que as pessoas ignoram, e é a parte mais importante. Um loop só é tão bom quanto o que ele consegue medir. Status de CI, um relatório de cobertura, uma resposta da API do Sonar, a saída de uma execução de teste repetida vinte vezes.
• Ação. O que o agente altera quando o estado não corresponde ao objetivo. Corrigir o código, escrever o teste que falta, atualizar a dependência, confirmar e enviar as alterações.
• Cadência. A frequência com que o loop é executado. Alguns loops são orientados a eventos (aguardam a conclusão da integração contínua). Outros são executados na velocidade permitida pelo volume de trabalho (consomem uma fila de tarefas localmente). Escolher a cadência errada resulta em desperdício de recursos ou na perda de sinais relevantes.
• Orçamento limitado. A válvula de escape. Número máximo de iterações, prazo final ou limite de tokens. É isso que impede que um ciclo se arraste indefinidamente em um problema que não consegue resolver. Meu ciclo de nave para em dez.
• Diretrizes. As regras sobre o que o agente não deve fazer. Nunca mesclar por conta própria. Nunca forçar o envio (push). Nunca alterar arquivos fora da área de alteração. Nunca desabilitar um teste com falha para fazê-lo passar.

A maioria dos loops de agentes que vi falharem se concentra nos dois últimos pontos. Eles têm um objetivo claro e bons sensores, mas acabam se descontrolando porque ninguém definiu o orçamento ou os limites de segurança.

O formato de um laço

Aqui está o fluxo de controle, representado graficamente. Esse mesmo formato funciona para quase qualquer tarefa de “levar este artefato a um estado desejado”, e é por isso que vale a pena internalizá-lo pelo menos uma vez.

Leia como uma frase: observe o PR e, se todos os pontos de verificação estiverem verdes, pare, pois está pronto para mesclar. Caso contrário, corrija o código e envie. Se ainda tivermos iterações disponíveis no orçamento, aguarde a próxima execução da CI e observe novamente. Se o orçamento estiver esgotado, pare e reporte o problema a um humano, em vez de ficar em um loop infinito.

Essa ramificação de escalonamento não é uma falha. É o loop fazendo seu trabalho. Um loop que sabe quando devolver o problema é mais útil do que um que finge que pode resolver tudo.

Loop 1: O Ship Loop, um RP que se impulsiona rumo ao verde.

Para tornar isso mais concreto, usei o Claude Code , pois seus /loopcomandos e habilidades correspondem quase que perfeitamente às seis partes mencionadas acima. A mecânica se aplica a qualquer agente que possa ser executado de acordo com um cronograma e chamar sua CI; o que importa é a estrutura.

O plano é simples. Definimos uma habilidade que sabe como verificar e corrigir os critérios de qualidade de um PR (ou seja, o objetivo, os sensores, a ação e as salvaguardas). Em seguida, a envolvemos em um loop que executa a habilidade em intervalos regulares até que o PR esteja aprovado ou o orçamento se esgote (ou seja, a cadência e o orçamento limitado).

Uma habilidade que conhece os portões

Uma skill do Claude Code é simplesmente um arquivo Markdown com um pequeno cabeçalho e um conjunto de instruções. Aqui está uma versão simplificada da ideia. O verdadeiro valor reside no fato de que os critérios de sucesso e as diretrizes estão presentes na skill em linguagem simples, que o agente deve seguir em cada iteração.

---
name: pr-quality-gate
description: Check all quality gates on a GitHub PR and fix anything failing. Use when driving a PR to merge-ready.
---

You are driving pull request #$1 to merge-ready. Do exactly one pass.

## Sensors: gather the current state first
- Run `gh pr checks $1` to get the CI check status.
- Run `gh pr view $1 --json statusCheckRollup,mergeable` for the rollup.
- Pull the coverage report from the latest CI run artifacts.
- Query the Sonar API for new issues introduced by this PR.

## Success criteria (the goal)
The PR is merge-ready ONLY when ALL of these are true:
- Every CI check is passing (unit, integration, architecture tests).
- Checkstyle reports zero violations.
- Line coverage is >= 90%.
- Sonar reports zero new issues on this PR.

If all are true, post a comment `✅ All gates green — ready to merge` and STOP. Do not merge the PR yourself.

## Action: fix exactly what is failing
For each failing gate, make the smallest correct change that fixes the root cause, then commit with a conventional-commit message and push to the PR branch.

## Guardrails — non-negotiable
- NEVER merge, approve, or close the PR.
- NEVER force-push or rewrite history.
- NEVER disable, skip, or delete a test to make a gate pass.
- NEVER touch files unrelated to this PR's diff.
- If a failure is ambiguous or you are not confident in the fix, post a comment explaining it and STOP for a human.

Note o que a habilidade não é . Não se trata de um comando inteligente que diga “faça o RP ficar bom”. É uma lista de verificação de sensores, uma definição inequívoca de “concluído” e uma lista rígida de coisas que o agente não pode fazer. Essa é a estrutura que envolve o processo.

Enrole em um laço

Agora, a cadência e o orçamento. No Claude Code, /loopum prompt ou outro comando é executado em intervalos recorrentes:

/loop 10m /pr-quality-gate 1234

Isso executa a pr-quality-gateskill em relação ao PR #1234 a cada dez minutos. O intervalo de dez minutos é a cadência, escolhida para corresponder aproximadamente ao tempo que o CI leva para retornar. Não faz sentido verificar a cada trinta segundos quando o sinal que você está esperando muda apenas uma vez por execução do CI. Consultar mais rápido do que seus sensores atualizam é ​​a maneira mais comum de desperdiçar dinheiro em um loop.

O orçamento limitado reside nos critérios de parada do loop. Você define que ele deve parar quando a habilidade reportar que o PR está verde ou após dez iterações:

Pare quando o PR publicar o comentário “pronto para mesclar” ou após 10 iterações, o que ocorrer primeiro. Na décima iteração sem sucesso, resuma o que ainda está falhando e o que você tentou, e pare.

Esse é o ciclo completo. Seis partes, dois arquivos e um PR que se executa sozinho até a linha de chegada enquanto você faz outra coisa.

Quatro Portões, Quatro Formatos de Loop Diferentes

Eis a parte que demorei um pouco para entender. O loop da nave acima parece um único loop, mas os quatro portões dentro dele são quatro tipos diferentes de loop , cada um com sua própria definição de progresso. Compreender o formato de cada um é o que permite otimizá-lo, porque um loop que sobe em direção a um número não se comporta de maneira alguma como um loop que processa uma fila.

Forma 1: Convergência para o Verde

Esta é a configuração padrão e a mais simples. O estado é binário por verificação: vermelho ou verde. A função do agente é converter todos os vermelhos em verdes e mantê-los assim. O modo de falha clássico é a oscilação : a correção para o teste de integração com falha introduz uma violação do Checkstyle, e a correção dessa violação quebra um teste unitário. Um bom loop de convergência para o verde executa novamente todos os sensores após cada alteração, não apenas aquele em que estava trabalhando, para que perceba quando trocou um vermelho por outro.

Forma 2: O Escalador de Cobertura

A cobertura não é binária. É um número que você está tentando alcançar um limite, o que torna o loop fundamentalmente diferente. “Concluído” não significa “o teste passou”, mas sim “a métrica ultrapassou 90%”. A maneira natural de executar esse loop é sempre atacar o arquivo com a menor cobertura em seguida:

1. Leia o relatório de cobertura e encontre a classe mais abaixo da linha.
2. Escreva testes significativos para os ramos não cobertos.
3. Reprise da cobertura. O número de espectadores aumentou?
4. Se ainda estiver abaixo de 90%, repita o processo com o arquivo imediatamente inferior.

O perigo aqui é único e merece ser destacado na habilidade: um agente instruído a “aumentar a cobertura” escreverá alegremente testes que executam código sem afirmar nada, porque isso eleva a métrica. O número aumenta e os testes não provam nada. Seus critérios de sucesso precisam exigir afirmações significativas , e seu portão de convergência para verde (Forma 1) é o que mantém os novos testes honestos, porque testes vazios ainda precisam passar pela revisão e não quebrar a compilação.

Forma 3: A atualização de dependência (uma fila)

A atualização de dependências é um processo em lote. Você não está convergindo para um único estado; você está esvaziando uma fila de trabalho, um item de cada vez, até que ela esteja vazia.

1. Construir a fila: listar todas as dependências desatualizadas.
2. Pegue o próximo. Dê um toque nele.
3. Compile e execute os testes. Se a atualização causou algum problema, corrija-o (um pequeno loop de convergência para verde aninhado dentro desta etapa).
4. Confirme essa atualização individualmente para que seja fácil revisá-la ou revertê-la.
5. Se a fila não estiver vazia, volte ao passo 2.

A condição “concluído” é uma fila vazia, não uma métrica positiva. O modo de falha é o travamento: uma dependência tem uma alteração incompatível que o agente não consegue resolver, e um loop ingênuo a sobrecarregará indefinidamente. É exatamente aqui que o orçamento por item se torna importante. Atribua a cada item da fila seu próprio limite de iterações pequeno e, quando um item atingir esse limite, ignore-o, deixe-o na fila e registre-o, em vez de permitir que uma atualização complexa bloqueie as outras dezenove atualizações simples.

Forma 4: O Estabilizador para Testes Ineficazes (Repita até ter certeza)

Esta é a forma mais sutil, porque o que você está medindo não é determinístico. Um teste falho passa na maioria das vezes, então uma única linha verde não lhe diz quase nada. O que está sendo medido aqui é a confiança estatística , não uma única observação.

1. Execute o teste suspeito (ou todo o conjunto de testes) N vezes seguidas.
2. Registre a proporção de aprovações/reprovações. Um teste que falha 3 vezes em 20 execuções é considerado instável.
3. Diagnostique a causa raiz: uma condição de corrida, um recurso compartilhado, uma dependência de tempo ou de ordem.
4. Corrija isso.
5. Execute o programa N vezes novamente. Só declare-o estável quando passar em todas as N execuções.

O erro crucial é declarar vitória cedo demais. Um loop que executa o teste uma vez após a correção e obtém sucesso reportará sucesso em um teste que ainda falha uma vez a cada cinquenta. O critério de sucesso deve ser “aprovado em N execuções consecutivas”, e N é um parâmetro que você ajusta com base na instabilidade inicial do teste. Quanto mais intermitente for a falha original, mais execuções você precisa para confiar na correção.

O motivo pelo qual os quatro elementos estão contidos em um mesmo loop é que compartilham a mesma estrutura externa: observar, comparar com a meta, agir, verificar o orçamento e repetir. O loop externo não se importa se a cobertura é um número e a fila de atualizações é uma lista. Ele simplesmente pergunta a cada ponto de controle “você está verde?” e permite que cada um responda à sua maneira. É importante manter a fila e as formas de convergência para o verde em foco, pois o segundo loop é construído a partir de ambas.

Loop 2: O Loop de Construção, da Especificação a um Ramo Limpo

O loop de desenvolvimento é executado no final da funcionalidade, em um PR já existente. O loop de compilação é executado no início , e é com ele que tenho mais cuidado, porque ele escreve a funcionalidade em vez de aprimorá-la.

Eu executo minha fase de build através da estrutura de desenvolvimento orientado a especificações que descrevi em Specs-Driven Development in Practice . Resumidamente: uma funcionalidade começa como uma especificação, é revisada, torna-se um design e é decomposta em /planuma fila de pequenas tarefas no formato TDD ( T-001, T-002, …) rastreadas em uma .tdd-state.jsonmáquina de estados. Cada tarefa é implementada com /build T-00X, que a move pending → red → green → refactor → donee a confirma quando seus gates são aprovados. Quando a fila está vazia, /validateexecuta todo o conjunto de testes (testes, cobertura, lint) e /reviewaudita a implementação em relação à especificação, retornando um veredicto com correções obrigatórias, correções recomendadas, correções pontuais e elogios.

Leia isso novamente e você perceberá que já é um loop com todas as seis partes , executado manualmente. O loop de construção apenas o fecha.

• Objetivo: cada tarefa concluída, /validatelimpa e /reviewcom resultado APROVADO, sem nenhuma pendência que precise ser corrigida.
• Sensores: .tdd-state.json a /validatesaída, o /reviewveredito. A estrutura é a camada de sensores. Não precisei criar uma para o loop.
• Ação: execute /builda próxima tarefa; após a fila ser esvaziada, corrija o que for necessário /validatee /reviewsinalize.
• Cadência: tão rápida quanto o trabalho permitir. Não há CI (Integração Contínua) para esperar aqui, então, ao contrário do loop padrão, este não realiza polling em intervalos regulares. Ele executa a próxima etapa assim que a anterior termina.
• Orçamento limitado: um limite para as rodadas de revisão e correção, para que uma constatação que o agente não consiga resolver não fique em loop infinito.
• Diretrizes: crie apenas branches, nunca faça merge, nunca enfraqueça um teste ou edite a especificação para que ela /reviewpasse, escale o problema em caso de baixa confiança.

Estruturalmente, são duas das formas que você já conheceu, aninhadas: uma fila (esvaziar as /buildtarefas) envolvendo uma convergência para o verde (corrigir até que /validateambas /reviewestejam limpas).

A habilidade de ciclo de construção

---
name: sdd-build-loop
description: Drive an SDD feature from its task queue to a clean, reviewed branch. Trust-gated; runs only on a feature branch.
---

You are building the feature in `.specs/$1` to a reviewed, committable state on the CURRENT feature branch. Confirm you are NOT on main first.

## Phase 1 — drain the task queue (queue shape)
- Read `.tdd-state.json` for the next task whose phase is `pending`.
- Run `/build` for that task. Let it go red → green → refactor → done and commit on completion.
- Repeat until no `pending` tasks remain.
- If one task fails its gates twice in a row, STOP and escalate. Do not skip it silently — a missing task is not a done feature.

## Phase 2 — validate and review (converge-to-green)
- Run `/validate`. If anything fails (tests, coverage, lint), fix the root cause, commit, and run `/validate` again.
- Run `/review`. If the verdict has ANY must-fix findings, fix each one with the smallest correct change, commit, and run `/review` again.
- Stop Phase 2 when `/validate` is clean AND `/review` returns APPROVE with zero must-fix. Leave should-fix and nit findings in a summary for the human; do not gold-plate.

## Success criteria
All tasks done, `/validate` clean, `/review` APPROVE with zero must-fix. Then STOP and write a handoff summary. DO NOT open a PR or merge.

## Guardrails — non-negotiable
- Work ONLY on the feature branch. NEVER commit to main.
- NEVER merge, and NEVER open the PR — that is the human's call.
- NEVER edit the spec, weaken a test, or lower a threshold to pass a gate.
- After 5 review-fix rounds without reaching APPROVE, STOP and escalate.

E o loop. Como não há um indicador de condição (CI) para aguardar, este funciona em ritmo próprio, em vez de consultar um relógio — ele simplesmente continua até que os critérios de sucesso sejam atendidos ou o orçamento se esgote:

/loop /sdd-build-loop 2026-05-09-create-new-customer

Quando o processo para, você não tem uma funcionalidade integrada. Você tem uma branch de funcionalidade com a fila de tarefas vazia, um arquivo limpo /validatee um APPROVEarquivo de origem /review, além de um resumo da tarefa pendente com os itens que deveriam ser corrigidos e os detalhes que foram deliberadamente deixados para você. Essa é exatamente a entrada que o processo de integração espera.

A parte que você precisa conquistar: confiança e compromisso automático

Quero ser sincero sobre algo, pois contradiz diretamente um conselho que dei anteriormente. Nos meus posts sobre SDD (Software Development Driver), enfatizo a importância de revisar cada tarefa e fornecer feedback ao agente para cada uma delas. “No fim das contas, é o seu nome que estará no commit.” “Ah, a IA criou o código assim” não é uma explicação aceitável em uma revisão. Continuo acreditando nisso.

Então, como posso conciliar isso com um loop que confirma automaticamente seis tarefas sem que eu precise verificar cada uma delas?

A resposta é que o ciclo de construção não elimina a revisão humana. Ele a realoca . O fluxo padrão do SDD (Software Development and Development) insere um ponto de verificação humana após cada tarefa. O ciclo de construção substitui esses pontos de verificação por tarefa por duas coisas: sensores automatizados ( /validatee /review) que realizam a verificação por tarefa e uma rodada de validação humana deliberada no final. Essa troca só é segura quando os sensores são confiáveis ​​o suficiente para substituí-lo em detalhes menores. Conquistar essa confiança é o pré-requisito e não é automático. Você progride nesse ciclo; você não começa aqui.

De onde vem essa confiança? Para mim, ela vem de um extenso conjunto de habilidades que venho desenvolvendo há meses, impulsionado inteiramente pela revisão manual de código. Sempre que encontro um trecho de código ou um padrão que não me agrada, atualizo a habilidade para que esse erro pare de acontecer. Faça isso consistentemente e, eventualmente, o Claude Code (ou qualquer outra ferramenta que você use) começará a gerar um código notavelmente próximo ao que você mesmo teria escrito, porque estará seguindo exatamente os padrões e modelos que você documentou. É nesse ponto que transferir a revisão humana de “após cada tarefa” para “após algumas tarefas” deixa de ser um risco e se torna o próximo passo natural. Mas essa confiança precisa ser conquistada primeiro: desenvolva seu próprio conjunto de habilidades antes de recorrer a esse ciclo. Não pule essa etapa, ou você gastará muito mais tempo corrigindo a saída do agente do que gastaria revisando cada tarefa manualmente.

Aqui está a lista de verificação que uso para decidir se uma determinada funcionalidade pode ser executada no loop de compilação:

• Você já implementou funcionalidades suficientes no framework, de modo que /reviewraramente surge algo com que você discorde. Se você ainda está discutindo com o revisor, é porque ele ainda não está pronto para ser seu representante.
• Suas habilidades e agentes definem os padrões da sua equipe. A estrutura já vem com minhas opiniões incorporadas. Até que você ajuste os agentes, as listas de verificação e as regras de revisão para que correspondam ao que você mesmo escreveria, o ciclo estará reforçando o gosto de outra pessoa.
• Seus sensores realmente detectam regressões. Seu limite de cobertura, regras de lint e /reviewlista de verificação precisam falhar de forma evidente nos erros que você considera importantes. Um status “verde” /validateprecisa significar algo antes de você permitir que ele configure um commit automático.
• A especificação foi aprovada /spec-reviewsem dúvidas. O loop amplifica tudo o que a especificação diz. Uma especificação vaga não produz código vago; produz código confiante, porém incorreto, mais rapidamente. Lixo entra, lixo sai em massa.
• A funcionalidade é um padrão que você já utilizou antes. Um slice CRUD com um contrato claro é um bom candidato. Uma decisão arquitetural inovadora não é — esse é exatamente o tipo de raciocínio que você não deve delegar a um loop.

E depois, os pontos inegociáveis, independentemente da sua confiança no modelo:

• Sempre em um branch de funcionalidade, nunca no principal. Toda a saída do loop é um branch que você pode descartar.
• Uma rodada obrigatória de validação humana antes da abertura do PR. Execute o aplicativo, clique nos recursos, leia as diferenças. O ciclo de compilação lhe entrega uma branch limpa; você decide se vale a pena criar um pull request. O ciclo nunca cria um para você.
• Um orçamento limitado nas rodadas de revisão e correção faz com que uma constatação que não possa ser resolvida seja encaminhada para instâncias superiores em vez de entrar em um ciclo vicioso.

Se essas condições não forem atendidas, execute o framework normalmente, tarefa por tarefa, observando atentamente cada diferença. O loop é uma otimização para os casos que você já entende, não um atalho para evitar o entendimento.

A mesma disciplina se aplica ainda mais acima no processo. No framework SDD, passo a maior parte do meu tempo revisando a especificação. A especificação precisa produzir algo pelo menos tão bom quanto o que eu teria escrito sem IA, idealmente melhor. Não pule essa revisão; uma especificação precisa é o que torna cada loop subsequente confiável em primeiro lugar. Engenharia de loops é uma técnica avançada, que você só utiliza depois de confiar em seus agentes, suas habilidades e seus sensores. E não importa quanta confiança você tenha conquistado, você ainda precisa ser responsável pelo que entrega. Seja o código escrito por IA ou manualmente, ele leva seu nome. Confiar 100% na IA é um desastre anunciado: no momento em que algo quebrar em produção, você precisa saber exatamente o que mudou e por quê, e não descobrir que ninguém, humano ou agente, realmente entende o código que foi entregue.

Ampliando o gasoduto em ambas as extremidades

O ciclo de desenvolvimento e o ciclo de construção abrangem a etapa intermediária da entrega: da especificação à integração. Mas uma funcionalidade não começa com uma especificação finalizada, e não termina no momento em que a integração contínua (CI) é aprovada. Mais dois ciclos estendem o pipeline para fora, e cada um deles envolve um ciclo em torno do trabalho tedioso e verificável que você já estava fazendo manualmente.

Loop 3: O Loop de Refinamento de Especificações (Front of the Pipeline)

O mecanismo de segurança do ciclo de compilação possui uma dependência oculta: ele só é seguro se a especificação inicial for precisa. Uma especificação vaga não produz código vago, mas sim código confiante, porém incorreto, mais rapidamente. Portanto, o ciclo que alimenta o ciclo de compilação é aquele que transforma um problema bruto do GitHub em uma especificação aprovada /spec-reviewsem nenhuma dúvida.

Este já é um loop que você executa manualmente. Meu fluxo de trabalho SDD orienta você a continuar executando /spec, responder às perguntas em aberto que surgirem e executá-lo novamente até que não haja mais nenhuma. Os sensores já existem: a lista de perguntas em aberto de /spec, e o veredito APROVADO/REPROVADO de /spec-review.

---
name: spec-sharpen-loop
description: Turn a GitHub issue into a review-passing spec, resolving what it can and escalating product decisions. Front of the pipeline.
---

You are turning issue #$1 into a spec that passes /spec-review with zero open questions. Work in rounds.

## Sensors
- The open questions /spec surfaces for this issue.
- The /spec-review verdict (PASS/FAIL) and its findings.

## Each round
1. Run `/spec` for the issue (or re-run after answers are added).
2. Triage every open question into one of two buckets:
   - RESOLVABLE from the issue, linked tickets, or existing specs: atomic acceptance criteria, missing non-goals, ambiguous wording, contract or format gaps. Resolve these and update the spec.
   - PRODUCT DECISION you cannot ground in existing material: pricing, policy, UX intent, scope trade-offs. Collect these.
3. If any PRODUCT DECISION questions remain, STOP and post them to the human as a numbered list. Wait for answers; do not invent them.
4. Run `/spec-review`. If FAIL, address the structural findings and start another round.

## Success criteria
/spec-review returns PASS with zero open questions remaining. Then STOP. The spec is ready for /plan and the build loop.

## Guardrails — non-negotiable
- NEVER answer a product-decision question yourself to force a PASS. A clean spec built on guessed intent is the most expensive failure.
- NEVER start design or code. This loop produces a spec, nothing else.
- If the same question reappears after being answered, escalate; the issue itself may be underspecified.

/loop /spec-sharpen-loop 1

Este loop tem uma cadência que os outros não têm: é no ritmo do ser humano . Ele avança uma rodada cada vez que você responde às perguntas sobre o produto que ele apresenta e, em seguida, bloqueia novamente. Você não está esperando por um relógio ou por CI; você é o sensor que ele está aguardando. Isso é intencional. Este é o único loop que pausa internamente para um humano de propósito, porque o atalho proibido aqui é o mais perigoso em todo o pipeline: responder a uma pergunta sobre o produto com um palpite plausível apenas para /spec-reviewpassar. Todos os loops subsequentes confiam nesta especificação. Se estiver errada, eles construirão, testarão e lançarão o produto errado com grande eficiência.

Ciclo 4: O Ciclo de Revisão-Resposta (Fim do Pipeline)

O ciclo de integração contínua (CI) entrega um PR aprovado para um revisor humano. Esse revisor deixa comentários e, em seguida, alguém precisa analisá-los: fazer a alteração, enviar (push), responder, repetir, até que todas as questões sejam resolvidas. Essa etapa de “analisar os comentários” é um ciclo de fila e é o inverso do ciclo de integração contínua. O ciclo de integração contínua leva o PR para a CI; este o leva para os revisores humanos.

---
name: pr-review-response
description: Resolve actionable human review comments on a PR until none remain and gates stay green. End of the pipeline.
---

You are responding to human review on PR #$1. Do exactly one pass.

## Sensors
- Run `gh pr view $1 --json reviews,comments,reviewThreads` and list every UNRESOLVED thread.
- Run `gh pr checks $1` for current gate status.

## Triage each unresolved thread
- CHANGE REQUESTED (do X, rename Y, handle case Z): make the smallest correct change, commit, push, and reply in the thread linking the commit. Do NOT resolve the thread — the reviewer does that.
- QUESTION (why did you...?): reply in the thread with an explanation. Change code only if the honest answer is "you're right, fixing it".
- DISAGREEMENT or ambiguous intent: STOP and escalate to your human. Do not argue in the thread, and do not silently comply.

After any code change, re-run the ship-loop gates so a review fix does not re-break CI.

## Success criteria
No unresolved actionable threads remain AND all gates are green. Then STOP. Do not merge.

## Guardrails — non-negotiable
- NEVER merge, approve, or resolve a reviewer's thread.
- NEVER push back on a reviewer; escalate disagreements to your human.
- One logical change per commit; never force-push.
- If a comment needs a product or architecture decision, escalate.

/loop 15m /pr-review-response 1234

Os revisores deixam comentários ao longo de horas, não segundos, então este loop verifica em intervalos como o loop principal. A diferença está no que ele verifica: a atividade de revisão humana em vez da integração contínua. A parte difícil não é a edição, mas sim a triagem. Um loop que trata cada comentário como uma “solicitação de alteração” reescreverá o código diligentemente em resposta a um revisor que estava apenas fazendo uma pergunta, enquanto um loop que trata cada comentário como uma pergunta ignorará solicitações de alteração reais. Deixar clara a diferença e forçar uma escalação em caso de discordância é o que impede o loop de discutir com o revisor em seu nome.

Compondo os Loops: Um Pipeline de Problema à Fusão

Agora, os quatro processos se unem em um único fluxo. O julgamento humano se concentra em exatamente dois pontos: responder a perguntas genuínas sobre o produto no início e decidir se uma ramificação merece um pull request no meio. Todo o resto é um ciclo convergindo para um objetivo verificável.

Observe a coluna de cadência. Cada ciclo é executado em uma velocidade diferente, e nenhuma delas é arbitrária. O ciclo de refinamento de especificações tem um ritmo humano, pois aguarda suas decisões. O ciclo de construção tem um ritmo próprio, pois seus sensores são locais e instantâneos. O ciclo de envio verifica a cada dez minutos, pois seu sensor é de integração contínua (CI). O ciclo de revisão e resposta verifica a atividade de revisão, pois essa é a velocidade com que os humanos comentam. A cadência de cada ciclo é ditada pela velocidade com que o que ele monitora pode realmente mudar. Ajuste a cadência aos seus sensores e você nunca pagará por uma verificação que não lhe forneça nenhuma informação nova.

Os dois portões humanos são os menores possíveis de serem de forma responsável. Você não está escrevendo a especificação do zero, revisando cada tarefa, supervisionando cada correção de CI ou editando manualmente cada detalhe da revisão. Você está tomando duas decisões — “essa intenção está correta?” e “vale a pena um PR para essa branch?” — cada uma delas respaldada por um loop que realizou o trabalho mecânico e parou para questionar. Esse é o objetivo principal da engenharia de loops: concentrar a convergência nos loops e dedicar sua atenção às decisões que nenhum loop deveria tomar.

Guarda-corpos para qualquer circuito fechado

Todos os quatro loops acima se baseiam no mesmo pequeno conjunto de regras. Um loop funciona sem supervisão; esse é o objetivo principal, e também o risco principal. Essas são as salvaguardas sem as quais eu não enviaria um loop.

• Defina limites para tudo. Cada loop precisa de um número máximo de iterações e, idealmente, também de um prazo final. Um loop sem limite não é autônomo, é um processo descontrolado.
• Nunca permita que um loop se funda. Ambos os loops devem estar prontos para mesclar e parar. A mesclagem deve ser feita por um humano. Essa regra simples evita o pior cenário possível: uma alteração automatizada sendo implementada diretamente na branch principal.
• Proíba explicitamente a manipulação de métricas. Qualquer loop que busque um número ou um veredito tentará satisfazê-lo da maneira mais fácil: desativando um teste instável, escrevendo testes sem asserções, editando a especificação para que /reviewpare de reclamar. Deixe claro os atalhos proibidos, pois o agente não os inferirá.
• Torne cada ação revisável e reversível. Uma alteração lógica por commit, mensagens convencionais, apenas branches, nunca force-push. Quando um loop faz algo errado na iteração 7, você quer reverter um commit, não desfazer uma bagunça já consolidada.
• Aumente a intensidade quando a confiança estiver baixa. A coisa mais valiosa que um loop pode fazer quando está travado é parar e admitir isso. “Tentei essas três correções e nenhuma funcionou, aqui está o que observei” é melhor do que um décimo commit desesperado.
• Ajuste a cadência aos seus sensores. Consulte os sensores em intervalos regulares apenas quando estiver aguardando algo lento, como um CI (intervalo de confiança). Quando os sensores forem locais, deixe o loop rodar na velocidade que o trabalho permitir.

Quando usar um loop e quando não usar.

Um loop é a ferramenta certa quando três coisas são verdadeiras: o objetivo é objetivamente verificável (um script ou um sensor pode dizer sim ou não), o progresso é incremental (cada iteração aproxima-se mensuravelmente do objetivo) e o trabalho é suficientemente tedioso para que a convergência domine o raciocínio. Levar um PR à aprovação é um exemplo. Esvaziar uma fila de tarefas bem especificada também é um exemplo, desde que você confie na estrutura utilizada .

Um loop é a ferramenta errada quando o objetivo é subjetivo (“tornar este design de API elegante”), quando não há um sensor confiável ou quando a parte difícil é uma única decisão em vez de uma sequência de etapas mecânicas. Se você não conseguiria escrever a verificação “terminamos?” como algo que retorne um booleano, você ainda não tem um loop. Você tem uma conversa e deve apenas ter a conversa.

O erro que vejo com mais frequência é recorrer a um loop para evitar pensar nos critérios de sucesso. Mas os critérios são o trabalho em si. Uma vez que você consiga definir precisamente o que significa “concluído” e como um sensor o detectaria, o loop praticamente se escreve sozinho. Até que isso aconteça, nenhuma iteração será suficiente, porque o agente não tem nada em que convergir.

Considerações finais

Solicitar a um agente que corrija um teste com falha é fácil. Projetar um sistema onde um ciclo aprimora a especificação, outro constrói o recurso em uma ramificação limpa e revisada, um humano toma as duas decisões importantes e mais dois ciclos conduzem a solicitação de pull request através da integração contínua e revisão humana — isso é engenharia.

Os loops não são os comandos inteligentes no meio do processo. São os objetivos que você pode verificar, os sensores que permitem ao agente enxergar, os orçamentos que o impedem de prosseguir e as salvaguardas que o mantêm honesto. Se esses elementos estiverem corretos, o agente no meio do processo se torna irrelevante.

Passamos anos aprendendo a escrever código que funciona. Engenharia de loops é aprender a escrever as condições sob as quais o código de um agente pode ser executado — e ser honesto sobre quais dessas condições você realmente conquistou. Essa é a habilidade mais duradoura, e é nela que eu investiria agora.

Se você quiser conhecer os fundamentos sobre os quais isso se baseia, o restante da série os aborda:

• Programação intuitiva, mas pronta para produção: um ciclo de feedback orientado a especificações para desenvolvimento assistido por IA.
• Engenharia de Aproveitamento: A Camada Ausente no Desenvolvimento de IA Orientado por Especificações
• Desenvolvimento orientado a especificações na prática: entrega de ponta a ponta com Spring Boot e Angular