O que é engenharia de loops em agentes de IA?

O que significa projetar loops

Projetar loops é definir o ciclo repetitivo executado por um agente de IA: o que o desperta, a que pode aceder, como o resultado é verificado e o que o faz parar. A engenharia de prompts molda uma mensagem enviada a um modelo. A engenharia de loops molda o processo que envia milhares de mensagens enquanto está a dormir. A unidade de trabalho deixa de ser o prompt e passa a ser o loop.

Em resumo: deixa de escrever instruções e passa a escrever um sistema de controlo. O agente continua a precisar de boas instruções, mas estas passam a ser um componente de um ciclo que é executado segundo um agendamento, trabalha numa cópia isolada do seu código, comprova o próprio resultado com um teste e desiste quando o orçamento se esgota.

Por que o termo apareceu em 2026

O nome está a ser definido publicamente neste momento. O repositório do GitHub cobusgreyling/loop-engineering ultrapassou 9,600 estrelas nos dois meses seguintes à sua primeira aparição (em julho de 2026), com a frase "Stop prompting. Design the loop. Get a score.". O repositório reúne esta mudança em seis componentes: agendamento, worktrees, skills, plugins e conectores, subagentes e memória persistente mantida fora da conversa.

O texto cita Boris Cherny, que lidera o Claude Code na Anthropic:

Já não escrevo prompts para o Claude. Tenho loops a executar prompts para o Claude.

Um segundo repositório, AI-Builder-Club/skills, tem cerca de 1,100 estrelas (em julho de 2026) e identifica diretamente as duas funções: um "harness de codebase", que torna um repositório seguro para um agente executar testes e deploys, e um "engenheiro de loops", que cria workflows que são ativados por um trigger, executam o trabalho e escrevem o que aprenderam num ficheiro partilhado para que o loop seguinte o possa ler.

Nenhum dos dois repositórios inventou esta prática. Quem já executou um build noturno, um linter em integração contínua ou um cron job que abre um ticket já conhece o modelo. A novidade é que o worker dentro do loop é agora não determinístico, o que altera o que a infraestrutura envolvente tem de fazer.

As quatro partes de um loop

Todo loop funcional tem estas quatro partes. Um loop que ignora uma delas é o loop que o acorda às 3am.

• Gatilho. O evento que inicia uma execução: um temporizador, um webhook, um novo pull request ou um alerta.
• Limite. Os ficheiros, as credenciais e a rede a que o agente pode aceder durante essa execução.
• Verificação. Uma verificação com um código de saída que determina se o resultado da execução é mantido ou descartado.
• Orçamento. O limite de tokens, tempo e dinheiro que termina uma execução, tenha ela sido bem-sucedida ou não.

Transforme estas quatro partes em perguntas e terá uma revisão de design para qualquer agente que esteja prestes a deixar em execução.

Gatilho: o que acorda o agente

Um timer é o gatilho mais simples. Num servidor Linux, um timer do systemd é melhor do que o cron neste caso porque regista eventos, permite definir as tentativas novamente e não inicia uma segunda cópia de uma unidade que ainda esteja em execução. Esta última propriedade elimina o erro de sobreposição mais comum nos ciclos de agentes: duas execuções a editar a mesma branch.

Escreva a unidade em /etc/systemd/system/agent-loop.service:

[Unit]
Description=Agent loop: triage open issues
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
User=agent
WorkingDirectory=/srv/agent/repo
ExecStart=/srv/agent/bin/loop.sh
TimeoutStartSec=1800

E o timer em /etc/systemd/system/agent-loop.timer:

[Unit]
Description=Run the triage loop every 30 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=30min
Unit=agent-loop.service

[Install]
WantedBy=timers.target

sudo systemctl daemon-reload
sudo systemctl enable --now agent-loop.timer
systemctl list-timers agent-loop.timer

systemctl list-timers deve apresentar uma coluna NEXT com uma hora no futuro e uma coluna LEFT com a contagem decrescente. Um resultado vazio significa que o timer não está ativado, porque enable sem --now agenda-o apenas para o próximo boot. TimeoutStartSec=1800 é mais importante do que parece: um agente bloqueado à espera de entrada manteria a unidade ativa indefinidamente, e o timer nunca seria executado novamente. Consulte uma execução com journalctl -u agent-loop.service -n 50.

Se conduzir o ciclo a partir do cron, adicione a sua própria proteção contra sobreposição, porque o cron inicia uma segunda cópia sem qualquer problema:

*/30 * * * * /usr/bin/flock -n /tmp/agent-loop.lock /srv/agent/bin/loop.sh

flock -n termina imediatamente com o status 1 quando o lock está ocupado. Assim, a segunda execução desaparece silenciosamente em vez de entrar em conflito com a primeira. A mesma configuração de serviço e timer do systemd aplica-se a qualquer tarefa de longa duração no servidor, seja um agente ou não.

Fronteira: dê a cada execução a sua própria cópia

Um agente que edita a sua working tree pode perder o trabalho que ainda não foi commitado. Os Git worktrees resolvem este problema com baixo custo: cada execução recebe o seu próprio diretório e a sua própria branch, partilhando o mesmo object store.

