Evidentemente sempre temos que estar atualizados com as novidades que não param de surgir e em meio a tanta novidade existe aquelas geradas automaticamente por IA/robos que apenas replicam de uma fonte principal e existem aquelas que realmente são uma experiência, perspectiva ou um caso de uso. Recentemente vem se falado muito sobre Loop Engineer que foi um boom nos meus e-mails, Instagram, reddit e Youtube, resolvi entender melhor por que desse hype e também montar uma aplicação aplicando esse conceito.
O que é Loop Engineer e o motivo do hype:
Para saber mais afundo o que é Loop Engineer sugiro pesquisar artigos focados nisso, mas em poucas frases:
Loop Engineering é a evolução do prompt engineering. Em vez de você escrever comandos manuais e esperar uma resposta da IA a cada passo, você projeta um sistema fechado e automatizado (um “loop”) onde agentes de IA trabalham sozinhos até atingirem um objetivo específico.
Agora o por que só agora um conceito que até então acredito que muitos já estavam fazendo e ficou no hype, vamos aos pontos:
- Boris Cherny, da Anthropic/Claude Code, disse que já não escreve prompt diretamente: o loop é que passsa a promptar o modelo, e o trabalho do humano vira “escrever loops”.
- Addy Osmani, do Google, deu nome, estrutura e anatomia ao conceito, descrevendo o loop como uma arquitetura co componentes como automações worktrees e sub agentes.
- A coincidência pública dessas falas em poucos dias ajudou a criar a impressão de “novo paradigma”, mesmo sendo uma evolução de ideias já existentes.
- O hype cresceu porque ferramentas como Claude Code, Codex, Cursor e afins começaram a oferecer primitivas parecidas com loop, goal, subagentes e automação contínua.
A aplicação loopforge:
Se você já usou Claude code ou qualquer assistente de IA com Skills (aqueles pacotes de conhecimento que você ensina o Claude a usar em determinada situação), sabe o trabalho que dá escrever uma boa. Não é só escrever em markdown explicando o que fazer. Tem regra de formação, tem que pensar em quando o claude vai “descobrir” que aquela skill existe, tem que ser conciso sem deixar de ser completo, tem que testar se realmente funciona na prática.
Fazer isso na mão, uma vez, já é chato. Fazer isso toda vez que eu tinha uma ideia nova de skill, revisando, ajustando, testando de novo, virou trabalho repetitivo de verdade. E trabalho repetitivo é exatamente o tipo de coisa que dá vontade de automatizar.
Só que automatizar “escrever uma skill boa” tem um problema chato escondido. Que critério eu uso para saber se a skill que a IA escreveu é boa? Não existe uma skill de referência pra comparar, tipo aquelas métricas de tradução automática que comparam sua frase gerada com uma frase “gabarito”. Aqui não tem gabarito. Cada Skill é sobre um assunto diferente, pra um objetivo diferente.
Foi aí que nasceu a ideia do projeto que apelidei de Loopforge: um sistema onde vários agentes de IA trabalham em cadeia, cada um numa LLM diferente, revisando o trabalho um do outro dentro de um loop que só para quando a qualidade bate um critério real. Virou também um estudo pessoal sobre o conceito de Loop Engineering. Esse artigo é o resumo de tudo que aprendi construindo isso, do conceito mais simples até os detalhes mais avançados de engenharia que precisei resolver pra fazer o sistema ser confiável.
A virada de chave: Loop Engineering
Prompt engineering é você escrever um prompt bom e mandar pra IA de uma vez. Funciona, mas a qualidade do resultado depende de acertar o prompt de primeira. Se a IA errar, você que vai perceber, reler, ajustar o prompt e mandar de novo. Você não está mais escrevendo um prompt perfeito. Você está desenhando um processo que converge pra qualidade.
Isso muda completamente onde você coloca esforço. Em vez de gastar horas lapidando um prompt gigante, você gasta esforço desenhando:
1. Quem faz o quê no ciclo (os papéis)
2. Como cada papel passa informação pro próximo (o hand-off)
3. Qual é o sinal de qualidade que decide se o ciclo já pode parar (a métrica)
4. Como garantir que o ciclo não fica girando pra sempre (as condições de saída)
O resto do artigo é basicamente eu explicando como resolvi cada um desses quatro pontos.
O ciclo, em linguagem simples:
Pensa em quatro pessoas trabalhando numa esteira, cada uma numa etapa:
– Discovery é o pesquisador. Ele olha o objetivo e propõe várias abordagens possíveis, com prós e contras de cada uma, e recomenda a que acha melhor. Ele só entra uma vez, no início, porque pesquisar de novo a cada volta do loop seria redundante (a pesquisa já foi feita).
– Plan é o arquiteto. Ele pega a recomendação do Discovery, escolhe o melhor caminho e transforma isso numa especificação concreta de skill: quais seções vai ter, o que cada uma precisa cobrir. Esse é o agente que repete a cada volta do loop, porque é ele que vai reagir ao feedback do Judge e replanejar.
– Write é quem escreve de fato. Pega a especificação do Plan e produz o arquivo real da skill, incluindo qualquer arquivo de referência adicional que ela precise.
– Judge é o avaliador. Lê o que o Write produziu e devolve uma nota estruturada, dimensão por dimensão (não é só “nota 7”, é “aqui você está bom, aqui você está fraco, e é por causa disso”).
O pulo do gato é que cada um desses quatro papéis roda numa LLM diferente. Isso não é capricho, é decisão de design, e vou explicar o porquê mais pra frente (spoiler: é sobre evitar viés).
Por que “loop com saída garantida” importa tanto:
Todo mundo que já brincou com agentes de IA em loop sabe do medo real: e se o loop nunca terminar? E se ele ficar girando, gastando tokens (leia-se: gastando dinheiro) pra sempre porque a IA nunca “acha” que terminou?
Por isso desenhei o loopforge com três portas de saída independentes, e qualquer uma delas encerra o ciclo:
1. A nota bateu o mínimo exigido. Você define, por exemplo, que só aceita uma skill com nota 0.8 pra cima (numa escala de 0 a 1). Bateu isso, acabou, a skill fica.
2. Estourou o teto de tentativas. Você define um número máximo de voltas do loop (por exemplo, 6). Se chegou lá sem bater a nota mínima, o sistema para de qualquer jeito e entrega a melhor versão que conseguiu, com um relatório dizendo que não bateu o critério.
3. O loop travou (estagnação). Às vezes o sistema fica preso girando sem melhorar a nota rodada após rodada. Se isso acontecer por um número de rodadas seguidas que você define, o loop para sozinho, porque insistir ali só ia queimar tokens sem ganho nenhum.
Isso é o tipo de detalhe que separa um “projeto de fim de semana legal” de um sistema que você confiaria pra rodar sem supervisão.
A métrica de qualidade: o coração de tudo
Essa foi a parte mais difícil de acertar, porque é ela que decide se o loop aprova ou reprova uma skill. Se a métrica for ruim, o loop inteiro é ruim, não importa quão bons sejam os agentes.
Cheguei numa métrica híbrida, combinando dois tipos de avaliação bem diferentes:
Camada 1: checks determinísticos (peso 30%)
São verificações programáticas, tipo checklist de código. Rápidas, baratas (não custam chamada de LLM) e 100% reproduzíveis. Coisas como:
– O frontmatter da skill (aquele cabeçalho com metadados) é um YAML válido e tem nome e descrição?
– A descrição tem um gatilho de uso claro, tipo “use quando X acontecer”? (Essa é praticamente a causa número um de uma skill nunca ser usada. Se a descrição não deixa claro quando ela se aplica, a IA nunca vai lembrar de chamá-la.)
– O arquivo está dentro de um orçamento de linhas razoável (skill enorme é skill que ninguém lê)?
– Os arquivos que a skill referencia realmente existem no disco?
– O markdown está bem formado?
Camada 2: o Judge, o avaliador que “entende” o conteúdo (peso 70%)
Checks programáticos não sabem dizer se a skill realmente faz sentido pro objetivo, ou se está clara, ou se está completa. Isso exige entendimento de linguagem, então essa parte fica por conta de outra LLM, o agente Judge, que devolve notas de 0 a 1 em cinco dimensões:
– A skill realmente cumpre o objetivo que foi pedido?
– Ela vai ser “descoberta” pela IA no momento certo (a descrição é boa o suficiente)?
– Está concisa e clara, ou está redundante e prolixa?
– Cobre o objetivo de ponta a ponta ou deixou buracos?
– Segue as boas práticas de escrita de skill que eu passei como referência?
Por que misturar os dois
Métrica só matemática (tipo BLEU, usada em tradução automática) compara texto contra uma referência gabarito, e aqui não existe gabarito. Métrica só de LLM-juiz sozinha tem um problema conhecido: LLM tende a ser “bonzinho” demais e inflar nota. A camada determinística funciona como um freio de mão, ela barra os erros grosseiros e óbvios antes mesmo de perguntar pra outra IA “você acha que isso ficou bom?”.
O score final é uma média ponderada simples:
score_final = 0.30 × nota_determinística + 0.70 × nota_do_judge
Se o resultado bater o mínimo definido (por padrão, 0.8), aprova. Se não bater, o feedback do Judge (que vem detalhado, dimensão por dimensão, com trechos concretos como evidência) volta pro agente Plan, que replaneja levando aquilo em conta na próxima volta.
A stack técnica, e por que escolhi cada peça
– PydanticAI: framework pra construir os agentes. Ele garante que cada agente devolve uma saída estruturada e tipada (um objeto Python de verdade, não um texto solto que eu preciso tentar interpretar na unha). Isso é enorme pra confiabilidade, porque elimina uma classe inteira de bugs de “a IA respondeu num formato que eu não esperava”.
– LangGraph: framework pra desenhar o grafo do loop (Discovery → Plan → Write → Judge → decide se repete ou não). Ele cuida da aresta condicional de loop e tem um recurso chamado checkpointer, que salva o estado da execução passo a passo (voltarei nisso).
– uv: gerenciador de pacotes e ambiente Python. Rápido e sem drama de dependência quebrada.
– YAML de configuração: você não mexe em código pra rodar o loopforge com um objetivo diferente. Você escreve um arquivo YAML dizendo qual LLM cada agente usa, qual é o objetivo, quais são os critérios de corte, e roda.
– structlog + rich: logs estruturados e bonitos no terminal, pra acompanhar cada etapa do loop em tempo real.
– LangGraph Studio: uma interface visual no navegador onde dá pra ver o grafo rodando ao vivo, inspecionar o estado em cada etapa, e até “voltar no tempo” pra ver decisões passadas.
Um objetivo, um arquivo YAML, um comando
Pra dar uma ideia concreta de como isso fica na prática, um YAML mínimo se parece com isto:
agents:
discovery:
Model: google-gla:gemini-2.0-flash
plan:
model: anthropic:claude-opus-4-8
write:
model: anthropic:claude-opus-4-8
judge:
Model: anthropic:claude-sonnet-4.6
skill:
objetivo: "Skill que revisa PRs de Python procurando bugs de concorrência"
output_dir: "./skills"
loop:
max_iteracoes: 6
score_minimo: 0.8E o comando é só:
uv run loopforge
Repare que cada agente aponta pra um provedor de LLM diferente (Google no Discovery, Anthropic no resto, por exemplo). Isso é proposital, e é o próximo tópico.—
Indo além do básico: os detalhes que fazem o sistema confiável
Até aqui foi o conceito. A parte que mais me ensinou coisa foi resolver os problemas de engenharia que aparecem quando você tenta rodar isso de verdade, sem supervisão, e sem torcer pra dar certo.
Anti-viés: por que o Judge nunca pode ser a mesma LLM do Write
Imagina pedir pra você mesmo avaliar o próprio trabalho sem nenhum distanciamento. É difícil ser crítico de verdade. Com LLM acontece parecido: se a mesma IA que escreveu o conteúdo também é quem avalia, ela tende a validar as próprias escolhas.
Por isso o sistema valida na configuração que o modelo do Judge é de um provedor diferente do modelo do Write, e emite um aviso se alguém tentar configurar os dois iguais. É uma trava simples, mas resolve um problema real de viés de avaliação.
Calibrando o Judge pra não ser bonzinho demais nem rigoroso demais
Como o Judge pesa 70% da nota final, ele é o fator que mais decide a acurácia do loop inteiro. Fiz três ajustes finos nele:
– O prompt do Judge exige que ele cite um trecho concreto da skill como evidência pra cada nota que dá, em vez de simplesmente “achar” uma nota. Isso obriga o modelo a fundamentar, e fica mais fácil de auditar depois se a nota fez sentido.
– O prompt dá âncoras explicando o que cada faixa de nota significa (o que é um 0.9, o que é um 0.5), pra reduzir a subjetividade de “qual é a régua aqui”.
– A temperatura de geração do Judge (e também do Write) fica baixa, o que reduz a variação aleatória entre rodadas. Isso importa porque se o Judge dá notas diferentes pro mesmo conteúdo em execuções diferentes, o loop fica instável e imprevisível.
O Judge não fica cego pros arquivos de referência
No começo, o Judge só recebia o arquivo principal da skill pra avaliar. Só que uma skill de verdade costuma ter arquivos de referência junto (aquele padrão de “progressive disclosure”, onde o arquivo principal é enxuto e aponta pra material mais detalhado quando necessário). Se o Judge não vê esses arquivos, ele avalia “completude” de forma incompleta, ironicamente.
Corrigi isso: o Judge agora recebe o plano original, os arquivos de referência inteiros, e as notas de escrita que o Write deixou explicando as decisões que tomou. Ele avalia o pacote completo, não só a ponta que aparece primeiro.
O feedback que anda pelo loop é estruturado, não é só um textão
Quando o Judge reprova, o feedback que volta pro Plan não é um parágrafo solto de prosa que o próximo agente precisa “interpretar”. É uma estrutura com listas separadas de problemas bloqueantes (o que precisa ser corrigido, sem discussão) e sugestões (melhorias que ajudam mas não travam a aprovação). Isso vira um checklist renderizado automaticamente, muito mais fácil de agir em cima do que um texto corrido.
MCP: os agentes podem consultar sistemas externos ao vivo
MCP (Model Context Protocol) é o jeito padrão de dar ferramentas externas pra um agente de IA usar, tipo “consultar uma página do Confluence” ou “ler um ticket do Jira” durante a execução, em vez de só confiar no que já foi carregado como contexto estático.
O loopforge herda automaticamente os servidores MCP que você já tem configurados na sua sessão do Claude Code. Não precisa configurar nada extra: se você já tem Confluence ou Jira conectado, os agentes ganham acesso a essas ferramentas sozinhos.
Duas decisões de design que considero importantes aqui:
– Seleção dinâmica por contexto. Em vez de você escolher manualmente quais servidores MCP usar toda vez, o sistema cruza palavras do seu objetivo e dos seus links de referência com a “assinatura” de cada servidor disponível (nome, variáveis de ambiente que ele espera, etc) e liga automaticamente só os que fazem sentido pro objetivo daquela execução. Muda o link de referência, muda o conjunto de ferramentas usado, sem você mexer em configuração nenhuma.
– Problema de saúde antes de usar. Cada servidor é testado no início (conecta e lista as ferramentas dele, exatamente como seria usado de verdade). Se algum está quebrado, ele é descartado com um aviso, e o loop nunca cai por causa de um servidor externo com problema.
Só leitura, sempre, sem exceção
Essa é a regra que trato como inegociável no projeto: o loopforge nunca cria, edita ou apaga nada nos sistemas externos que consulta via MCP. Toda ferramenta que chega pros agentes passa por um filtro que remove qualquer coisa que pareça escrita ou execução (baseado no nome do verbo, tipo “criar”, “atualizar”, “deletar”) antes mesmo do modelo enxergar que aquela ferramenta existe. A única coisa que o sistema de fato escreve em algum lugar é a skill final, gravada localmente no seu computador.
Esse tipo de trava é o tipo de decisão que parece óbvia depois de pensada, mas que é fácil de esquecer quando você está animado construindo a parte “legal” do sistema.
Busca na web pra ficar atualizado
Além de MCP (pra sistemas internos tipo Confluence), os agentes também têm acesso a busca na internet aberta (DuckDuckGo por padrão, sem precisar de chave de API). Isso ajuda a skill gerada a se basear em prática atual, em vez de só confiar na memória de treinamento do modelo, que pode estar desatualizada.
Lidando com a realidade de rodar com modelos gratuitos e instáveis
Um detalhe prático que só aparece quando você tenta rodar isso de verdade, sem gastar uma fortuna em API: modelos gratuitos ou com cota limitada estouram limite de requisição por minuto com facilidade. O sistema tem um limitador de requisições global (soma de todas as chamadas de todos os agentes, porque um agente sozinho pode disparar várias chamadas internas de function-calling) e uma política de novas tentativas automáticas quando toma um erro de “limite excedido” ou erro temporário do servidor, respeitando o tempo de espera que o provedor pede.
E se mesmo assim a IA devolver uma saída mal formada (acontece bastante com modelos menores tentando gerar estruturas de dados complexas), o sistema tenta de novo automaticamente antes de desistir. E se o próprio Judge falhar catastroficamente numa rodada, o loop não quebra: ele usa uma nota de fallback pra aquela rodada e segue em frente, preservando qualquer skill que já tenha sido escrita até ali. Nenhuma dessas falhas derruba o processo inteiro.
Uma trilha auditável de tudo que aconteceu
Junto com a skill final, o sistema grava um arquivo à parte com a trilha de raciocínio completa do loop: o que o Discovery pesquisou e onde encontrou, o que o Plan decidiu e por quê, as notas que o Write deixou explicando escolhas, o histórico de notas do Judge rodada a rodada. Isso transforma um processo que seria uma “caixa preta” em algo que dá pra auditar depois, entender por que o sistema tomou determinada decisão.
Duas formas de observar o que está acontecendo
Todo o processo emite logs estruturados detalhados no terminal (cada troca de etapa, cada nota, cada decisão do loop), e também é possível abrir uma interface visual no navegador que mostra o grafo rodando ao vivo, com a possibilidade de inspecionar o estado em qualquer ponto da execução, inclusive voltar no tempo pra rever decisões passadas. Ter as duas visões, uma rápida no terminal pro dia a dia e uma visual detalhada pra depuração mais profunda, faz muita diferença quando algo não sai como esperado.
O que eu aprendi construindo isso
Algumas reflexões que ficaram depois de meses mexendo nesse projeto:
Métrica é o produto de verdade. Eu comecei pensando que o difícil seria escrever bons prompts pros agentes. O difícil de verdade foi desenhar uma métrica de qualidade em que eu confiasse o suficiente pra deixar o sistema decidir sozinho quando parar. Um sistema autônomo só é confiável na medida em que o critério de parada dele é confiável.
Diversidade de modelo não é luxo, é proteção. Usar LLMs diferentes pra papéis diferentes não é só sobre custo (modelos mais baratos pra pesquisa, mais caros pra escrita fina). É sobre ter um avaliador genuinamente independente de quem produziu o conteúdo.
Todo sistema autônomo de verdade precisa de saída garantida. Não importa quão boa seja a métrica, você precisa de um teto e de detecção de estagnação. Sem isso, “autônomo” vira sinônimo de “pode ficar rodando pra sempre gastando seu dinheiro”.
Resiliência não é feature, é pré-requisito. Um sistema que quebra toda vez que uma IA externa devolve algo inesperado não é um sistema autônomo, é um sistema que precisa de babá. Tratar erro de rate limit, saída malformada e falha de ferramenta externa como coisas esperadas, não exceções raras, foi o que transformou o loopforge de “protótipo que funciona no meu computador quando dá sorte” pra algo que roda sem eu ficar olhando.
Antes de encerrar como funciona o loopforge de forma mais técnica antes de você clonar o projeto e se aventurar:
Fechando
Esse projeto começou como uma forma de resolver um incômodo bem específico meu: escrever skills boas dá trabalho repetitivo. Terminou virando um estudo bem mais profundo sobre como desenhar sistemas de múltiplos agentes de IA que se corrigem sozinhos com segurança, sem viés escondido, e sem depender de eu estar olhando por cima do ombro o tempo todo.
Se você trabalha com IA e ainda não experimentou montar um loop desse tipo (agentes diferentes, papéis separados, métrica real de corte), recomendo muito. É um exercício que ensina mais sobre engenharia de sistemas confiáveis do que sobre “prompt mágico”.
Se quiser trocar ideia sobre o assunto ou tiver curiosidade sobre algum detalhe específico da implementação, comenta aqui embaixo. Fico feliz em compartilhar mais.
Repositório do Loopforge que desenvolvi: https://github.com/AirtonLira/loopforge
