Passo 1 · Fundamentos · Fundamentos · Loop Engineering EN PT

Módulo 1 · Fundamentos · Lição 1

O que é loop engineering (e por que o one-shot falha)

A maior parte do trabalho com IA é um único arremesso: você pede, ela responde, você torce. Loop engineering troca a torcida por um método — diga exatamente o que "pronto" significa, depois itere em loop (faça um pouco, prove, corrija, repita) até o resultado realmente atender ao pedido, e termine ensinando de volta. Esta primeira lição apresenta a ideia de várias formas e então prevê a máquina inteira que o resto do curso constrói.

Leia a versão simples, ou abra a camada técnica em qualquer seção.

A grande ideia

Imagine o jeito habitual de usar um assistente de IA. Você digita um pedido, ele produz uma resposta, e então você torce para a resposta estar certa. Não existe passo algum em que algo de fato confira o resultado contra o que você queria. Um arremesso, uma recepção, dedos cruzados. Isso é one-shot — e para qualquer coisa maior que uma pergunta rápida, ele falha em silêncio com mais frequência do que parece.

Ele falha porque a primeira tentativa de quase qualquer coisa real é incompleta. Uma função compila mas trata mal uma lista vazia. Um resumo lê bem mas inventa um fato. Uma landing page parece pronta mas o botão de cadastro não faz nada. O one-shot não tem como perceber nada disso, porque para em "resposta" e nunca chega em "a resposta é verdadeira?".

Loop engineering é o hábito oposto. Antes de começar, você escreve o que "pronto" de fato significa de um jeito que você consegue medir. Depois roda um ciclo enxuto: aprenda o estado real das coisas, descubra o maior gap, faça uma peça delimitada de trabalho, e então vá até o lugar real onde aquilo funciona ou não e prove. Se está pronto, você para e ensina o que construiu. Se não, a prova te diz exatamente o que corrigir, e você dá mais uma volta.

A diferença é o passo da prova. O one-shot diz "aqui está." Loop engineering diz "aqui está — e aqui está o comprovante de que de fato funciona." Todo o resto deste curso é construído sobre essa única jogada: prove na fronteira real, nunca apenas alegue.

Pense assim… a diferença entre atirar uma flecha num alvo no escuro versus atirar com as luzes acesas. O one-shot é o escuro: você solta a flecha e torce. O loop acende as luzes — você atira, caminha até lá e olha onde acertou, ajusta, atira de novo. Mesmo arqueiro, mesmo arco; a única coisa nova é ir conferir o alvo entre os tiros. Essa conferência é o método inteiro.

O formato, com precisão

Loop engineering é: SCOPE (um done-when mensurável, escrito antes de qualquer trabalho) → um ciclo repetido de LEARN → ANALYZE → EXECUTE uma unidade delimitada → VERIFY na fronteira real → DECIDE → ao convergir, entregar o resultado mais um curso completo ensinado. O passo verify é um Proof Gate: a verificação roda contra o artefato real ou a fronteira real (o arquivo real, o comando real, o app rodando), e um mock ou uma alegação de memória nunca conta como aprovação.

Por que "uma unidade delimitada"

Cada passada executa exatamente uma mudança, não um lote. Delimitar a unidade mantém o verify barato e inequívoco: quando algo quebra, exatamente uma coisa mudou, então a causa é óbvia. Lotes borram a atribuição e tornam o proof gate inútil. O loop troca throughput bruto por passada por um sinal limpo a cada passada — o que converge mais rápido em qualquer coisa não-trivial.

Agnóstico de modelo, sem travas de safety

O método é uma estrutura de controle, não um produto. Ele roda em qualquer modelo ou CLI capaz, com o trabalho entre agentes delegado de forma headless via cli -p. É derivado de dois padrões testados em campo: o maintainer-orchestrator do steipete (um modelo de topo orquestra, delegando unidades delimitadas a outros agentes) e um control-plane de github-project-triage (issues com relações de bloqueio como o livro-razão das unidades). O resto deste curso transforma essa estrutura num harness usável.

Os dois padrões que este método destila são relatos públicos de campo sobre orquestração de agentes de longo horizonte. Na dúvida sobre qualquer fato externo neste curso, a regra é fundamentá-lo em evidência ao vivo da web via Bright Data CLI (Lição 11) — nunca em memória velha. padrão de origem · maintainer-orchestrator + control-plane de project-triage

