Engenharia de loops — projetando sistemas que fazem prompt para agentes

• Em vez de fazer prompt diretamente para agentes de código a cada turno, a mudança é para um modo de trabalho de projetar um sistema que faz prompt para o agente
• Um loop é uma meta recursiva em que a IA repete até concluir após você definir o objetivo, e é composto por cerca de cinco elementos
• Os cinco elementos são Automations, Worktrees, Skills, Plugins·connectors e Sub-agents, e tanto Claude Code quanto Codex atualmente têm todos os cinco
• O sexto elemento, memória, é um arquivo markdown ou quadro do Linear que armazena estado fora de uma conversa única, complementando modelos que esquecem a cada execução
• Ainda está em estágio inicial e é essencial prestar atenção ao custo de tokens; validação e entendimento continuam sendo responsabilidade humana (build the loop, stay the engineer)

---

Definição de engenharia de loops e contexto de surgimento

• Engenharia de loops é substituir a si mesmo por um sistema no papel de quem faz prompt para o agente, projetando diretamente o sistema que faz esse trabalho
  • Um loop é uma meta recursiva (recursive goal) em que a IA repete até concluir depois que o objetivo é definido
  • Pode ser a forma futura de trabalhar com agentes de código, mas ainda está no começo, e atenção ao custo de tokens é indispensável (os padrões de uso mudam muito dependendo de ser token rich/poor)
• Citações
  • Peter Steinberger: "Pare de fazer prompt para agentes de código e projete loops que façam prompt para eles"
  • Boris Cherny (responsável pelo Claude Code na Anthropic): "Agora eu não faço prompt para o Claude; eu rodo loops que fazem prompt para o Claude e decidem o que fazer. Meu trabalho é escrever loops"
• Nos últimos cerca de 2 anos, a prática era dar bons prompts e contexto suficiente, trocando turno a turno enquanto segurávamos diretamente o agente como ferramenta, mas esse modelo está chegando ao fim
• Agora, cria-se um pequeno sistema que encontra e distribui trabalho, valida, registra o que foi concluído e decide a próxima tarefa, deixando esse sistema cutucar o agente
  • Fica acima dos textos anteriores sobre agent harness engineering (o ambiente onde um agente roda) e factory model (o sistema que produz software)
  • Um harness que roda por timer, cria pequenos helpers e se alimenta sozinho
• Não é mais uma questão de ferramenta — há 1 ano, se você quisesse loops, precisava escrever e manter gambiarras em bash por conta própria; agora, os componentes já vêm embutidos no produto
  • A lista de Steinberger bate quase exatamente com o app Codex e é quase idêntica ao Claude Code, então em vez de discutir qual ferramenta usar, o foco é projetar loops que funcionem em ambos

Os cinco componentes do loop e a memória

• Um loop precisa de cinco coisas, com mais um lugar para lembrar do estado
  • Automations — disparam em um cronograma e fazem descoberta e triagem por conta própria
  • Worktrees — evitam que dois agentes trabalhando em paralelo entrem em conflito
  • Skills — registram conhecimento do projeto que o agente acabaria preenchendo no chute
  • Plugins·connectors — conectam o agente às ferramentas que você já usa
  • Sub-agents — um lado gera ideias e o outro valida
• O sexto é a memória, como um arquivo markdown ou quadro do Linear, que existe fora de uma conversa única e guarda o que foi concluído e o que fazer em seguida
  • Parece simples demais, mas é o mesmo truque do qual todos os agentes de longa duração dependem (texto anterior sobre long-running agents)
  • Como o modelo esquece tudo entre execuções, a memória precisa estar no disco, não no contexto — o agente esquece, mas o repositório não
• Os dois produtos atualmente têm os cinco itens, mudando apenas um pouco os nomes; a capacidade é a mesma

Automations — o batimento cardíaco do loop

• Automations são o elemento que transforma o loop de uma única execução em um loop de verdade
  • No app Codex, são criadas na aba Automations, escolhendo projeto, prompt a executar, periodicidade e se será um checkout local ou uma worktree em background
  • Execuções que encontram algo vão para a caixa de entrada de Triage, e execuções que não encontram nada são arquivadas sozinhas
  • A OpenAI usa isso internamente para tarefas chatas como triagem diária de issues, resumo de falhas de CI, elaboração de briefings de commits e caça a bugs adicionados na última semana
  • A automação pode invocar skills, então em vez de colar um paredão de instruções, é possível acionar $skill-name e manter tarefas repetitivas de forma sustentável