cd /srv/agent/repo
git worktree add -b loop/triage-01 /srv/agent/work/triage-01 origin/main
git worktree list

git worktree list imprime uma linha por tree, com o respetivo caminho, commit e branch. Quando a execução termina, git worktree remove /srv/agent/work/triage-01 elimina o diretório, e git worktree prune limpa as entradas cujo diretório desapareceu. A partir deste ponto, os loops paralelos tornam-se seguros, porque dois agentes em duas branches e em dois diretórios não podem substituir o trabalho um do outro.

A fronteira também diz respeito às credenciais. Um loop executado sem supervisão mantém tokens de longa duração, e cada execução pode expor um deles num log, num commit ou no contexto de um modelo. Restrinja o token ao único repositório que o loop utiliza, mantenha-o fora do ambiente visível pela própria shell do agente sempre que possível e leia como manter segredos fora dos agentes de IA antes de dar acesso de produção a um loop. Para obter uma barreira mais forte, coloque o loop completo numa VM descartável que possa destruir depois de cada execução. A ferramenta que utiliza também define parte da fronteira antes de escrever qualquer configuração, por isso vale a pena ler como o sandbox gerido do Cowork se compara com o Claude Code na sua própria máquina antes de decidir quanto isolamento precisa de criar por conta própria.

Verificação: o mecanismo que torna o loop seguro

Esta é a parte que distingue um loop de um cron job que apenas introduz texto. A saída do agente é uma proposta. O mecanismo decide.

#!/usr/bin/env bash
set -euo pipefail

repo=/srv/agent/repo
branch="loop/$(date -u +%Y%m%dT%H%M%SZ)"
tree="/srv/agent/work/$(basename "$branch")"

cd "$repo"
git fetch --quiet origin
git worktree add -b "$branch" "$tree" origin/main
cd "$tree"

# the agent's own command runs here, in non-interactive mode

if ! npm test; then
  echo "gate failed: discarding $branch" >&2
  cd "$repo"
  git worktree remove --force "$tree"
  exit 1
fi

git push origin "$branch"
cd "$repo"
git worktree remove "$tree"

set -euo pipefail faz trabalho real nesse script. Sem -e, um git fetch que falhou é ignorado e a execução continua com um origin/main desatualizado. Sem -u, um erro ortográfico no nome de uma variável é expandido para uma string vazia, e a limpeza é executada no caminho errado em vez de falhar de forma explícita.

O bloco if ! npm test contém toda a ideia. O código de saída de uma verificação em que já confia, da sua suite de testes ou do seu verificador de tipos, decide se a branch é enviada ou eliminada. Um loop sem mecanismo de verificação produz trabalho que ninguém tem tempo de rever, o que é pior do que não produzir trabalho. Um loop com um mecanismo de verificação produz uma branch que já passou o mesmo critério que a branch de um contribuidor humano tem de passar. Um mecanismo de verificação bem-sucedido não diz nada sobre a quantidade de código que o agente alterou para chegar lá. Por isso, vale a pena associar a verificação a uma instrução permanente como a regra que faz o agente aplicar a alteração mínima que funciona, mantendo o diff pequeno o suficiente para que a revisão continue barata.

Escolha um mecanismo de verificação que falhe de forma honesta. Uma suite de testes que passa com um diff vazio ensina ao loop que não fazer nada é um sucesso. Repositórios com testes fracos produzem loops fracos. É por isso que os repositórios em destaque colocam "preparar a base de código para agentes" antes de "escrever o loop". Se quiser saber se a sua suite detetaria realmente uma regressão, em vez de apenas executar as linhas, o mutation testing é a verificação que responde a essa pergunta. Um agente que devolve um relatório de evidências que pode ser executado novamente, em vez de lhe pedir para ler o diff transforma essa resposta em algo que pode confirmar por si mesmo.

Orçamento: o que interrompe uma execução

Um agente que tenta novamente para sempre tem um custo sem limite. Defina um limite de tempo de parede para cada loop, aplicado por TimeoutStartSec; um limite de tentativas dentro do script; e um limite de gastos aplicado pela conta do provedor. Depois, registe o custo de cada execução para detetar um loop a desviar-se antes de isso aparecer na fatura. Controlo de custos para um agente VPS sempre ativo aborda a parte contabilística, e gestão do contexto que um agente mantém entre turnos aborda o maior fator individual do custo por execução, porque um loop que relê o mesmo repositório a cada 30 minutos paga por essa leitura a cada 30 minutos.

O custo é o motivo pelo qual os loops normalmente são melhores do que uma sessão longa. Uma execução que começa de novo, realiza uma tarefa específica e termina mantém o contexto pequeno. Uma sessão deixada aberta durante oito horas mantém no histórico todos os erros anteriores e paga por toda a transcrição em cada turno.

Os padrões que os repositórios em destaque formalizam

O repositório loop-engineering apresenta sete padrões para produção, e vale a pena lê-los como um menu, não como um manifesto. Triagem diária. Um monitor de pull requests que acompanha os comentários de revisão e responde a eles. Um verificador de integração contínua que processa as builds com falhas. Um verificador de dependências. Um redator de changelogs. Limpeza pós-merge. Triagem de issues.