One-shot vs o loop, num relance

Aqui estão as duas formas desenhadas lado a lado. O one-shot é uma linha reta sem volta: pedir, responder, pronto, torcer. O loop dobra a linha num círculo, e a dobra é o passo verify — quando a prova falha, a seta volta ao início em vez de sair pela borda.

Esquerda: uma linha tracejada que termina em torcida. Direita: o mesmo trabalho dobrado num ciclo cujo VERIFY ou volta (falha) ou libera (passa).

O ciclo, desenhado e rotulado

Agora o ciclo anotado completo numa folha. Cinco partes nomeadas num arranjo fixo: o escopo que você define uma vez, depois os quatro passos que se repetem. Toque numa parte na legenda abaixo para destacá-la e ler o que ela faz.

Leia em sentido horário a partir do topo: SCOPE alimenta LEARN → ANALYZE → EXECUTE → VERIFY; VERIFY volta na falha, libera na aprovação.

Escolha uma parte para destacá-la, ou "Mostrar tudo" para resetar. (Toque numa parte ativa de novo para limpá-la.)

DECIDE é a dobradiça

VERIFY produz evidência; DECIDE a lê e roteia. Três desfechos: convergiu (todo done-when atendido → sai do anel para entregar + ensinar), continuar (progresso mas não pronto → de volta ao LEARN com o novo estado), ou bloqueado numa bifurcação só-do-usuário (uma decisão genuinamente humana → faz o handoff, pronto para decisão, e só então um humano se envolve). O papel permanente do humano é observabilidade, não condução.

Cada passo tem sua própria lição

LEARN (Lição 3), ANALYZE (Lição 4), EXECUTE (Lição 5), VERIFY + os gates (Lição 6), e a coisa toda rodando AFK (Lição 7). Esta folha é o mapa; o resto do Módulo 2 percorre cada nó em profundidade.

Por que loops vencem o one-shot

É tentador achar que um modelo forte o bastante torna o one-shot aceitável. Não torna — não porque o modelo seja fraco, mas porque a estrutura do one-shot não tem onde pegar um erro. Três visões de por que o loop vence: o mecanismo que o faz funcionar, o contrato que torna o "pronto" objetivo, e um rastreio resolvido de um pedido real.

o loop, em pseudocódigo

function loop_engineer(ask) {
  const scope = define_done_when(ask);   // mensurável, escrito primeiro
  let state = learn();                  // leia o artefato / a fronteira REAL
  while (true) {
    const unit  = analyze(state, scope); // classifique o gap → escolha UMA unidade delimitada
    execute(unit);                    // faça exatamente uma mudança
    const proof = verify(scope);       // PROOF GATE — rode na fronteira real
    if (proof.converged) return ship_and_teach(proof);
    state = learn();                   // reincorpore a prova, vá de novo
  }
}

O loop tem um lugar onde um erro é pego — verify(). O one-shot é o mesmo código com o bloco while inteiro deletado.

GOAL.md · o bloco done-when

# o contrato de escopo — o que torna o "pronto" objetivo
done_when:
  - "build passa: `npm run build` sai com 0"
  - "o botão de cadastro faz POST e retorna 200 em /api/signup"
  - "sem erros de console ao carregar (verificado no app rodando)"
verification:
  boundary: "o app rodando + o endpoint real"   # NÃO um mock
  proof:    "um transcript / screenshot, não uma alegação"

Cada linha é algo que uma máquina consegue checar. "Parece pronto" não está na lista — esse é o ponto.

LOOP-LOG.md · três passadas em um pedido

# pedido: "adicione um formulário de cadastro funcional à landing page"
pass 1  execute: "renderizar o markup do formulário"
        verify:  abrir app → formulário aparece, botão não faz nada  → FALHA
pass 2  execute: "ligar botão → POST /api/signup"
        verify:  curl /api/signup → 500, handler ausente  → FALHA
pass 3  execute: "adicionar o handler /api/signup"
        verify:  curl + abrir app → 200, linha gravada  → PASSA ✓ convergiu

Um one-shot teria parado depois da passada 1 ("aqui está seu formulário") com dois dos três defeitos entregues. O loop pegou os dois.

Veja por conta própria: grep -rn "done_when" GOAL.md · cat LOOP-LOG.md