• O Claude Code chega ao mesmo ponto com agendamento e hooks
  • Com /loop, é possível executar prompts ou comandos em intervalos definidos, agendar jobs cron e disparar comandos de shell por hooks em momentos específicos do ciclo de vida do agente
  • Para continuar rodando mesmo depois de fechar o notebook, dá para transferir tudo para o GitHub Actions
• Há um segundo primitivo dentro da sessão que fica próximo do núcleo deste texto
  • /loop reexecuta em um intervalo fixo
  • /goal continua até que a condição escrita por você realmente seja verdadeira, e após cada turno um pequeno modelo separado verifica se houve conclusão, para que o agente que escreveu o código não seja também o corretor
    • Ex.: definir condições como "todos os testes em test/auth passam, lint clean" e sair da frente
  • O Codex também oferece /goal, funcionando ao passar turnos até que uma condição de parada verificável seja satisfeita, com suporte a pause, resume e clear

Worktrees — para que o paralelismo não vire caos

• No momento em que você roda mais de um agente, conflitos de arquivo começam a aparecer; esse é o ponto de falha
  • Dois agentes escrevendo no mesmo arquivo causam a mesma dor de cabeça que dois engenheiros fazendo commit na mesma linha sem se falar
  • git worktree resolve isso — compartilha o mesmo histórico do repositório, mas cada um fica em um diretório de trabalho separado sobre sua própria branch, então as edições de um agente não alcançam o checkout do outro
• O Codex tem suporte embutido a worktree, evitando colisões mesmo quando várias threads mexem no mesmo repositório ao mesmo tempo
• O Claude Code oferece o mesmo isolamento com git worktree, a flag --worktree para abrir a sessão no próprio checkout e a configuração isolation: worktree aplicada a subagents (cada helper recebe um checkout novo que se limpa sozinho ao terminar)
• Worktree elimina conflitos mecânicos, mas o limite superior continua sendo você — a quantidade real de coisas que dá para rodar é determinada pela sua largura de banda de revisão, não pela ferramenta (texto anterior sobre the orchestration tax)

Skills — para não precisar reexplicar o projeto toda vez

• Skill é a forma de parar de reexplicar o mesmo contexto do projeto em toda sessão, como se cada sessão fosse um peixinho dourado
  • As duas ferramentas usam o mesmo formato — uma pasta com SKILL.md contendo instruções e metadados, além de scripts, referências e assets opcionais
  • No Codex, pode ser chamada com $ ou /skills, ou executada automaticamente quando a tarefa combina com a descrição da skill; por isso, descrições concisas e tediosas funcionam melhor do que descrições espertinhas
  • O Claude Code funciona da mesma forma (texto anterior sobre agent skills)
• Skill é o lugar onde intenção (intent) deixa de virar custo recorrente
  • O agente começa cada sessão a frio e preenche lacunas de intenção com suposições confiantes (texto anterior sobre the intent debt)
  • A skill é essa intenção escrita para fora — convenções, etapas de build, coisas como "não fazemos assim por causa daquele incidente"; você registra uma vez e o agente lê em toda execução
  • Sem skill, o loop rederiva o projeto inteiro do zero em cada ciclo; com skill, isso se acumula como juros compostos
• Skill é o formato de autoria, e plugin é a forma de distribuição — ao compartilhar entre vários repositórios ou empacotar, isso vira plugin (igual em Codex e Claude Code)

Plugins·connectors — fazendo o loop tocar ferramentas reais

• Um loop que só enxerga o sistema de arquivos é um loop pequeno
  • Um connector baseado em MCP permite ao agente ler issue trackers, consultar banco de dados, chamar APIs de staging e enviar mensagens no Slack
  • Tanto Codex quanto Claude Code falam MCP, então um connector feito para um lado normalmente funciona do outro lado também
  • O plugin empacota connector e skill para que colegas instalem tudo de uma vez, sem reconstruir o conjunto inteiro de memória
• É isso que separa um agente que diz "aqui está uma correção" de um loop que abre um PR, vincula um ticket no Linear e envia um ping no canal quando o CI fica green
  • O connector é o motivo pelo qual o loop não fica só falando de possibilidades, mas age no ambiente real

Sub-agents — separar quem constrói de quem verifica

• A estrutura mais útil em um loop é, de longe, separar quem escreve o código de quem o inspeciona
  • O modelo que escreveu o código é permissivo demais ao corrigir a própria lição de casa
  • Um segundo agente, com instruções diferentes e às vezes até outro modelo, pega coisas que o primeiro já tinha se convencido de que estavam boas
