A engenharia de loop não faz o trabalho inteiro em um salto gigante. Ela o faz em passadas — voltas curtas e repetidas em que cada volta olha para a realidade, faz exatamente uma mudança e checa essa mudança contra algo real antes de a próxima volta começar. Esta lição percorre uma passada completa, tempo a tempo, para que você consiga ler o que está acontecendo quando o harness está rodando.
Imagine que você pede ao harness para corrigir um bug, construir uma funcionalidade ou lapidar um texto. Ele não vai tentar fazer tudo em uma explosão heroica e depois te entregar uma pilha pronta torcendo para funcionar. Em vez disso, ele trabalha em passadas. Uma passada é uma volta curta e completa do mesmo ciclo de seis passos, e o harness continua dando passadas até o trabalho estar comprovadamente terminado.
Toda passada segue exatamente a mesma forma: olhar onde as coisas realmente estão, decidir qual é o próximo movimento mais importante, fazer só esse único movimento, checá-lo contra algo real e decidir o que corrigir em seguida — e então repetir o loop. A disciplina é o ponto: uma mudança por vez, cada uma checada antes de a próxima começar. É isso que impede que uma execução longa e sem supervisão derrape para a bagunça.
Pense nisso como subir uma escada no escuro. Você não salta para o topo — nem consegue vê-lo. Você apalpa o próximo degrau, põe seu peso nele para garantir que aguenta, e só então alcança o seguinte. Cada degrau é uma passada: um pequeno movimento que você de fato testa antes de confiar nele. Pule o teste e avance três degraus de uma vez, e o primeiro degrau fraco te derruba até embaixo.
Uma passada é: LEARN → ANALYZE → EXECUTE uma unidade delimitada → VERIFY na fronteira real → DECIDE → (loop). O SCOPE fica antes da primeira passada e define o que "pronto" significa; é o contrato contra o qual toda passada posterior é medida. O loop se repete até que as condições done-when do escopo estejam todas atendidas em uma fronteira real, não na imaginação do modelo.
Uma tarefa longa feita de uma vez só acumula suposições não verificadas: ao final, um erro lá no começo moldou silenciosamente tudo o que veio depois. Delimitar cada passada a uma única mudança verificada transforma um monólogo frágil em uma sequência de checkpoints. Se a passada 7 quebra algo, você sabe que foi a passada 7 — as seis anteriores foram cada uma provadas boas na sua própria fronteira.
Antes de o loop girar uma única vez, há um contrato: o que "pronto" de fato significa aqui? Não um sentimento — uma condição checável. "Pronto" não é "os testes parecem passar" ou "ficou melhor". É algo que você poderia entregar a um estranho, e ele concordaria, só de olhar, se você atingiu ou não. "A página de login responde em menos de 300 ms para 95% das requisições." "Todos os 14 testes unitários passam e o build está verde." "O artigo é legível no nível do 9º ano e toda afirmação tem uma fonte."
Este é o único lugar em que você, o humano, está firmemente no comando. Você define o alvo — o done-when mensurável — ou aprova o que o harness propõe. Tudo o que o loop faz depois está a serviço desse alvo, então se o alvo é nebuloso, a execução inteira é nebulosa. Um "pronto" nítido e mensurável é a coisa de maior alavancagem que você fornece.
Pense nisso como uma linha de chegada pintada na pista. Os corredores podem dosar o ritmo, disparar ou relaxar — mas ninguém discute quem venceu, porque a linha está bem ali no chão. Um "pronto" mensurável é essa linha pintada. Sem ela, toda passada é um corredor perguntando "já chegamos?" e recebendo uma resposta diferente a cada vez.
No harness, o escopo é capturado como um pequeno conjunto de condições done-when — cada uma observável em uma fronteira (um teste, um build, uma resposta HTTP, um diff de arquivo, uma página renderizada). A próxima lição cobre os gates que as impõem; por ora, a ideia central é que o loop tem um alvo fixo para mirar, escrito antes de qualquer mudança ser feita.
Para um pedido cru e vago, o front-end Forge existe justamente para transformar "deixa melhor" em condições done-when mensuráveis antes de o loop começar (você conhecerá o Forge no Módulo 2). De qualquer forma, a regra é a mesma: sem pronto mensurável, sem loop.
Aqui está uma passada completa, em ordem. Leia como uma história — cada tempo entrega seu resultado ao seguinte.
LEARN — olhe primeiro. A passada abre lendo a realidade: o estado atual do código ou documento, o escopo e quaisquer fontes confiáveis. Ela inspeciona os artefatos reais em vez de adivinhar o que provavelmente contêm. Partir de um palpite é a forma mais barata de arruinar uma passada inteira.
ANALYZE — nomeie a lacuna, depois escolha UMA. Com a realidade em mãos, ela compara onde as coisas estão com onde o "pronto" diz que deveriam estar, e agrupa a lacuna em movimentos candidatos. Cada candidato recebe uma avaliação rápida — Fit, Risk, Proof, Blocker, Next — e desse ranking ela escolhe exatamente uma unidade de trabalho para fazer nesta passada. Não três. Uma.
EXECUTE — faça só aquela única coisa. Ela faz a única mudança escolhida e nada mais. A tentação do "já que estou aqui, também conserto…" é exatamente o que o loop recusa, porque uma passada que muda cinco coisas não consegue te dizer qual delas quebrou.
VERIFY — cheque de verdade. Ela então testa a mudança em uma fronteira real — roda o teste, builda o projeto, carrega a página, faz o diff do arquivo — e olha o resultado de fato. Não "isso deveria funcionar". Prova.
DECIDE — melhore, depois repita o loop. Com base no que a verificação mostrou, ela decide o que corrigir em seguida: normalmente o próprio artefato, mas às vezes as instruções que guiam o trabalho. Então inicia uma nova passada em LEARN. O ciclo se repete até toda condição done-when ser atendida.
Pense nisso como um cozinheiro cuidadoso provando enquanto cozinha. Olhe a panela (LEARN), decida que o prato precisa de sal e só de sal (ANALYZE → escolha uma), adicione uma pitada (EXECUTE), prove (VERIFY), e então decida o próximo ajuste único (DECIDE). Um cozinheiro que joga sal, pimenta, limão e pimenta-malagueta tudo de uma vez e prova só no fim não faz ideia do que mudar — e o loop também não faria.
LEARN lê o estado a partir da fronteira real (sistema de arquivos, git, processo em execução, docs confiáveis) — nunca da memória defasada. ANALYZE produz uma lista ranqueada e seleciona uma única unidade delimitada. EXECUTE aplica essa única unidade. VERIFY roda a checagem na fronteira e registra o resultado observado. DECIDE escolhe o próximo alvo — artefato ou prompt — e reentra no loop. O done-when do SCOPE é a condição de término.
LEARN, ANALYZE, EXECUTE e VERIFY recebem cada um um tratamento mais completo ao longo do curso; os gates que tornam o VERIFY confiável são todo o conteúdo da Lição 3. O trabalho desta lição é a forma: que esses tempos rodam nesta ordem, uma vez por passada, em toda passada.
Os mesmos seis tempos, desenhados como o ciclo que formam. O escopo define o alvo uma vez; depois os cinco tempos internos giram, de novo e de novo, com a verificação como o gate que decide se você avança ou volta para corrigir.
ANALYZE é onde uma passada conquista seu foco. Olhar para a realidade normalmente revela várias coisas que poderiam ser feitas — um teste falhando aqui, um caso de borda faltando ali, uma frase tosca, uma query lenta. O loop não ataca todas elas. Primeiro ele agrupa a lacuna (junta o que falta em uma lista curta de movimentos candidatos), depois dá a cada candidato uma avaliação rápida, e escolhe o único melhor para fazer nesta passada.
A avaliação faz cinco perguntas simples sobre cada candidato:
A vencedora é a única unidade com o melhor equilíbrio: Fit alto, Risk gerenciável, algo que você consegue de fato provar, idealmente um Blocker que libera trabalho posterior. Todo o resto espera por uma passada futura. Esta é a regra que mantém o loop honesto — uma unidade delimitada por passada, escolhida de propósito, não o que for mais tentador.
Pense nisso como a triagem em um pronto-socorro. Cinco pacientes chegam de uma vez. A enfermeira não atende os cinco pela metade; ela avalia cada um pela urgência e pelo que dá de fato para ajudar agora, e o mais crítico vai primeiro. Os outros não são esquecidos — são os próximos da fila. ANALYZE é essa enfermeira de triagem para o trabalho.
Os cinco eixos são uma rubrica rápida e repetível, não um modelo pesado de pontuação. Proof é decisivo: um candidato que não pode ser verificado em uma fronteira real nesta passada é despriorizado, porque uma mudança não verificável não pode fechar com segurança. Blocker captura a ordem de dependência — escolher a unidade que destrava outras três costuma ter mais alavancagem do que uma mudança vistosa, mas isolada.
Uma unidade delimitada é aquela cujo efeito e verificação cabem ambos dentro de uma única passada — pequena o bastante para executar e checar antes do próximo LEARN. "Refatorar o módulo inteiro" não é delimitado; "extrair esta única função e manter os testes verdes" é. Se um candidato é grande demais para delimitar, o movimento certo costuma ser escolher a unidade menor que o divide.
A regra mais importante de todas no loop é a que soa quase simples demais: faça exatamente uma coisa delimitada por passada. Não zero. Não cinco. Uma.
Por que não cinco? Porque, se você muda cinco coisas e então verifica, e o resultado está errado, não dá para dizer qual das cinco causou. Você perdeu aquilo para que o loop serve — a capacidade de apontar para uma única mudança e dizer "esta está provada boa". Fazer em lote troca um instante de velocidade aparente por um pântano de depuração depois.
Por que não zero? Porque uma passada que olha, pensa e então não faz nada é movimento desperdiçado. O loop nunca fica ocioso: toda passada ou entrega uma mudança verificada ou bate num blocker real que ela expõe claramente. "Vou esperar para ver" não é uma passada; é uma estagnação, e ao longo de uma execução longa e sem supervisão, estagnações são como o progresso morre em silêncio.
Pense nisso como uma cirurgia, uma incisão por vez. Um cirurgião não faz cinco cortes de uma vez "para ganhar tempo", e também não fica paralisado sobre o paciente. Cada ação deliberada é feita, checada, e só então a próxima é tomada. O paciente — seu código, seu documento — sobrevive justamente porque nada acontece que não seja um movimento controlado e verificado.
Passadas de uma unidade tornam uma execução trivialmente bissectável: cada checkpoint isola exatamente uma mudança contra sua verificação. Uma regressão introduzida na passada N é atribuível à passada N por construção — não existe o "qual dessas edições causou?" porque cada passada fez uma edição e a provou. É isso que permite que uma execução autônoma longa continue depurável.
A disciplina corta para os dois lados. Um LLM conduzindo o loop precisa converter cada passada ou em uma unidade entregue e verificada ou em um blocker explicitamente exposto — nunca um no-op, nunca um "deixa eu pensar a respeito" sem saída. Passadas ociosas queimam orçamento e corroem a observabilidade, já que o humano que observa o log não consegue mais saber se há progresso acontecendo.
Uma mudança não está pronta porque parece pronta. Está pronta porque você a checou contra a realidade e a realidade concordou. Essa checagem é o VERIFY, e ela sempre acontece em uma fronteira real — o lugar de fato onde a verdade mora. Se a unidade era uma correção de código, você roda o teste e lê o resultado. Se era uma mudança de build, você builda o projeto. Se era uma página, você carrega a página. Se era uma frase, você a relê no contexto.
O que o VERIFY recusa é a mentira confortável: alegar sucesso de memória, ou confiar num mock que sempre diz sim. O harness tem uma regra dura aqui — verifique rodando a checagem de verdade, nunca simulando-a na sua cabeça e declarando vitória. Uma passada que "deveria passar" não passou. Só a fronteira pode dizer isso.
Pense nisso como um detector de fumaça versus o seu próprio nariz. Você pode não sentir cheiro nenhum e ter certeza de que a casa está bem. O detector é a fronteira real — ele não se importa com quão confiante você está; ele amostra o ar de fato. O loop confia no detector, não no palpite. Essa é a diferença entre "acho que funciona" e "funciona".
Este é o coração do que a Lição 3 chama de Proof Gate: toda conclusão alegada precisa ser respaldada por saída observada na fronteira real — o exit code de um test runner, um log de build, um status HTTP, um diff renderizado. "Alegação" e "mock" explicitamente não são evidência. Uma unidade só avança quando sua condição done-when é observada como verdadeira, não afirmada como verdadeira.
As fronteiras são concretas e variadas: um teste unitário/de integração, um compilador, um linter, um servidor em execução atingido por uma requisição, um screenshot, um diff de arquivo revisado contra a especificação, ou evidência web ao vivo puxada por uma ferramenta. A habilidade está em escolher uma fronteira que de fato exercite a mudança — um teste que não toca o caminho alterado não prova nada.
A verificação acabou de te contar a verdade sobre sua única mudança. DECIDE é o que você faz com essa verdade. Normalmente a resposta é direta: escolha a próxima melhoria única no artefato — o próximo bug, a próxima peça faltante — e inicie uma nova passada em LEARN.
Mas há um movimento mais sutil e poderoso. Às vezes o que precisa ser corrigido não é o artefato — são as instruções que conduzem o trabalho. Se passada após passada continua errando do mesmo jeito, a mudança mais esperta pode ser afinar o próprio prompt ou o escopo, para que a próxima passada mire melhor. O loop tem permissão para melhorar a si mesmo, não só sua saída. Então, de qualquer forma, ele repete o loop — e segue repetindo até toda condição done-when ser atendida.
Pense nisso como um GPS recalculando a rota. Depois de cada trecho de estrada ele checa onde você de fato está contra onde deveria estar. Normalmente ele só diz "siga em frente" (melhore o artefato). Mas se você continua saindo do curso, ele não repete a mesma curva errada mais alto — ele recalcula a rota inteira (melhore o prompt). Mesmo destino, direções mais espertas.
DECIDE pode mirar qualquer uma das superfícies editáveis: o artefato (o código, doc ou design em construção) ou o prompt/escopo (as instruções e o done-when que guiam o loop). Quase-acertos repetidos no mesmo eixo são o sinal clássico de que é hora de melhorar o prompt em vez de moer o artefato — uma metacorreção barata que reorienta toda passada subsequente.
O loop termina quando as condições done-when do escopo são todas observadas como verdadeiras em suas fronteiras — isso é convergência. Se uma passada expõe um blocker que precisa de uma decisão humana, o loop pausa em um handoff claramente marcado em vez de adivinhar. Caso contrário, ele segue dando passadas; "melhore até convergir" é a regra de parada literal.
Enquanto o loop roda — muitas vezes por horas, sem supervisão — você não fica sentado conduzindo. Você o observa. O harness escreve um registro contínuo, o LOOP-LOG.md, que transforma as passadas invisíveis em algo que você lê num relance: quantas passadas aconteceram, quantas unidades de fato foram entregues, com que frequência a verificação passou, e se algo está bloqueado. Esta é a sua janela de observabilidade. Você define o "pronto"; o log deixa você confirmar que o loop está convergindo honestamente para ele.
O painel abaixo é essa janela, ao vivo. Os quatro blocos no topo são os sinais vitais do loop; a tabela tem uma linha por unidade de trabalho, cada uma com um selo do seu estado. Aperte Rodar uma passada para avançar o loop em uma volta, ou ligue o Auto-loop para ver as passadas correrem como correriam numa execução AFK real.
LOOP-LOG.md — objetivo auth-refresh
uma unidade delimitada por passada · verifique na fronteira real
| Unidade de trabalho | Estado | Fit | Último verify (fronteira real) |
|---|
Uma única lista de unidades alimenta tanto a tabela quanto a faixa de resumo. Cada passada avança exatamente uma unidade — movendo uma unidade na fila para "verificando", ou resolvendo uma unidade "verificando" em "entregue" (verify passou) ou "bloqueada" (verify falhou na fronteira). Os blocos de sinais vitais são recalculados a partir dessa lista a cada passada: passadas dadas, unidades entregues, a taxa contínua de aprovação no verify, e passadas ociosas mantidas em zero. A faixa geral lê a pior unidade: qualquer blocker a deixa âmbar, caso contrário ela reporta convergência saudável.
Passadas dadas é o batimento cardíaco do loop. Unidades entregues ao longo das passadas é a sua vazão verdadeira — trabalho verificado, não tentativas. Taxa de aprovação no verify é o sinal de honestidade; uma taxa caindo diz que o prompt talvez precise melhorar (de volta a DECIDE). Passadas ociosas precisam ficar em zero — no instante em que sobe, o loop está estagnando em vez de progredir. Ler estes quatro é exatamente como um humano supervisiona uma execução AFK sem tocá-la.
O loop é um único ciclo, mas três tipos diferentes de ator o tocam, cada um com um trabalho claro.
Você, o humano, é dono das bordas. Você define ou aprova o done-when mensurável no início, e depois basicamente observa — lendo o LOOP-LOG.md para confirmar que a execução está convergindo honestamente. Você só volta a intervir quando o loop expõe uma decisão real que ele não deveria tomar sozinho. Você é o supervisor, não o condutor.
O LLM é o motor de uma passada. Ele roda os seis tempos e obedece à regra de ferro: exatamente uma unidade delimitada por passada — nunca agrupe várias mudanças, nunca fique ocioso num no-op. A cada passada ele produz ou uma mudança verificada ou um blocker claramente exposto. É essa disciplina que torna sua saída longa e sem supervisão confiável.
Os agentes são como as passadas se espalham entre as ferramentas. Uma única passada pode ser entregue a um modelo de linha de comando diferente do anterior — uma passada conduzida por um CLI, a seguinte por outro — para que a ferramenta mais forte para cada passo execute aquele passo. A camada de orquestração despacha uma passada para qualquer agente que se encaixe, e o log mantém tudo legível.
Pense nisso como um set de filmagem. O diretor (você) define a visão e observa o monitor, mas não opera a câmera. Cada tomada (passada) é feita pela equipe especialista certa para ela — e a ordem do dia (o log) deixa o diretor ver cada tomada sem ficar atrás de cada lente.
Em uma execução multi-agente, o orquestrador pode despachar qualquer passada individual para um agente de linha de comando específico em modo headless — por convenção cli -p "<the one bounded unit for this pass>". Como cada passada é delimitada e verificada de forma independente, não importa que a passada 4 tenha rodado em um modelo e a 5 em outro; a checagem na fronteira é o que certifica o resultado, não a identidade do motor. Um elenco de agentes é escolhido de antemão, e o validador de uma passada nunca é o mesmo agente que a produziu.
Tudo no loop interno roda AFK (away-from-keyboard): o humano tem observabilidade, não um volante. O único lugar em que uma execução bloqueia para uma pessoa é um handoff deliberado e pronto para decisão. Observar o LOOP-LOG.md (e, mais tarde, um arquivo de review) é a superfície de supervisão; ela nunca exige que o humano execute um passo por conta própria.
Nada disso é abstrato. Uma passada deixa um rastro que você consegue ler. Aqui está o tipo de entrada que o loop anexa ao LOOP-LOG.md depois de uma única passada — repare que ela registra os seis tempos: o que aprendeu, a única unidade que escolheu e por quê, o que fez, a verificação real que rodou, e a decisão para a próxima vez.
## passada 7 — 2026-06-14 09:41 learn leu src/auth/refresh.ts + 14 testes; done-when do escopo = "todos os testes de auth verdes" analyze lacuna agrupada em 3 candidatos; avaliados em Fit/Risk/Proof/Blocker/Next escolhido → "tratar retry de token expirado" (Fit:high Risk:low Proof:test Blocker:yes) execute editou refresh.ts: faz retry uma vez no 401, depois expõe o erro (1 unidade, sem lote) verify $ npm test -- auth/refresh ✓ 14 passing (fronteira real: test runner exit 0) decide artefato ok; próxima unidade = "rotacionar refresh token no sucesso" → loop
Quando o harness conduz um objetivo, o log fica na raiz do diretório de trabalho. Para ver as passadas chegarem em tempo real, dê tail nele:
seu terminal$ cat LOOP-LOG.md # lê toda a execução até agora $ tail -f LOOP-LOG.md # acompanha novas passadas conforme chegam
Uma passada despachada para um agente de linha de comando específico é lançada em modo headless com a unidade delimitada como seu prompt:
orquestrador — despacha uma passada$ cli -p "EXECUTE one unit: handle expired-token retry in refresh.ts; verify with: npm test -- auth/refresh"
O agente exato por trás de cli pode diferir de passada para passada — o que certifica o resultado é a verificação na fronteira, não qual motor a rodou.
O que fica
Toda passada é uma unidade delimitada, aprendida da realidade, executada sozinha e provada em uma fronteira real antes de o loop girar de novo. Esse é todo o motor: pequenos passos verificados, repetidos até o "pronto" ser observavelmente verdadeiro.
Três perguntas rápidas. Escolha uma resposta e o painel te diz por que está certa ou errada — recuperar bate reler.
Q1Durante o ANALYZE, o loop encontra cinco coisas que poderiam ser corrigidas. Quantas ele faz nesta passada?
Q2O que "VERIFY na fronteira real" descarta?
Q3Numa execução AFK, qual é o trabalho principal do humano depois que o loop está rodando?