Um modelo melhor aumenta as chances de uma passada qualquer ser boa, mas ele não consegue te dizer se esta passada foi. O valor do loop é o passo da prova, que independe da força do modelo: ele roda a verificação real na fronteira real. Modelo forte mais loop converge mais rápido; modelo forte sozinho ainda entrega palpites não verificados.

Por passada, sim — você paga pelo verify. Na tarefa inteira, não: um one-shot sutilmente errado custa uma sessão de debug humana depois, que faz alguns proof gates baratos agora parecerem minúsculos. Delimitar cada unidade mantém o verify rápido, então o overhead do loop fica pequeno enquanto a sua certeza fica alta.

Rodar a coisa real e observar o resultado real: executar o comando e ler o seu exit code, bater no endpoint real, abrir o app rodando, consultar a linha real do banco. O que não conta: "isto deveria funcionar", uma resposta mockada, ou reler o código e afirmar que está bem. Essa distinção — fronteira acima de crença — é a Lição 6.

Para uma resposta descartável sem fronteira real — uma definição rápida, um brainstorm, um rascunho que você mesmo vai julgar de qualquer forma. No momento em que a saída precisa funcionar contra algo real (código, dados, um sistema ao vivo, uma alegação mensurável), a verificação ausente do one-shot vira o bug, e o loop justifica o seu valor.

Os cinco passos, slide a slide

Mesmo ciclo, uma ideia por card para fixar limpo. Clique Próximo / Voltar, toque num ponto, ou use as setas esquerda/direita. A barra mostra o quanto você já avançou.

Passo 0 · antes do loop

SCOPE — escreva o que "pronto" significa.

Antes de qualquer trabalho, declare o resultado como algo que você consegue medir. Sem um done-when mensurável, sem loop — você nunca saberia quando parar.

Passo 1 · learn

LEARN — enxergue o estado real, não presuma.

Leia o artefato e a fronteira reais como estão agora. Decisões construídas sobre um palpite do estado são, elas mesmas, palpites.

Passo 2 · analyze

ANALYZE — classifique o gap, escolha UMA unidade.

Compare o estado ao escopo, nomeie o maior gap, e transforme-o em uma jogada delimitada e ranqueada. Não um lote — uma.

Passo 3 · execute

EXECUTE — faça exatamente uma mudança.

Faça essa única unidade e nada mais. Uma mudança por passada mantém a prova do próximo passo inequívoca quando algo se move.

Passo 4 · verify

VERIFY — prove na fronteira real.

Rode a verificação real na coisa real. Um Proof Gate, nunca uma alegação ou um mock. Este é o passo que o one-shot não tem.

A dobradiça · decide

DECIDE — iterar, entregar, ou fazer handoff.

Leia a prova. Não pronto? dê outra volta. Pronto? entregar + ensinar. Uma bifurcação só-humana? faça handoff, pronto para decisão.

Para levar

Defina "pronto", itere com prova, depois ensine.

Defina o escopo, rode learn → analyze → execute → verify até a prova dizer convergiu, depois entregue o resultado e um curso como este.

1 / 7 Use as setas ← →

Duas abordagens, lado a lado

O mesmo pedido, tratado de duas formas. Cada card mostra o formato da abordagem, no que ela é boa, onde ela morde, e um simples "escolha esta quando". Passe o mouse ou foque um card para trazê-lo à frente — depois use o seletor abaixo para acender o certo para a sua situação.

One-shot

Pergunte uma vez, pegue a primeira resposta, repasse. Não há passo que confira a resposta contra o pedido.

const result = ask(prompt);
return result;          // pronto? desconhecido — só torcemos

Prós

+Resposta mais rápida possível — uma chamada.
+Ok para respostas descartáveis, sem fronteira.

Contras

–Sem verificação: defeitos sutis vão em silêncio.
–"Pronto" é indefinido, então não dá para confiar.

Escolha esta quando A saída é descartável e você mesmo vai julgá-la de qualquer forma — uma definição, um brainstorm, um rascunho.

Loop engineering

Defina um "pronto" mensurável, depois faça uma unidade delimitada, prove na fronteira real, e repita até a prova dizer convergiu.

const scope = done_when(ask);
do { execute_one(); } while (!verify(scope).ok);
return ship_and_teach();   // pronto? provado ✓

