Passo 14 · Na prática·Na prática · Loop EngineeringENPT
Módulo 5 · Na prática · Lição 14
Na prática: um pedido, de ponta a ponta
Uma ideia crua, conduzida até a entrega — Forge para montá-la, o loop para construí-la, as ferramentas para prová-la — e o tempo todo o humano só assistiu. Estas são as treze lições anteriores fazendo um trabalho real, e então te entregando as chaves.
Linguagem simples primeiro; abra qualquer painel para a versão precisa.
1
A grande ideia: uma ideia crua, entregue, enquanto você assistia
Tudo neste curso veio uma peça de cada vez: o que é um loop, como delimitá-lo, os cinco passos, os gates, o front-end Forge, as ferramentas, o motor do curso. Esta lição roda tudo isso de uma vez, sobre um pedido real, de uma frase a uma mudança entregue — e você não toca no teclado depois que ela começa.
Eis o pedido que vamos seguir o caminho inteiro: "A RHG precisa de um endpoint de health e uma página de status minúscula, atrás de login, entregue com segurança." Isso é vago de propósito — é assim que pedidos reais chegam. No fim ele vira um contrato mensurável, um quadro de tickets, código que um agente escreveu, uma prova de que o código de fato funciona, e um write-up do que foi entregue. Nada disso é simulado: todo "pronto" nesta página é uma checagem real que realmente passou.
A forma da execução tem duas metades. O Forge é o front-end que transforma a névoa em um plano — sete passos: grill, research, prototype, PRD, issues, implement, review. O loop é o motor dentro do passo "implement" que constrói cada ticket e se recusa a chamá-lo de pronto até que uma checagem real passe. Em torno de ambos há uma regra que torna seguro se afastar: tudo roda AFK (longe do teclado), e o seu único trabalho é observabilidade — você lê o log, você não conduz uma passada.
Pense nisso como… contratar uma reforma de cozinha enquanto você está no trabalho. Você não assenta azulejo. Você entrega um briefing, a equipe o transforma num plano com um aval em cada etapa, eles constroem, um inspetor independente confere cada etapa contra o briefing, e você recebe fotos no celular o dia todo. Você só intervém numa decisão que só você pode tomar — "qual bancada?" — nunca para segurar um martelo.
O loop (o motor)
Cinco passos, rodados repetidamente até o contrato ser cumprido: LEARN (observar o estado real) → ANALYZE (classificar a lacuna, escolher exatamente UMA unidade delimitada) → EXECUTE (construir essa única unidade) → VERIFY no boundary real (o Proof Gate — rodar a checagem de fato, nunca uma alegação e nunca um mock) → DECIDE (avançar, repetir ou escalar). O Proof Gate é o inegociável: uma unidade só está "pronta" quando um comando rodado contra o artefato real retorna o resultado esperado.
Forge (o front-end de 7 passos)
Para um pedido cru ou vago você roda o Forge primeiro: 1 grill (autodebate que converge o escopo), 2 research (opcional — o Bright Data CLI puxa fatos reais para research.md), 3 prototype (opcional — evidência real de que a abordagem funciona), 4 PRD (a especificação do produto), 5 issues (tickets com relações BLOCKING — um kanban) mais GOAL.md (o contrato durável do ultragoal), 6 implement (o loop AFK: um Executor constrói cada ticket, um Validator independente o prova contra GOAL.md — o Validator nunca é quem construiu), 7 review (QA AFK que emite review.md como um relatório de observabilidade).
AFK + observabilidade
Todo passo acima roda sem supervisão. O único papel do humano é observabilidade: ler LOOP-LOG.md, review.md, o readout de status. Você nunca executa nada — nem mesmo a QA. Você só é interrompido por uma bifurcação genuinamente exclusiva do usuário, exposta como um handoff pronto para decisão. A delegação entre agentes é via cli -p headless; evidência da web é sempre o Bright Data CLI (nunca WebSearch/WebFetch, nunca o Bright Data MCP); a verificação de GUI via Computer Use é não-bloqueante e somente por acessibilidade.
Padrões de control-plane que esta execução segue: steipete/agent-scripts. A disciplina de meta durável por trás de GOAL.md: jxnl/dots (ultragoal).
2
A execução inteira em uma imagem
Leia da esquerda para a direita. Os sete passos do Forge rodam em ordem; o passo 6 (implement) é onde o loop gira, uma passada por ticket; o passo 7 (review) emite o relatório. Sob a linha inteira corre o trilho de observabilidade — o humano o lê, nunca pisa nele, até a única bifurcação de decisão puxá-lo para cima.
Sete passos no topo; o loop gira dentro do passo 6; o trilho de observabilidade é onde o humano vive. A única seta para cima é o handoff.
Vamos agora percorrer cada batida numerada desta imagem como algo vivo e clicável — um fluxograma que você percorre passo a passo, um plano que você abre fase por fase, um quadro que se move sozinho, os níveis que ficaram travados, uma reprodução de uma passada, a recuperação quando uma prova falhou, o ramo de melhorar-o-prompt, e o PR entregue. Nove widgets interativos, um pedido.
3
Percorra a execução de ponta a ponta
Mesma execução, agora como uma decisão que você percorre passo a passo. Escolha um caminho e aperte Próximo: o caminho feliz roda os sete passos até um resultado entregue; os outros caminhos mostram as duas bifurcações que podem te tirar do piloto automático — uma prova que falhou (o loop se recupera sozinho) e a única decisão genuinamente exclusiva do usuário (o loop para e te entrega uma escolha).
Traçar execução:
Leia de cima → baixo. O Proof Gate é o losango: um pass entrega, um fail volta ao EXECUTE, e uma escolha genuinamente só do usuário ramifica para o handoff.
Passo 1 de 7
Comece aqui
Um pedido cru aterrissa
Aperte Próximo para conduzir o caminho feliz do pedido até um resultado entregue. Troque a execução acima para ver as duas bifurcações que te tiram do piloto automático.
O gate é um comando, não uma opinião
No loop, o EXECUTE nunca chega a declarar vitória. O VERIFY roda a checagem nomeada em GOAL.md contra o artefato real — aqui curl -s -o /dev/null -w "%{http_code}" localhost:8080/health — e só um 200 literal avança a passada. Um gate que falha não para a execução; ele realimenta a falha no ANALYZE e o loop tenta de novo (essa é a seta "falha → repetir"). A execução só para para um humano na bifurcação de handoff, que é reservada para uma escolha que nenhum agente deveria fazer sozinho.
4
Anatomia do pedido: de uma frase a um contrato
A primeira coisa que o Forge faz é grelhar a ideia — ele discute consigo mesmo até a névoa virar algo mensurável. "Entregue com segurança" não é testável; curl localhost:8080/health → 200 é. Abaixo está cada passo do Forge para o nosso pedido, e a prova concreta que ele deixa para trás. Repare que todo passo entrega ao seguinte um artefato real, então nada é aceito por fé.
1 · grillConvergir o escopoO autodebate resolve "atrás de login" e "com segurança" em comportamento concreto.→ um escopo nítido, de duas frases
2 · researchPuxar fatos reaisO Bright Data CLI busca a convenção atual de health-check para research.md.→ research.md (citado)
3 · prototypeEvidência de que funcionaUma rota descartável retorna 200 localmente — prova de que a abordagem é sólida.→ um spike rodando
4 · PRDA especificaçãoProblema, escopo, não-objetivos e o done-when, escritos uma vez.→ PRD.md
5 · issuesO quadro + contratoTickets com links BLOCKING viram um kanban; GOAL.md registra o done-when durável.→ issues + GOAL.md
6 · implementO loop AFKO Executor constrói cada ticket; um Validator independente o prova no gate.→ commits provados
7 · reviewQA de observabilidadeA QA AFK lê a execução inteira e emite um relatório que você lê, não roda.→ review.md
A saída do grill (o escopo afiado)
"Atrás de login" → o endpoint é público (load balancers precisam alcançá-lo sem autenticação) mas a página de status exige uma sessão. "Com segurança" → entregar atrás de uma flag, desligada por padrão, com um rollback de um clique. O done-when deixa de ser um sentimento e vira um comando.
O contrato que ele escreveu — GOAL.md
Este é o artefato ultragoal: agnóstico a agente, CLI e modelo. A ativação universal é simplesmente rodar um GOAL.md durável sob o loop (o recurso de meta nativo de um fornecedor é um exemplo opcional, nunca obrigatório).
GOAL.md — o contrato durável contra o qual todo Validator verifica
<goal> Add a /health endpoint and a session-gated status page to RHG. </goal><context> repo: rhg-api · service runs on :8080 · ship behind flag status_page_v1 </context><constraints>
- /health is unauthenticated (the load balancer probes it)
- /status requires a valid session cookie
- flag defaults off; rollback = flip the flag, no deploy
</constraints><verification>
- curl -s -o /dev/null -w "%{http_code}" localhost:8080/health → 200
- curl -s -o /dev/null -w "%{http_code}" localhost:8080/status → 302 (no session)
</verification><done-when> both verification commands return their codes on the real service </done-when>
disciplina de ultragoal / meta durável: jxnl/dots.
5
O plano: o PRD como fases com barras de saída
O PRD não é uma parede de prosa — o Forge o molda como uma sequência de fases que vão em ordem, e uma fase só avança quando passa sua barra de saída, a prova de que é seguro continuar. A faixa é o mapa da nossa execução; clique numa fase para abrir seu objetivo, suas tarefas, os critérios de saída e os riscos que o loop está vigiando.
Pense nisso como… reformar cômodo por cômodo. Você não joga a casa inteira no gramado — você termina um cômodo, confere que nada quebrou, então começa o próximo, e mantém uma torneira funcionando até o fim para sempre poder lavar as mãos.
Pedido endpoint de health da RHG + página de statusJanela uma noite AFKCondutor Forge → o loop (o Orchestrator delega via cli -p)
Progresso2 de 4 fases concluídas
Clique numa fase — ou foque a barra e use ←→ — para abrir seu cartão.
Fase 1 · Concluída
Enquadrar o pedido
grill → research → PRD
Objetivo: Transformar uma frase vaga numa especificação com um done-when mensurável, antes que alguém escreva uma linha de código de produto.
Tarefas
Grelhar "atrás de login" e "com segurança" até virar comportamento concreto
Puxar a convenção atual de health-check para research.md via Bright Data CLI
Fazer um spike de uma rota descartável que retorna 200 — prova de que a abordagem se sustenta
Done-when expresso como comandos executáveis, não adjetivos
Toda afirmação não óbvia no PRD citada
O protótipo de fato retornou 200 localmente
Riscos & mitigações
MédEscopo ainda nebuloso após um grillAdjetivos voltam furtivamente. Mitigação: rejeitar qualquer done-when que não possa ser um comando.
BaixoConvenção desatualizada vinda da memóriaAs normas de health-check mudam. Mitigação: o Bright Data CLI busca a fonte atual, nunca a recordação paramétrica.
Fase 2 · Concluída
Decompor num quadro
issues + GOAL.md
Objetivo: Quebrar o PRD em tickets pequenos com links BLOCKING explícitos, e escrever o GOAL.md durável contra o qual o Validator vai checar cada unidade.
Tarefas
Cortar tickets: rota, flag, página de status, guarda de sessão, testes
Ligar arestas BLOCKING (a página de status depende da rota)
Escrever GOAL.md com os comandos de verificação e o done-when
Semear o kanban: Blocked · Ready · Building · Proven
Critérios de saída
Cada ticket é uma unidade delimitada com seu próprio done-when
Nenhum ticket está "Ready" enquanto um bloqueador está aberto
A verificação de GOAL.md é executável por copiar-e-colar
Riscos & mitigações
MédTickets grandes demais para provar numa passadaUma unidade que você não consegue verificar de forma limpa. Mitigação: dividir até cada uma ter um único gate executável.
BaixoOrdenação oculta entre ticketsDependências implícitas travam o loop. Mitigação: tornar toda dependência uma aresta BLOCKING explícita.
Fase 3 · Em andamento
Implementar sob o loop
o loop AFK
Objetivo: Construir cada ticket e prová-lo no boundary real. O Orchestrator delega uma unidade via cli -p; um Executor a constrói; um Validator independente roda o gate. O Validator nunca é quem construiu.
Tarefas
O Executor implementa a rota /health atrás da flag
O Validator roda curl … /health e exige 200
O Computer Use verifica que a página de status renderiza — não-bloqueante, só AX
Cada unidade verde se move sozinha para Proven no quadro
Critérios de saída
Ambos os comandos de GOAL.md retornam seus códigos no serviço real
Nenhuma unidade marcada como pronta por alegação — só por um gate que passa
Toda repetição e falha está em LOOP-LOG.md
Riscos & mitigações
AltoUma prova falha no meio da execuçãoA rota dá 500 sob a flag. Mitigação: o gate pega; o loop realimenta a falha no ANALYZE e repete (ver §9).
MédQuem construiu avalia o próprio trabalhoA autovalidação esconde bugs. Mitigação: o Validator é um agente separado que nunca escreveu o código.
BaixoA checagem de GUI bloqueia a execuçãoUm modal rouba o foco. Mitigação: o Computer Use é somente por acessibilidade e nunca traz o app à frente nem move o cursor.
Fase 4 · Planejada
Revisar & entregar
review.md
Objetivo: Uma passada de QA AFK lê a execução inteira e emite review.md como um relatório de observabilidade — então a mudança é entregue atrás da sua flag. O humano lê o relatório; o humano não roda a QA.
Tarefas
O agente de QA re-deriva cada done-when de forma independente
Emitir review.md: o que foi entregue, o que foi provado, risco residual
Fazer merge atrás de status_page_v1=false; canário; ramp
Produzir este curso visual-teach como o artefato de convergência
Critérios de saída
review.md confirma que todo comando de GOAL.md passou
O rollback é um único clique de flag, sem deploy
A execução é totalmente legível a posteriori em LOOP-LOG.md
Riscos & mitigações
MédA QA carimba a execução sem questionarUm revisor amigável demais. Mitigação: a QA re-roda os gates ela mesma em vez de confiar no log.
BaixoFlag deixada ligada após o rollbackUm caminho morto persiste. Mitigação: um ticket de acompanhamento apaga a flag após duas semanas.
Um critério de saída é um gate, não um sentimento
"A implementação foi bem" não é um gate; "curl … /health retorna 200 no serviço real" é. Uma fase não pode avançar até que toda caixa seja uma checagem que passou — que é exatamente o Proof Gate do loop aplicado na escala da fase. O plano e o loop são a mesma disciplina em dois níveis de zoom.
A barra de marcos é uma máquina de estados viva
Cada segmento carrega done, active ou todo; selecionar um troca o role="tabpanel" visível. Numa execução real esses estados são dirigidos pelo quadro de tickets, então a barra reflete a realidade em vez do plano como escrito.
Cada fase avança só pelo seu gate de saída. A flag fica desligada pelas fases 1–3, então o rollback é um único clique; a entrega é onde ela entra em produção.
6
O quadro de issues se move sozinho
O passo "issues" do Forge transforma o PRD num quadro de tickets com quatro colunas — Blocked (esperando uma dependência), Ready (sem bloqueadores abertos), Building (um Executor está com ela) e Proven (um Validator passou seu gate). Durante a execução AFK o loop avança os cartões sozinho; aqui você pode conduzi-los. Um ticket sempre vive em exatamente uma coluna, e as contagens permanecem honestas o tempo todo.
Repare no cartão travado: um ticket com uma dependência BLOCKING aberta não pode se mover até seu bloqueador estar Proven — a mesma regra que o loop obedece, então ele nunca constrói algo cuja fundação ainda não está lá.
Pense nisso como… post-its numa parede. Um post-it nunca fica em dois lugares; você o descola de "ready" e o cola sob "building". Nada se perde, e a parede sempre te diz quanto falta — exceto os post-its que estão presos com fita até o de cima estar terminado.
Tickets abertos: 0 · Proven: 0
Blocked0
Ready0
Building0
Proven0
Um array é a fonte da verdade
Cada ticket é um objeto com um campo col — blocked, ready, building ou proven — e um blockedBy opcional. As colunas na tela não são a verdade; o array é. Tanto o botão de seta quanto o arrastar-e-soltar caem no mesmo moveTo(), então as duas interações nunca podem discordar, e um cartão fisicamente não pode aparecer em duas colunas.
BLOCKING é aplicado num único lugar
Um movimento para fora de blocked é recusado enquanto o bloqueador não está proven; quando um bloqueador chega a proven, seus dependentes são auto-promovidos para ready. Essa é a regra de kanban do passo "issues" do Forge, e é por isso que o loop nunca pega uma unidade cuja fundação está faltando. Sem framework — um array, um render, eventos de arraste nativos.
moveTo — o único lugar onde a coluna de um ticket muda (bloqueio aplicado)
functionmoveTo(id, col) {
const t = tickets.find(x => x.id === id);
if (!t || t.col === col) return;
if (t.blockedBy && !isProven(t.blockedBy)) return; // BLOCKING: refuse the move
t.col = col; // single source of truthif (col === 'proven') promoteDependents(id); // unblock what waited on it
render(id); // repaint everything from state
}
7
Níveis de autorização em ação: o que ficou restrito ao usuário
"Roda AFK" não significa "faz o que bem entende". Cada capacidade que a execução pode usar fica num nível (tier): a maioria é auto (o loop pode usá-las sem supervisão — ler arquivos, rodar o build, rodar o gate, conduzir uma checagem de GUI não-bloqueante), e algumas são gated (exigem um humano, expostas como um handoff). O painel abaixo é o mapa de autorização da nossa execução. Ligue uma capacidade e veja ou ela entrar em ação ou levantar um aviso vermelho de que não pode rodar sem o seu gate.
O ponto de ensino: uma capacidade gated ligada pelo loop sozinho não dispara de fato — ela aparece como bloqueada, exatamente como uma feature flag ligada enquanto sua dependência está desligada. É isso que mantém uma execução autônoma segura.
Pense nisso como… os interruptores de luz de um prédio. As luminárias de leitura estão num circuito que você pode acionar livremente. Mas o disjuntor principal da sala de servidores precisa de uma chave — acione o interruptor dele sem a chave e uma etiqueta acende: "precisa de aval primeiro."
ler & construirauto
Ler o repo, rodar o build, rodar a suíte de testes. O pão com manteiga do loop — nunca precisa de um humano.
tier: auto — sem gate
rodar o Proof Gateauto
Rodar a checagem curl … /health contra o serviço real. O Validator faz isso a cada passada, sem supervisão.
tier: auto — sem gate
verificar GUI (Computer Use)auto
Ler a página de status pela árvore de acessibilidade para confirmar que renderiza. Não-bloqueante, só AX — nunca move o cursor.
tier: auto — não-bloqueante
virar a flag de prod para 100%gated
Ligar status_page_v1 para todos os usuários. Isso é uma decisão de lançamento — o loop precisa entregá-la a um humano.
requer: aval humano (handoff)
force-push para a maingated
Reescrever o histórico compartilhado no branch padrão. Destrutivo e irreversível — sempre uma decisão humana.
requer: aval humano (handoff)
O que o loop pode fazer agora
Um mapa decide o que está "de fato ativo"
Cada capacidade tem um nível (tier). O loop pode ligar qualquer coisa, mas o conjunto efetivo — o que de fato dispara — exclui qualquer capacidade gated que não foi autorizada por um humano. Um interruptor gated acionado pelo loop sozinho renderiza o aviso inline e é reportado como bloqueado, nunca entregue. O fix "Obter aval" aqui faz as vezes do handoff real: ele registra a autorização humana que libera o bloqueio.
const tier = { read_run:'auto', proof_gate:'auto', gui_verify:'auto',
enable_flag:'gated', merge_main:'gated' };
functioneffective(on, authorized) {
// on by the loop AND (auto OR a human authorized it) = actually firesreturn Object.keys(on).filter(id =>
on[id] && (tier[id] === 'auto' || authorized[id]));
}
Este é o trilho de segurança sob "tudo roda AFK": autonomia sobre o tier auto, uma parada dura no tier gated. O humano nunca executa o trabalho auto e é chamado apenas para as bifurcações gated.
8
Reproduza uma passada AFK, estado por estado
Dê o zoom até o fim: uma única passada do loop no ticket /health. Aperte os eventos e veja o loop se mover por seus estados. A questão toda é que você não pode pular etapas — você não pode VERIFY antes de EXECUTE, e uma vez que uma passada DECIDE avançar, aquela unidade está pronta. Os botões ficam acinzentados no instante em que um movimento não é permitido de onde você está.
Pense nisso como… um jogo de tabuleiro onde só certas casas se conectam. Você rola o dado, você anda — mas o tabuleiro não te deixa pular para uma casa sem caminho até ela. Os botões acinzentados são as casas que você simplesmente não consegue alcançar de onde está.
O nó preenchido de cor argila é o passo atual. Os nós esmaecidos são inalcançáveis daqui.
Passo atual
LEARN
Observe o estado real do rhg-api: nenhuma rota /health existe ainda, a flag está desligada.
Movimentos permitidos
Log da passada (é isso que o LOOP-LOG.md registra)
A passada é uma máquina de estados finita
Um estado atual, um conjunto fixo de eventos, e uma tabela mapeando (state, event) → nextState. Eventos que não estão na tabela para o estado atual são desabilitados, então um movimento ilegal (verificar antes de executar) é impossível por construção — a mesma razão pela qual o loop nunca alega pronto sem rodar o gate. VERIFY é o único estado com duas saídas: advance para DONE num pass, ou retry de volta para ANALYZE num fail.
No meio da execução, um gate ficou vermelho. O Validator rodou curl … /health e recebeu um 500, não o 200 que o contrato exige. Este é o momento para o qual todo o design foi construído: nada foi entregue, ninguém foi acordado, e o loop se recuperou sozinho. Abaixo está o relatório que a execução produziu — uma linha do tempo do que aconteceu, a causa-raiz escavada com cinco porquês, o raio de impacto, e os fixes que o loop aplicou — e você só o lê.
Pense nisso como… um alarme de fumaça que dispara enquanto a cozinha ainda está bem. O alarme é a vitória: ele pegou o problema antes do incêndio, o sprinkler resolveu, e o relatório te diz para afastar a torradeira — não para reconstruir a casa.
GATE-FAIL
A passada em que /health retornou 500
Pego emPassada 4 · VERIFY
RecuperadoPassada 6 · VERIFY → 200
Entregou quebrado?Não — o gate bloqueou
Humano acordado?Não — o loop se recuperou sozinho
Reportado emLOOP-LOG.md
9·a
Linha do tempo da passada que falhou
Leia de cima a baixo. Os pontos oliva são rotina, o argila é um aviso, o vermelho é o gate que falhou, o verde é a recuperação. A falha apareceu exatamente onde deveria — no VERIFY, antes de qualquer coisa ser entregue.
Passada 4
O Executor constrói a rota /health
Um agente adiciona o handler atrás de status_page_v1 e o reporta como completo.
execute
Passada 4
VERIFY: o gate retorna 500, não 200
O Validator roda curl … /health. O handler lança erro numa leitura de config nil. A alegação "completo" é derrubada pelo boundary.
gate fail
Passada 5
DECIDE: repetir, não entregar
A falha realimenta o ANALYZE. O loop não avança e não escala — um gate que falha está dentro do escopo do loop para corrigir.
retry
Passada 5
Causa-raiz encontrada no log
O handler leu a config da flag antes de ela ser carregada. O ANALYZE estreita o fix para uma única mudança delimitada.
diagnosticado
Passada 6
Fix executado e re-verificado
O Executor protege a leitura da config; o Validator re-roda o gate. curl … /health → 200 no serviço real.
recuperado
Passada 6
O ticket se move sozinho para Proven
Só agora — num 200 real, não numa alegação — o cartão avança. A execução continua, intocada por um humano.
proven
A falha apareceu no VERIFY e foi contida ali. Duas passadas depois o mesmo gate retornou um 200 real.
9·b
Causa-raiz — cinco porquês
Continue perguntando "mas por que aquilo aconteceu?" até chegar a algo que você de fato consegue corrigir. "O gate retornou 500" é o sintoma. A quinta resposta é a que vale a pena corrigir — e ela aponta para um teste faltando, não para uma pessoa.
Por que o gate falhou?
O handler de /health retornou um 500 em vez de 200.
Por que o handler deu 500?
Ele lançou erro ao ler uma config de flag nil.
Por que a config estava nil?
O handler leu a flag antes de o carregador de config ter rodado no cold start.
Por que isso não foi pego antes?
O done-when do ticket checava um processo aquecido; nada exercitava o caminho de cold start.
Causa-raiz · o gate tinha um ponto cego
O comando de verificação atingia um servidor já inicializado, então o bug de ordem-de-init era invisível para ele. O fix é adicionar um caso de cold start ao gate — a prova, não o código, estava incompleta.
O gate fez exatamente o seu trabalho
Uma alegação de "completo" encontrou um boundary que discordou, e o boundary venceu. Nada foi entregue sobre uma mentira porque o loop nunca avança sobre uma alegação — só sobre um gate que passa. O custo do bug foram duas passadas extras de computação, pagas pela máquina, com o humano dormindo.
Sem culpados, e endurece o gate
O fix não é "o agente escreveu um bug"; é "a verificação do contrato deixou passar um caminho." Fortalecer o gate (adicionar a checagem de cold start) torna o sistema melhor, então a mesma classe de falha não consegue escapar da próxima vez.
9·c
Raio de impacto & os fixes
O dano em números, e a boa notícia no fim. Depois os itens de ação — marque-os conforme forem entregues; a barra acompanha o progresso.
2
Passadas extras do loop
0
Builds quebrados entregues
0
Humanos paginados
100%
Pego no gate
0 de 3 concluídos
P1
P1
P2
10
O ramo de melhorar-o-prompt: ajuste o contrato, veja reconstruir
O loop pode melhorar duas coisas diferentes. Normalmente ele melhora o artefato — o código. Mas quando o artefato continua errando do mesmo jeito, o movimento mais inteligente é melhorar o prompt que dirige a execução: a instrução entregue ao próximo agente. Este ajustador é esse ramo tornado tangível. Gire os botões à esquerda — quão estrito é o gate, qual boundary verificar, quem é o executor, se exigir uma fonte citada — e a instrução montada à direita se reconstrói, palavra por palavra, para você ver exatamente como cada alavanca reescreve o pedido antes de ele ser enviado.
Pense nisso como… uma máquina de café com botões de intensidade, tamanho e leite. Você não re-encana a máquina a cada vez — você gira um botão e a próxima xícara muda. Aqui a "xícara" é a instrução que o loop envia, e cada botão a reescreve na hora.
Instrução montadaao vivo
Uma função pura mapeia botões → instrução
Cada controle atualiza um state compartilhado e chama render(); a prévia é o que quer que buildPrompt(state) retorne — nada escreve nela diretamente. Como o construtor é puro (mesmo estado → mesma string), a instrução é reproduzível e a linha que mudou simplesmente pisca. Este é o mecanismo literal do passo "improve" do loop quando ele mira o prompt em vez do código: mude o contrato, regenere a instrução, rode de novo, mantenha só se o resultado do gate melhorar.
Melhorar o artefato OU melhorar o prompt
O loop converge melhorando qualquer que seja a superfície que é o gargalo. Um build instável → melhore o código. Uma execução que continua verificando a coisa errada (o ponto cego da §9) → melhore o prompt e o gate. Ambos os ramos terminam do mesmo jeito: re-rodar, re-provar, decidir. O humano continua apenas observando.
11
O resultado entregue: um PR write-up
A execução terminou; eis o que saiu. Um bom resultado conta uma história, não um despejo de diff. Antes de ler uma linha de código você deve conhecer a motivação (por que mexemos nisso), fazer um rápido tour pelos arquivos (o que mudou e por quê), ver o foco (a única parte sutil que merece uma segunda olhada — o fix de cold start da §9), e confiar no rollout (como entra em produção, atrás da sua flag, com um rollback de um clique). Os quatro botões são paradas nesse passeio.
Pense nisso como… um guia de turismo, não um despejo de mapa. Um mapa mostra toda rua de uma vez; um guia te conduz, aponta para a única estátua que importa, e te diz onde fica a saída.
rhg/rhg-api · pull request #318
Adicionar endpoint /health e uma página de status com sessão
Provado pelo loop+204 −125 arquivosflag: status_page_v1
Por que a RHG precisava disso afinal.
O load balancer não tinha um jeito confiável de saber se uma instância da RHG estava de fato servindo — ele sondava a home page, que podia dar 200 enquanto o app estava travado. Precisávamos de um /health barato e sem autenticação no qual o balancer pudesse confiar, mais uma pequena página /status com sessão para os operadores darem uma olhada nas checagens recentes.
A dor
Nenhum sinal confiável de vida; o balancer mantinha tráfego numa instância travada.
O objetivo
Um /health público retornando 200, e uma página /status que dá 302 sem uma sessão.
Por que agora
O escopo estava nítido, o done-when era um comando, e a coisa toda coube em uma noite AFK.
Cinco arquivos mudaram. Eis cada um e por quê.
novoapi/health.goA nova rota sem autenticação. Retorna 200 com um corpo JSON minúsculo assim que o carregador de config rodou.
novoapi/status_page.goA página com sessão. Redireciona (302) para o login quando não há um cookie de sessão válido.
editadoconfig/flags.yamlRegistra status_page_v1, com padrão false — zero mudança de comportamento até ser virada.
editadoapi/router.goConecta ambas as rotas atrás da flag. A guarda de cold start da §9 vive aqui.
testeapi/health_cold_start_test.goExercita o caminho de cold start que o gate original deixou passar. O teste é a especificação endurecida.
O único trecho espinhoso que merece uma leitura cuidadosa — o bug da §9.
Leia isto devagar: o handler não pode ler a config da flag antes de o carregador tê-la populado. Num cold start essa leitura retornava nil e o handler lançava um 500 — a falha exata que o gate pegou. O fix protege a leitura com um padrão seguro.
api/router.go — a guarda de cold start
// guard the flag read: a cold start must not 500funchealthEnabled() bool {
cfg := flags.Current()
if cfg == nil {
returntrue// /health is safe to serve even before flags load
}
return cfg.Enabled("status_page_v1") || cfg.healthAlwaysOn
}
Se você revisar um único trecho, que seja este — a correção vive aqui; todo o resto é encanamento.
Como entra em produção sem acordar ninguém.
Entregar no escuro atrás da flag
Fazer merge com status_page_v1=false em todo lugar. /health serve (é seguro-ligado); /status fica no escuro. Seguro para fazer merge agora.
Apontar o load balancer para /health
Trocar a sonda para /health em staging, observar uma hora, depois prod.
Canário da página de status em 5%
Virar status_page_v1 para 5% das sessões de operadores. Observar status.render.errors permanecer em zero.
Ramp 5% → 100% — o passo gated
Cada passo fica limpo por uma hora antes do próximo. Virar para 100% é a decisão gated pelo usuário da §7 — o loop a entrega a um humano no handoff.
Plano de rollback
Virar status_page_v1=false — reversão instantânea, sem deploy. Apagar a flag num PR de acompanhamento após duas semanas.
Parada 1 de 4 · Motivação
As perguntas reais do revisor, antecipadas
Um diff responde "o que mudou?" mas um revisor pergunta "por quê?", "onde eu olho?" e "isso vai quebrar a prod?". A forma de quatro etapas responde exatamente a essas, então o escrutínio certo cai sobre o trecho que sustenta o peso (a guarda de cold start) em vez de se espalhar fino por variáveis renomeadas. O rollout conquista confiança porque é gated por flag, com canário em métricas nomeadas, com rollback sem deploy — o revisor aprova um plano, não um salto.
12
Como foi construído: o mapa da suíte
Tudo que você acabou de ver roda sobre um harness e cinco skills distribuídas. O harness loop-engineering é a espinha — ele roda o loop e orquestra o time AFK. Em torno dele ficam cinco skills, cada uma dona de um trabalho: ultragoal escreve o GOAL.md durável; visual-teach constrói o curso (esta página); brightdata-cli é o único caminho para evidência real da web; computer-use-cli dirige apps nativos do macOS de forma não-bloqueante. As mesmas cinco estão instaladas em uma dúzia de agentes, então qualquer agente pode assumir o trabalho.
Um harness (argila, centro), cinco skills ao redor. O front-end Forge e as ferramentas todos se conectam ao mesmo loop.
O harness
loop-engineering roda LEARN → ANALYZE → EXECUTE → VERIFY → DECIDE, conduz os 7 passos do Forge, e orquestra o time AFK (um Orchestrator delegando unidades via cli -p; um Executor que constrói; um Validator que prova e nunca é quem construiu). Ele sempre encerra um trabalho não-trivial produzindo um curso visual-teach como este.
As cinco skills
ultragoal — a disciplina de meta durável por trás de GOAL.md; agnóstica a agente/CLI/modelo. A ativação universal é uma meta durável rodada sob o loop.
visual-teach — o motor do curso; emite as lições autocontidas em EN + PT-BR.
brightdata-cli — o único caminho uniforme para dados da web (SERP, scrape, browser, mais de 40 datasets). Sempre este CLI; nunca WebSearch/WebFetch; nunca o Bright Data MCP.
computer-use-cli — automação nativa do macOS somente pela API de acessibilidade; não-bloqueante, nunca move o cursor nem traz o app à frente.
Forge — o front-end de 7 passos que transforma um pedido cru na execução acima.
Essa é a suíte inteira fazendo um trabalho. Agora é sua. Você não precisa lembrar os sete passos ou os cinco estados — você precisa lembrar um movimento: invocar /loop-engineering. Dê a ele o seu pedido cru. Para qualquer coisa vaga ele roda o Forge primeiro; para qualquer coisa concreta ele vai direto ao loop. Ele roda AFK, prova o próprio trabalho no boundary real, e termina — exatamente assim — te entregando um curso visual-teach para a próxima pessoa também conseguir assumir.
A única coisa que você continua fazendo é a coisa que você fez nesta página inteira: observar. Leia LOOP-LOG.md. Leia review.md. Responda à única bifurcação de handoff quando ela vier. Esse é o trabalho.
Um movimento para começar (/loop-engineering), AFK no meio, um resultado entregue e um curso na saída — e o loop está pronto para rodar de novo.
Seu professor está a uma mensagem de distância. Esta foi a suíte inteira sobre um pedido. Quer rodá-la sobre o seu pedido? Conte ao agente a ideia crua e diga "conduza com /loop-engineering." Não tem certeza se o seu pedido é vago o bastante para precisar do Forge, ou concreto o bastante para ir direto ao loop? Pergunte — é exatamente o tipo de pergunta para trazer aqui.
14
No código: onde a execução vive no disco
A execução não é mágica — é um punhado de arquivos simples que um agente lê e escreve, mais o único comando que você digita. Aqui estão os artefatos reais que a execução deixa para trás, e exatamente como abri-los.
os artefatos de uma execução (sob o repo em que ela opera)
# the durable contract every Validator checks against
GOAL.md # goal · context · constraints · verification · done-when# the Forge outputs
research.md # facts pulled by the Bright Data CLI (cited)
PRD.md # problem · scope · non-goals · done-when
issues/ # tickets with BLOCKING edges — the kanban# the run records (what you read; you never execute)
LOOP-LOG.md # every pass: LEARN→ANALYZE→EXECUTE→VERIFY→DECIDE
review.md # the AFK QA observability report
Inicie a execução
Um movimento, de qualquer agente que tenha as skills instaladas:
# in the repo you want changed:/loop-engineering "RHG needs a /health endpoint and a status page, behind login, shipped safely"
Acompanhe (observe, nunca conduza)
# tail the run log as passes land
tail -f LOOP-LOG.md
# read the QA report when phase 4 emits it
cat review.md
# the contract the whole run is held to
cat GOAL.md
Re-rode a prova você mesmo (opcional)
O done-when é um comando, então você pode confirmá-lo na mão — a mesma checagem que o Validator rodou:
Recordar vence reler. Tente cada pergunta de memória antes de clicar — a resposta se revela ao clicar, com o porquê. Nenhuma pista na formatação; toda opção tem o mesmo comprimento.
Q1Durante a execução AFK, qual é o único trabalho do humano?
B. Tudo roda AFK; o humano só tem observabilidade — lê LOOP-LOG.md / review.md / status, nunca executa, nem mesmo a QA. A única exceção é uma bifurcação genuinamente só do usuário, exposta como um handoff.
Q2O que torna uma unidade "pronta" no loop?
C. O Proof Gate é um comando rodado contra o artefato real — nunca uma alegação, nunca um mock. Na nossa execução isso foi curl … /health → 200 no serviço de verdade. Uma alegação de "completo" perdeu para o boundary na §9.
Q3Quem prova que o trabalho de um Executor cumpre o objetivo?
A. O Validator nunca é quem construiu. Separar quem constrói de quem prova é o que impede um agente de carimbar o próprio trabalho — o risco "Méd" da §7 tornado concreto.
Q4Quando o Forge roda antes do loop?
D. O Forge é o front-end para um pedido cru ou vago — seu grill converge o escopo em um done-when mensurável. Um pedido concreto pode ir direto ao loop com um GOAL.md.
Q5Por que o gate que falhou na §9 não virou uma queda?
B. Porque o loop nunca avança sobre uma alegação, o 500 foi pego no VERIFY antes de qualquer coisa ser entregue. A falha realimentou o ANALYZE e o loop a corrigiu sozinho — duas passadas extras, zero humanos acordados.
Q6Qual é o caminho sempre-o-CLI para evidência da web?
C. Evidência da web é sempre o Bright Data CLI — o único caminho uniforme que todo agente tem pelo shell. Nunca WebSearch/WebFetch, e nunca o Bright Data MCP.
Pontuação: 0 / 6
Esse é o curso. Você agora tem o modelo, o front-end, as ferramentas, e o único movimento que roda todos eles. Abra qualquer painel técnico que você pulou, depois leve para o seu próprio trabalho — seu professor está a uma mensagem de distância.