• O Codex cria subagents sob demanda, roda em paralelo e depois combina os resultados em uma única resposta
  • Define agentes próprios em arquivos TOML em .codex/agents/ (name, description, instructions, além de model e reasoning effort opcionais)
  • Ex.: um revisor de segurança pode usar um modelo forte com high effort, enquanto um explorer usa um modelo rápido em read-only
• O Claude Code faz o mesmo com subagents em .claude/agents/ e agent teams que trocam tarefas
  • Nas duas ferramentas, a divisão comum é: um agente explora, outro implementa e outro valida contra a especificação (textos anteriores sobre the code agent orchestra e adversarial code review)
• Como o loop roda enquanto você não está olhando, é preciso ter um verificador confiável (verifier) para conseguir sair da frente
  • Subagents fazem seu próprio trabalho de modelo e ferramentas, então consomem mais tokens; use onde uma segunda opinião realmente vale a pena
  • É isso que o /goal do Claude Code faz internamente — um modelo novo decide se a tarefa terminou em vez de deixar isso para quem a executou, aplicando a separação maker/checker à própria condição de parada

Como é um loop na prática

• Quando juntado, uma única thread vira um pequeno painel de controle; esta é uma forma repetidamente útil
  • Uma automation roda no repositório toda manhã, e seu prompt invoca uma skill de triagem para ler falhas de CI de ontem, issues abertas e commits recentes, registrando o resultado em um arquivo markdown ou quadro do Linear
  • Para cada item que vale a pena tratar, a thread abre uma worktree isolada, entrega um rascunho de correção a um sub-agent e um segundo sub-agent revisa esse rascunho com base na skill do projeto e nos testes existentes
  • Um connector permite que o loop abra um PR e atualize o ticket; o que o loop não consegue resolver vai para a caixa de entrada de triagem
  • O arquivo de estado (state file) é a espinha dorsal de tudo — lembra o que foi tentado, o que passou e o que ainda está em aberto, para que a execução da manhã seguinte continue de onde a de hoje parou
• O ponto central é que você não fez prompt para nenhuma dessas etapas; projetou tudo uma vez, e seja no Codex ou no Claude Code, os componentes são os mesmos, então o loop também é

O que o loop ainda não faz por você

• Loops mudam o trabalho, mas não apagam a pessoa; na verdade, quanto melhores eles ficam, mais agudos ficam três problemas
• A validação ainda é sua responsabilidade
  • Um loop não supervisionado também erra sem supervisão
  • Separar o sub-agent verifier do maker dá sentido ao "terminou" do loop, mas mesmo assim "done" continua sendo uma alegação, não uma prova (texto anterior sobre code review in the age of AI — o trabalho é entregar código cujo funcionamento foi confirmado)
• Entendimento apodrece se for negligenciado
  • Quanto mais rápido o loop entrega código que você não escreveu diretamente, maior fica a distância entre o que existe e o que você realmente entende
  • Isso é comprehension debt, e um loop suave acelera ainda mais esse gap se você não ler o que ele produziu
• A postura confortável é a postura perigosa
  • Quando o loop roda sozinho, fica fácil parar de ter opinião e aceitar exatamente o que ele devolve (cognitive surrender)
  • Projetar loops é remédio quando feito com julgamento, e acelerador quando usado para evitar pensar — a mesma ação, com resultado oposto

Construa o loop, mas continue sendo engenheiro

• Isso parece um preview de como o trabalho vai evoluir, mas se você não revisar o código diretamente ou depender apenas de loops automáticos, a qualidade do produto pode cair e você pode entrar em uma espiral descendente para um buraco cada vez mais fundo
• Configure loops, mas fazer prompt diretamente para agentes ainda continua eficaz; o essencial é encontrar o equilíbrio adequado
• Loops produzem resultados opostos dependendo da pessoa — entre duas pessoas que criam o mesmo loop, uma o usa para acelerar um trabalho que entende profundamente, e a outra para evitar entender o trabalho
  • O loop não sabe a diferença, mas você sabe
• É por isso que projetar loops não é mais fácil do que prompt engineering; é mais difícil — o ponto de Cherny não é que o trabalho ficou fácil, e sim que o ponto de alavancagem mudou
• Conclusão: construa loops, mas faça isso como alguém que vai continuar sendo engenheiro, e não apenas a pessoa que aperta o botão de iniciar

[shakespeares]

A verificação ainda continua sendo responsabilidade sua

A compreensão apodrece quando é negligenciada

Uma postura confortável é uma postura perigosa

=> No fim, é preciso conferir diretamente e fazer prompting para minimizar o trabalho repetitivo.