Prós

+Todo resultado carrega uma prova de que funciona.
+Converge em tarefas reais; roda AFK.

Contras

–Overhead por passada: você paga pelo verify.
–Precisa de um done-when mensurável de antemão.

Escolha esta quando A saída precisa de fato funcionar contra algo real — código, dados, um sistema ao vivo, uma alegação mensurável. Este é o padrão para trabalho real.

Minha tarefa é principalmente…

Onde o one-shot quebra

Pegue um pedido real — "adicione um formulário de cadastro funcional" — e percorra-o pelo loop uma decisão de cada vez. Cada passada executa uma unidade, depois faz uma única pergunta sim/não no proof gate: passou? Um "não" volta; uma execução limpa entrega. Escolha um cenário, depois pressione Próximo.

O cenário one-shot é a história de advertência: ele para no primeiríssimo "parece pronto" e nunca chega a um proof gate.

Rastrear:

O loop volta ao EXECUTE a cada "não" até a prova passar. O one-shot (tracejado) roda uma vez e pula o gate por completo.

Passo 1 de 1

Comece aqui

Um pedido aterrissa

Pressione Próximo para percorrer o loop em três passadas — ou troque para one-shot para vê-lo pular o gate.

O gate é uma guarda, não um vibe

"A prova passa?" não é o modelo julgando o próprio trabalho — é a verificação real rodada na fronteira real, devolvendo um sinal duro. No rastreio resolvido, os três gates foram abrir app (botão morto → não), curl /api/signup (500 → não), e curl + abrir app (200, linha gravada → sim). Um "não" carrega o porquê, que é exatamente a entrada de que o ANALYZE precisa para a próxima unidade.

Por que o caminho do one-shot é tracejado

Ele nunca toca o losango. Roda EXECUTE uma vez e pula para "entregue na torcida", então qualquer defeito segue junto sem ser detectado. Essa aresta ausente — executar direto para entregar sem gate no meio — é o modo de falha inteiro que este curso existe para consertar.

Convergência ao longo das passadas

Veja como as duas formas ficam ao longo do tempo. O eixo y é "quanto do pedido está de fato atendido e provado". O one-shot dá um salto e então fica plano — ele não consegue subir, porque nada o verifica. O loop sobe um degrau a cada passada conforme o proof gate fecha um gap após o outro, até chegar a pronto.

Leia da esquerda → direita: o one-shot estaciona abaixo de "pronto"; o loop sobe um degrau provado por passada até cruzar a linha.

Monotônico por construção

A curva do loop só sobe ou fica plana, nunca desce — porque uma passada só é aceita quando seu proof gate se sustenta, e um gate que falha descarta a mudança em vez de entregar uma regressão. Cada degrau aceito é uma linha de done-when que ficou verde. "Convergiu" é simplesmente a passada em que a última linha vermelha fica verde; não há passada além dela.

A linha plana do one-shot

A altura do one-shot é onde quer que seu único palpite tenha caído — às vezes alto, às vezes baixo, mas sempre incerto, porque nenhum gate jamais o mediu. Desenhada honestamente, é uma linha plana numa altura desconhecida abaixo de "pronto". O loop troca aquele único salto incerto por uma escada de saltos certos.

A suíte inteira (uma prévia)

O loop é o motor. O resto deste curso acrescenta a máquina construída em volta dele — e aqui está o mapa para você saber para onde vamos. No centro está o loop que você acabou de conhecer. Em torno dele há quatro peças: um front-end Forge opcional que leva uma ideia crua até a entrega, um time AFK que roda tudo sem usar as mãos enquanto você só assiste, a disciplina ultragoal que mantém uma execução longa honesta, e uma caixa de ferramentas de skills companheiras que fundamentam e entregam o trabalho.

Uma frase para guardar: tudo roda AFK, e o único trabalho do humano é observabilidade. Você lê os logs, a review, o status. Você não executa nada — nem o QA. Você intervém só quando há uma decisão genuinamente humana a tomar.

O loop no centro; o Forge o alimenta, o time AFK o roda, o ultragoal o ancora, as ferramentas o servem — e o humano só lê os comprovantes.

Forge — 7 passos (Lição 8)