O que estes padrões têm em comum é uma tarefa restrita com uma condição de passagem evidente. "Corrigir a build com falhas" tem uma condição que a máquina consegue ler. "Melhorar a base de código" não tem, por isso nunca se transforma num loop. Transforma-se numa confusão com um agendamento.

Também têm em comum um registo escrito. Ambos os repositórios retiram o estado da conversa e colocam-no em ficheiros no repositório: o que foi executado, o que foi encontrado e o que foi decidido. Esse ficheiro é a memória do loop e permite que um segundo loop se baseie no trabalho do primeiro, em vez de o redescobrir. É também a forma de auditar um agente posteriormente, porque o contexto do modelo desaparece assim que a execução termina. A coordenação em tempo real é um canal separado, e uma sessão do Claude Code pode passar trabalho a outra na mesma máquina enquanto ambas continuam em execução, mas nada nessa troca sobrevive ao fim de qualquer uma das sessões. Por isso, o ficheiro continua a ser a parte que pode consultar mais tarde.

Onde os loops falham

As falhas são previsíveis e repetem-se entre equipas.

• Sem controlo. A saída acumula-se, ninguém a revê, a confiança desaparece e o loop é desativado.
• Sobreposição. Duas execuções no mesmo branch ou dois agentes na mesma working tree produzem conflitos que o agente tenta depois resolver.
• Desvio silencioso. O loop continua a passar porque a verificação é demasiado fraca para falhar.
• Âmbito sem limites. Um trigger que é executado em cada commit de um repositório ativo transforma-se num problema de custos em menos de um dia.

Todos têm a mesma correção: reduza o job, torne a verificação mais rigorosa e registe a execução. Se não conseguir descrever a condição de aprovação numa frase, o job ainda não está pronto para ser automatizado.

Como começar sem a terminologia

Não precisa de um framework. Um pequeno servidor Linux sempre ativo, um repositório git cuja suíte de testes falha quando deveria, um timer do systemd e um script shell com um if são suficientes para criar um ciclo completo. É precisamente por aí que a maioria das pessoas deve começar, porque as questões de conceção são respondidas ao executar o sistema, e não ao escolher uma ferramenta. Quando um ciclo está estável, executar um segundo consiste principalmente em adicionar outro timer e outro worktree. Consulte como executar um agente de IA para programação num VPS para obter a configuração base e as opções atuais de agentes de IA self-hosted se quiser executar o próprio agente em hardware que controla.

FAQ

A engenharia de loops é diferente da engenharia de prompts?

A engenharia de prompts otimiza uma mensagem: redação, exemplos e formato da saída. A engenharia de loops otimiza o ciclo em torno da mensagem: o gatilho que inicia uma execução, o sandbox em que ela é executada, a verificação que aceita ou rejeita a saída e o orçamento que a encerra. Ainda é necessário ter um bom prompt dentro do loop. Porém, o prompt deixa de ser o principal elemento ajustado no dia a dia, porque o gate e o gatilho têm mais efeito sobre o resultado.

Preciso de um framework para criar um loop de agente?

Não. Um temporizador do systemd, um git worktree por execução, um script de shell que termina com um comando de teste e um limite de gastos na conta do provedor cobrem todos os elementos da definição. Os frameworks adicionam interfaces de agendamento, formatos de memória partilhada e encaminhamento entre vários agentes. Esses recursos são úteis quando vários loops estão em execução. Eles não são um requisito inicial para o primeiro loop.

O que é um harness de codebase?

É o conjunto de recursos que permite a um agente trabalhar num repositório sem a presença de uma pessoa: uma configuração executada com um único comando, testes executados de forma não interativa e com falha explícita, um linter e uma forma de fazer deploy ou pré-visualizar uma alteração. O termo surgiu na mesma vaga de repositórios de 2026 que popularizou a engenharia de loops. O teste prático é simples: se um novo colaborador humano não consegue passar do clone até aos testes verdes com um único comando, um agente também não consegue.

Como impeço um loop de agente de gerar uma conta elevada?

Defina limites em três pontos. Configure TimeoutStartSec na unidade do systemd para que uma execução bloqueada seja terminada. Limite as tentativas dentro do script, em vez de repetir até obter sucesso. Defina um limite rígido de gastos na conta da API, porque esse é o único limite que o agente não consegue contornar por meio de argumentos. Depois, registe o custo de cada execução, porque um loop cujo custo duplica normalmente é um loop cujo âmbito aumentou silenciosamente.

Quais tarefas vale a pena transformar primeiro num loop?

Escolha uma tarefa com uma condição de aprovação legível por máquina e um raio de impacto pequeno. Corrigir um build com falha, atualizar uma dependência e regenerar um changelog são exemplos adequados, porque uma suite de testes ou um diff pode comprovar o resultado. Trabalho aberto, como refatoração ou design, ainda não é adequado, porque não há nada que o gate possa verificar. Um loop sem gate é uma forma dispendiosa de gerar dívida de revisão.