Antes que qualquer uma das partes móveis faça sentido, uma ideia precisa se fixar: o loop-engineering-suite é um harness — um loop de verificar-e-melhorar que conduz qualquer tarefa até uma conclusão mensurável e, então, entrega e publica um curso sobre ela. Ele funciona da mesma forma não importa qual modelo de IA ou ferramenta de linha de comando esteja fazendo o trabalho, e três públicos diferentes o leem ao mesmo tempo: o humano que observa, o modelo que executa o método e os agentes que são o runtime.
Um harness é o equipamento que permite controlar algo poderoso com segurança — o arnês de um alpinista, a estrutura em volta de um motor de testes. O loop-engineering-suite é exatamente isso, mas para realizar trabalho com IA. Você o envolve em torno de uma tarefa — escrever código, corrigir um bug, rascunhar um prompt, produzir um documento — e ele leva essa tarefa de um pedido bruto até um resultado finalizado e conferido duas vezes.
Não é uma única ferramenta, e não está preso a uma única IA. É um jeito de trabalhar: uma pequena máquina com um único batimento. A cada batida, faz quatro coisas em ordem. Ela olha como as coisas realmente estão agora. Escolhe um próximo movimento — não dez. Faz esse único movimento. Então prova que o movimento funcionou conferindo a coisa real — rodando o teste de verdade, abrindo a página de verdade — nunca simplesmente declarando sucesso. Depois bate de novo.
O batimento continua até a tarefa cruzar uma linha de chegada que você escreveu antes de começar: um done-when simples e mensurável ("o teste passa", "a página carrega em menos de um segundo"). No instante em que cruza essa linha, o harness faz mais duas coisas por conta própria — ele entrega um curso visual autossuficiente que explica o que construiu (um curso exatamente como o que você está lendo) e publica esse curso para que você receba um link que pode compartilhar.
É esse último hábito que justifica a existência desta lição. O suite inteiro foi feito para ser compreendido, não apenas executado — então o ponto natural de partida é a ideia de que um loop disciplinado, mais uma linha de chegada escrita, mais um curso no fim, é a forma inteira da coisa. Todo o resto deste curso é detalhe pendurado nessa estrutura.
Pense nisso como… uma equipe de boxes conduzindo um carro de corrida por voltas repetidas. A cada volta: confira o carro, mude exatamente uma coisa — um pneu, não quatro palpites de uma vez — mande-o de volta à pista, então leia o tempo de volta no painel de cronometragem para provar que a mudança ajudou. Ninguém confia num mecânico que diz "pareceu mais rápido"; confiam no relógio. A corrida termina numa meta de voltas definida antes da bandeira verde. Isso é o harness: olhar, mudar uma coisa, medir no relógio real, repetir até uma linha de chegada definida com antecedência.
O suite é agnóstico a modelo e a agente. A unidade de trabalho é uma passagem de um ciclo de cinco etapas: LEARN → ANALYZE → EXECUTE uma unidade delimitada → VERIFY no boundary real → DECIDE (melhorar o artefato, ou melhorar o prompt que o conduz, e então repetir). O loop só para quando um done-when escrito e mensurável é satisfeito — nunca por uma sensação de que provavelmente terminou.
"Verificar no boundary real" é a frase que sustenta tudo: pronto se estabelece por evidência produzida onde o trabalho realmente encontra a realidade (uma execução de teste real, uma resposta HTTP ao vivo, um build que compila), nunca por um modelo afirmando isso em prosa. Esse ponto de checagem se chama Proof Gate, e é a espinha de todo o método — a lição 3 é dedicada a ele.
Cruzar o done-when dispara dois entregáveis permanentes: um curso visual-teach (o resultado legível por humanos, um arquivo HTML autossuficiente com CSS, SVG e JS inline — sem etapa de build) e uma etapa de Publish (um gist privado e, opcionalmente, uma página hospedada). Entregar e publicar não são polimento opcional; são parte do que "pronto" significa aqui.
Aqui está a ideia inteira em uma só tela. Um loop interno conduz o trabalho; três públicos sentam ao seu redor, cada um com uma função diferente. O loop se repete até o done-when ser atingido, então o resultado se desdobra em um curso entregue e um link publicado.
O que torna este harness incomum é que três leitores muito diferentes estão sempre presentes ao mesmo tempo, e o sistema foi projetado para que cada um tenha uma função claramente separada. Manter essas funções separadas não é burocracia — é exatamente o que mantém o trabalho honesto. Aqui está quem eles são e o que cada um faz.
O humano observa e decide — e, crucialmente, não está no caminho do trabalho. Quando o harness roda, ele roda sozinho; seu papel é observar o painel de cronometragem e tomar apenas as decisões que cabem a uma pessoa. Você acompanha por dois arquivos de texto simples que o loop mantém atualizando: LOOP-LOG.md, um diário corrente de cada passagem (o que ele olhou, o único movimento que escolheu, se a prova passou), e review.md, um relato de qualidade sobre o que está sólido e o que está frágil. Você intervém em exatamente um tipo de momento — uma decisão que é irreversível, voltada para fora, ou sobre intenção de negócio (dinheiro se movendo, algo indo a público, um rumo que não dá para desfazer barato). Para isso, o harness pausa e lhe entrega uma pergunta clara, pronta para decisão. Todo o resto, ele resolve sem você.
O modelo — a LLM conduzindo uma passagem — executa o método e honra os portões. Sua disciplina é o produto: olha antes de saltar, escolhe exatamente um movimento delimitado, o faz e então o prova no boundary real — rodando a coisa de verdade e lendo o resultado de verdade, nunca uma afirmação, nunca um mock, nunca um selo verde que ele mesmo colou no próprio trabalho. Depois de qualquer mudança que toque o caminho que acabou de provar, ele prova de novo, porque o estado que leu um instante atrás pode já estar desatualizado. E nunca fica ocioso: cada passagem ou avança o trabalho ou melhora o prompt que o conduz. Quando genuinamente não consegue alcançar o boundary real, ou o próximo movimento é uma decisão só do humano, ele não finge progresso e não trava para sempre — ele para e devolve uma pergunta pronta para decisão.
Os agentes são o runtime — as mãos que de fato giram as chaves. O método é executado por um modelo, mas o trabalho acontece dentro de ferramentas concretas de linha de comando: Claude Code, Codex, Kimi, Grok e outras, incluindo um Council de vários modelos votando juntos. Um orquestrador entrega uma unidade delimitada por vez a um desses agentes pelo seu modo headless de linha de comando, de modo que passagens diferentes possam rodar em qualquer agente que seja o melhor ou esteja disponível para aquele movimento. O harness inteiro — suas skills e instruções — é instalado em cada um deles, então o mesmo jeito de trabalhar está presente não importa qual ferramenta pegue a próxima unidade. Uma regra é sagrada e percorre o suite inteiro: o agente que confere um resultado nunca é o agente que o construiu.
Pense nisso como… uma equipe de corrida. O chefe de equipe apenas observa o painel de cronometragem e toma as grandes decisões — parar nos boxes agora ou seguir em frente (o humano). O regulamento que todos seguem — uma mudança por volta, sempre medida no relógio — é a disciplina (o modelo). Os mecânicos com as ferramentas são os que de fato estão sob o carro, e um inspetor diferente aprova o trabalho que não foi quem o fez (os agentes). Mesma equipe, três papéis, nunca borrados — que é exatamente por que nada passa despercebido.
O papel do humano é observabilidade AFK (away-from-keyboard). Você não executa unidades e nunca recebe uma tarefa de QA — a validação é feita pelo harness, por um agente que não é o que construiu a coisa. Você é chamado apenas num ponto de bifurcação genuinamente só do usuário, apresentado como um handoff pronto para decisão. Os arquivos que você lê são LOOP-LOG.md (o diário por passagem) e review.md (o relatório de observabilidade de QA); uma visão de status resume o progresso. Você consome; não executa.
# LOOP-LOG · blindagem do search-handler passagem 007 LEARN leu services/search/handler.py + saída do teste ANALYZE bucket=correctness · pick=empty-query guard (1 unidade) EXECUTE adicionou guard + 1 teste VERIFY execução real: pytest -k empty_query → PASS ✓ prova no boundary DECIDE artefato melhorado · faltam 2 critérios de done-when → loop passagem 008 LEARN releu o estado (repo mudou desde a 007) ...
Uma passagem = uma unidade delimitada. Rode LEARN → ANALYZE → EXECUTE (uma) → VERIFY → DECIDE; nunca agrupe unidades em lote, nunca fique ocioso, rode a prova de novo após qualquer mudança no caminho já provado. Se o boundary for inalcançável, pare e pergunte, pronto para decisão — nunca afirme, nunca simule a checagem de cabeça e relate como aprovada.
O orquestrador delega uma unidade delimitada a um agente instalado pelo seu modo headless cli -p, após um preflight (command -v / uma etapa de detecção de painel) para que só agentes ativos sejam usados. O Validador é sempre um agente diferente do construtor — essa separação é o que torna o Proof Gate confiável. Estas são as invocações comprovadas (flags ao pé da letra):
# Claude Code — saída JSON claude -p "<uma unidade delimitada>" --output-format json # Codex — exec silencioso codex exec --quiet "<uma unidade delimitada>" # Kimi — saída de texto (nunca -p COM --yolo; sem --work-dir) kimi -p "<uma unidade delimitada>" --output-format text # Grok — saída simples, auto-aprovar, cwd explícito grok -p "<uma unidade delimitada>" --output-format plain --always-approve --cwd .
As mesmas skills são copiadas ou linkadas (symlink) em cada agente (Claude Code as lê como /loop-engineering e /fusion-*; Codex/Kimi/Grok rodam headless; Cursor/Gemini/Aider/OpenCode/Crush/Goose leem o SKILL.md). O runtime difere; o método é idêntico.
Se três públicos são o quem, quatro portões são as regras do jogo — os pontos de checagem que uma execução precisa cruzar para que "finalizado" seja um fato, e não uma opinião. Você conhecerá cada um a fundo mais adiante; aqui está a forma, para que a palavra "portão" nunca seja um mistério quando aparecer.
O Scope Gate vem primeiro: o loop se recusa a começar a girar até existir um done-when escrito e mensurável. Sem linha de chegada, sem corrida. O Proof Gate é o coração de tudo: uma passagem só conta como progresso quando a mudança é provada no boundary real — uma execução real, uma resposta real — não afirmada. O Course Gate dispara na convergência: quando o trabalho está pronto, um curso visual-teach que o explique precisa existir. E o Publish Gate envia esse curso para fora — um gist privado e, opcionalmente, uma página hospedada — para que o resultado seja compartilhável, não preso em uma única máquina.
Pense nisso como… os pontos de checagem de um percurso de maratona. Você não pode começar sem uma linha de chegada registrada (Scope). Seu tempo só conta se você realmente cruzar os tapetes de cronometragem, não se você disser que correu rápido (Proof). No fim, você recebe um certificado impresso de resultado (Course). E o resultado é publicado publicamente, não sussurrado só para você (Publish). Pule um tapete e a execução simplesmente não conta.
Uma LLM pode produzir prosa fluente e confiante descrevendo um sucesso que nunca aconteceu. O Proof Gate existe precisamente para neutralizar esse modo de falha: a única coisa que faz uma passagem avançar é uma observação tomada onde o artefato encontra a realidade — o código de saída de um teste real, os bytes de uma resposta HTTP real, um build que de fato compila. Uma afirmação, um mock ou uma checagem autoavaliada são rejeitados. A lição 3 cobre o Proof Gate por completo.
Scope é uma pré-condição (você não pode rodar o loop sem um done-when). Proof roda em toda passagem. Course e Publish são gatilhos de convergência. Juntos, eles transformam "acho que está pronto" em "aqui está a evidência, e aqui está o link".
O suite é um punhado de partes nomeadas que se encaixam. Você conhece cada uma como deve ser mais adiante no curso; aqui está o mapa, para que os nomes já sejam familiares quando chegarem.
loop-engineering é o próprio loop central — o batimento da seção 1. Forge é o front-end ao qual você recorre quando o pedido é uma ideia bruta em vez de uma especificação; ele transforma um vago "eu quero…" em um escopo mensurável em sete passos. ultragoal é a disciplina por trás de um objetivo durável e verificável — o GOAL.md contra o qual o loop testa. visual-teach é o motor que constrói o curso que você está lendo agora. brightdata-cli é como o harness obtém evidência web real e atual em vez de adivinhar de memória; computer-use-cli é como ele opera apps nativos do macOS quando uma tarefa vive em um programa de desktop. fusion distribui uma pergunta difícil a um painel de modelos em paralelo e faz um juiz escolher a melhor resposta; Council é o conselho de peso — vários modelos com papéis e votos definidos — para as maiores decisões. A família de adaptadores é a única peça compartilhada de encanamento que permite a todos eles alcançar as mesmas CLIs subjacentes. E os publish gates são o que envia o curso finalizado para fora, no fim.
Para levar
Um loop, quatro portões (Scope · Proof · Course · Publish), três públicos (humano observa, modelo executa o método, agentes são o runtime) e um conjunto nomeado de partes. Guarde esses quatro fatos e o resto do curso é só detalhe se encaixando ao redor deles.
Agora veja as peças trabalharem juntas como um único pipeline — uma ideia bruta à esquerda, um curso publicado à direita. Use o sumário fixo para percorrer cada repasse; o diagrama mostra o mesmo fluxo, e o trecho ao final é a forma de uma passagem comprovada. (Isto também é uma demonstração ao vivo: o sumário à esquerda acompanha sua posição conforme você rola.)
Você entrega algumas frases e, algum tempo depois, volta um entregável finalizado e conferido mais um link compartilhável. No meio, o pedido viaja por cinco repasses: uma ideia bruta é afiada pelo Forge em um escopo mensurável, o loop avança pelas passagens, o Proof Gate exige evidência real a cada passagem, e o resultado verificado é entregue e publicado.
Pense nisso como… encomendar uma peça sob medida. Você descreve o que quer (ideia). Um chefe de oficina escreve a especificação e as tolerâncias exatas (Forge). Os torneiros a fazem em passagens medidas (loop). Um inspetor a coloca no calibre — uma pessoa diferente de quem fabricou (prova). Então ela é embalada com seu certificado e enviada (entregar e publicar).
Um prompt vago entra no Forge (grill → research → prototype → PRD → issues + /goal GOAL.md). O escopo compilado e mensurável alimenta o loop, que despacha uma unidade delimitada por passagem a um agente via cli -p. Cada passagem precisa cruzar o Proof Gate no boundary real. Na convergência, o visual-teach constrói o curso (Course Gate) e o Publish Gate o envia.
Um humano descreve o que quer em algumas frases — sem especificação, sem critérios de aceite ainda. Nada foi construído; este passo apenas entrega a intenção a uma máquina que sabe como afiá-la.
O Forge interroga a ideia (grill), opcionalmente pesquisa e prototipa, depois compila um PRD, issues e um GOAL.md com um done-when mensurável. O vago "eu quero…" vira uma linha de chegada contra a qual o loop pode testar — isso é o Scope Gate sendo satisfeito.
Cada passagem lê o estado real, escolhe uma unidade delimitada e a executa — despachada a um agente via cli -p. Uma mudança por vez, nunca um lote de palpites, repetindo até o done-when ser satisfeito.
Antes de uma passagem contar como progresso, a mudança é provada rodando a coisa de verdade e lendo o resultado de verdade. Uma afirmação não é prova; um mock não é prova. Um agente diferente do construtor faz a checagem — o Proof Gate.
Quando o done-when é atingido, o visual-teach constrói um curso autossuficiente (o Course Gate) e o Publish Gate o envia — um gist privado e, opcionalmente, uma página hospedada — entregando ao humano um resultado finalizado e um link.
Aqui está a forma de uma passagem — leia de cima a baixo e você reconhecerá cada etapa do diagrama. Este é o batimento que o harness repete até estar pronto.
# uma unidade delimitada, cinco passos, provada no boundary def one_pass(scope, agent): state = learn(scope) # LEARN · ler o estado real if meets(state, scope.done_when): return deliver_and_publish(scope) # portões Course + Publish unit = analyze(state, scope) # ANALYZE · escolher exatamente UMA result = agent.run(unit) # EXECUTE · via cli -p proof = verify_at_boundary(result) # VERIFY · rodar a coisa de verdade if not proof.passed: # Proof Gate: evidência, não afirmações return retry_or_handoff(proof) return decide(scope, result) # DECIDE · melhorar · repetir o loop
A partir de qualquer agente instalado, inicie o harness em uma tarefa com /loop-engineering; para uma ideia bruta, comece pelo Forge. Acompanhe o progresso em LOOP-LOG.md e leia o relato de QA em review.md — você observa, o loop roda.
O Validador (verify_at_boundary) é sempre um agente diferente do construtor (agent.run) — essa separação é o que torna o Proof Gate confiável. A etapa de publicação roda node ~/.claude/skills/loop-engineering/publish-course-gist.js <courseDir> e reporta a URL do gist.
Agora você tem a estrutura na qual todo o curso se apoia. O loop-engineering-suite é um harness: olhar, mudar uma coisa, prová-la no boundary real, repetir até uma linha de chegada escrita — e então entregar e publicar um curso. É agnóstico a modelo e a agente, então o mesmo método roda em qualquer IA capaz e qualquer ferramenta de linha de comando. E é lido por três públicos cujas funções nunca se misturam: o humano observa e decide, o modelo executa o método e honra os portões, os agentes são o runtime que gira as chaves.
A regra única
Nada está "pronto" porque um modelo disse que sim. Está pronto quando o boundary real diz que sim — e então o resultado é ensinado e publicado, não apenas afirmado. Todo o resto deste curso é como essa promessa é mantida.