Para um prompt cru e vago, o front-end Forge roda antes do loop: grill (interrogatório autorrespondido da ideia) → pesquisa (opcional, via Bright Data CLI) → protótipo (opcional, para evidência) → PRD → issues (tickets com relações de BLOQUEIO, um kanban) → implementar (o loop AFK: um Executor constrói cada ticket, um Validador independente prova contra o GOAL.md — o Validador nunca é quem constrói) → review (QA AFK emitindo review.md como relatório de observabilidade).

AFK + observabilidade (Lição 9)

Tudo acima roda AFK. O Orquestrador (um modelo de topo) delega unidades delimitadas a outros agentes via cli -p headless; o elenco é definido no início e é agnóstico de modelo. O humano lê LOOP-LOG.md / review.md / status e não executa nada — nem o QA — bloqueando só numa bifurcação genuinamente só-do-usuário via um handoff pronto para decisão.

ultragoal + as ferramentas (Lições 10–13)

O ultragoal é a disciplina de metas duráveis por trás do /goal — agnóstico de agente/CLI/modelo; a ativação universal é um GOAL.md durável rodando sob o loop (o create_goal do Codex é um exemplo opcional, nunca exigido). As ferramentas: Bright Data CLI para evidência real da web (sempre — nunca WebSearch/WebFetch, nunca o MCP da Bright Data), Computer Use CLI para automação macOS não-bloqueante e só via árvore de acessibilidade, e visual-teach, o motor que gerou este próprio curso.

Glossário

O punhado de termos usados acima, em palavras simples. Estas são as palavras em que o curso inteiro se apoia — uma vez que um termo está aqui, toda lição posterior o usa do mesmo jeito.

One-shot: Pedir uma vez e pegar a primeira resposta, sem passo que a confira contra o pedido. ex.: "escreva o formulário" → aqui está um formulário → entregar, defeitos e tudo.
Loop engineering: Defina um "pronto" mensurável, depois cicle (faça uma unidade → prove → corrija) até o resultado realmente atender ao pedido, então ensine. ex.: o rastreio de cadastro em três passadas que pegou um botão morto e um 500.
Escopo / done-when: O contrato escrito antes de qualquer trabalho: o que "pronto" significa, expresso como coisas que você consegue medir. ex.: "npm run build sai com 0" — uma linha que uma máquina consegue checar.
Unidade delimitada: Exatamente uma mudança executada por passada — não um lote — para que a próxima prova seja inequívoca. ex.: "ligar o botão", sozinho, antes de adicionar o handler.
Proof Gate: O passo verify rodado na fronteira real — o comando, endpoint ou app real — nunca uma alegação ou um mock. ex.: curl /api/signup retornando 200, não "deveria retornar 200".
Convergiu: A passada em que toda linha de done-when está provadamente atendida. O loop para; o resultado é entregue com seu comprovante. ex.: a passada 3 acima — 200 mais uma linha gravada — pronto.
AFK / observabilidade: A execução inteira acontece sem usar as mãos; o humano só lê os logs e o status, não executando nada, bloqueando só numa bifurcação só-humana. ex.: você lê o LOOP-LOG.md enquanto o time trabalha.

Verificação rápida

Três perguntas rápidas — responda de memória antes de espiar para trás. Cada uma corrige no momento em que você clica, e diz por quê. Recordar agora é o que faz fixar.

1 · Qual é o único passo que o loop tem e o one-shot não?

o proof gate é a diferença, e independe da força do modelo. O one-shot para em "resposta"; o loop chega em "provado".

2 · Por que cada passada executa só UMA unidade delimitada?

uma mudança por passada significa que o verify é inequívoco: se quebra, exatamente uma coisa mudou, então a causa é óbvia.

3 · Na suíte completa, qual é o papel permanente do humano?

tudo roda AFK. O humano lê LOOP-LOG.md / review.md / status e não executa nada, nem o QA, bloqueando só numa decisão só-humana.

Respondidas 0 / 3 · corretas 0

Sua vez agora. Você já viu o loop de cinco formas — desenhado, em deck, em aprofundamento, lado a lado, e um flowchart que você percorreu. A seguir vem a Lição 2 · o contrato de escopo, onde você escreve o "pronto" mensurável de que o loop inteiro depende. Lembre: este curso é o seu professor — peça para ele reexplicar qualquer parte, em palavras simples ou em profundidade, quando quiser.