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 surgiu em 2026

O nome está a ser definido publicamente neste momento. O repositório GitHub cobusgreyling/loop-engineering ultrapassou 9,600 estrelas nos primeiros dois meses após surgir (em julho de 2026) e tinha cerca de 11,600 em 2026-10-27, sob a frase "Stop prompting. Design the loop. Get a score.". Em julho de 2026, o README agrupava a mudança em seis blocos: agendamento, worktrees, skills, plugins e conectores, sub-agents e memória persistente mantida fora da conversa. O README atual já não contém essa lista (verificado em 2026-10-27), mas continua a manter o estado do loop num ficheiro fora da conversa.

O repositório dá crédito a Boris Cherny, que lidera o Claude Code na Anthropic, como uma das suas inspirações. A frase dele, amplamente divulgada, é:

I don't prompt Claude anymore. I have loops running that prompt Claude.

Um segundo repositório, AI-Builder-Club/skills, aproxima-se das 1,300 estrelas (em 2026-10-27) e identifica diretamente os dois papéis: um "codebase harness", que torna um repositório seguro para um agente executar testes e deploys, e um "loop engineer", 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 a prática. Quem já executou uma compilação noturna, 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 desperta o agente

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

Dê primeiro ao agente o seu próprio utilizador. Esse utilizador faz parte do limite de segurança. Deve ser proprietário de /srv/agent e de mais nada:

sudo useradd --system --home-dir /srv/agent --shell /usr/sbin/nologin agent
sudo chown -R agent:agent /srv/agent

Depois, 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 mostrar 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 arranque. TimeoutStartSec=1800 é mais importante do que parece. Um serviço Type=oneshot é considerado em arranque até o seu script terminar. Por predefinição, o systemd desativa o timeout de arranque para unidades oneshot. Sem esta linha, um agente bloqueado à espera de entrada mantém a unidade para sempre no estado de ativação. Cada execução posterior do timer encontra-a ainda em execução e não inicia nada. Com a linha definida, o systemd termina a execução após 30 minutos e marca-a como falhada. Se alguma vez alterar a unidade para o valor predefinido Type=simple, TimeoutStartSec deixa de abranger a própria execução. Nesse caso, RuntimeMaxSec= é a definição que impõe o limite. Consulte uma execução com journalctl -u agent-loop.service -n 50.

Se executar o ciclo a partir do cron, adicione o seu próprio mecanismo para impedir sobreposições, porque o cron inicia uma segunda cópia sem hesitar:

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

flock -n termina imediatamente com o estado 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 ou não um agente.

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

Um agente que edita a sua working tree pode perder o trabalho não commitado. Os Git worktrees resolvem isto de forma económica: 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 path, commit e branch. Quando a execução termina, git worktree remove /srv/agent/work/triage-01 remove o worktree, mas apenas se estiver limpo. Se a tree tiver ficheiros não monitorizados ou ficheiros monitorizados modificados, ou contiver submódulos, o git recusa-se a removê-la até adicionar --force. Por isso, o script de controlo abaixo força a remoção apenas no path que elimina a execução. git worktree prune limpa as entradas cujo diretório desapareceu. A partir deste ponto, os loops paralelos são seguros, porque dois agentes em duas branches e em dois diretórios não podem substituir o trabalho um do outro.

O limite também abrange as credenciais. Um loop executado sem supervisão mantém tokens de longa duração, e cada execução pode expor um token num log, num commit ou no contexto de um modelo. Limite 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 conceder acesso de produção a um loop. Para criar uma barreira mais forte, coloque todo o loop numa VM descartável que possa destruir após cada execução. A ferramenta que executa também define parte do limite 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 controlo que torna o ciclo seguro

Esta é a parte que distingue um ciclo de um cron job que apenas introduz comandos. A saída do agente é uma proposta. O controlo 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 executa trabalho real nesse script. Sem -e, uma falha em git fetch é ignorada e a execução continua com um origin/main desatualizado. Sem -u, um erro ortográfico no nome de uma variável expande para uma cadeia vazia, e a limpeza é executada no caminho errado em vez de falhar de forma explícita. A última linha não tem --force de propósito: se a execução deixar ficheiros não rastreados ou não confirmados na árvore, o git recusa-se a removê-la, e -e termina a execução com um erro depois do push, em vez de apagar silenciosamente trabalho que ninguém confirmou.

O bloco if ! npm test contém toda a ideia. O código de saída de uma verificação em que já confia, como a sua suíte de testes ou o seu verificador de tipos, decide se o branch é enviado ou destruído. Um ciclo sem controlo produz trabalho que ninguém tem tempo para rever, o que é pior do que não produzir trabalho. Um ciclo com controlo produz um branch que já passou pelo mesmo nível de exigência que o branch de um contribuidor humano tem de passar. Um controlo verde não indica quanto código o agente alterou para chegar a esse resultado. Por isso, vale a pena associar a verificação a uma instrução permanente, como a regra que leva um agente a fazer a menor alteração que funciona, para manter o diff suficientemente pequeno e tornar a revisão rápida.

Escolha um controlo que falhe de forma honesta. Uma suíte de testes que passa com um diff vazio ensina ao ciclo que não fazer nada é um sucesso. Repositórios com testes fracos geram ciclos fracos. Por isso, os repositórios em destaque colocam "tornar a base de código preparada para agentes" antes de "escrever o ciclo". Se quiser saber se a sua suíte detetaria realmente uma regressão, em vez de apenas executar as linhas, o mutation testing é a verificação que responde a essa questão. Um agente que devolve um relatório de evidências que pode ser executado novamente em vez de lhe pedir que leia o diff transforma essa resposta em algo que pode confirmar por si próprio.

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 codificados pelos repositórios em destaque

O repositório de loop engineering lista oito padrões de produção (em 2026-10-27), e vale a pena lê-los como um menu, não como um manifesto. Triagem diária. Um loop simples que é executado como uma GitHub Action e não mantém nenhum ficheiro de estado. Um babysitter de pull requests que monitoriza comentários de revisão e responde-lhes. Um verificador de integração contínua que recolhe builds com falhas. Um verificador de dependências. Um gerador de rascunhos de changelogs. Limpeza pós-merge. Triagem de issues.

O que têm em comum é uma tarefa limitada com um gate claro. "Corrigir o build com falhas" tem uma condição de sucesso que a máquina consegue ler. "Melhorar o codebase" não tem, por isso nunca se transforma num loop. Transforma-se num problema 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 do 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 desenvolva o trabalho do primeiro, em vez de o redescobrir. Também é assim que se audita um agente posteriormente, porque o contexto do modelo desaparece assim que a execução termina. A coordenação em tempo real ocorre num 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 a qualquer uma das sessões. Por isso, o ficheiro continua a ser a parte que se consulta 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 ciclos é diferente da engenharia de prompts?

A engenharia de prompts otimiza uma mensagem: formulação, exemplos e formato da saída. A engenharia de ciclos otimiza o processo em torno da mensagem: o gatilho que inicia uma execução, o sandbox onde ela é executada, a verificação que aceita ou rejeita a saída e o orçamento que a termina. Continua a precisar de um bom prompt dentro do ciclo. No entanto, o prompt deixa de ser o elemento ajustado diariamente, porque o gate e o gatilho têm mais efeito no resultado.

Preciso de um framework para criar um ciclo de agente?

Não. Um timer do systemd, um git worktree por execução, um shell script que termina com um comando de teste e um limite de gastos na conta do fornecedor cobrem todas as partes da definição. Os frameworks acrescentam interfaces de agendamento, formatos de memória partilhada e encaminhamento entre vários agentes. Estes recursos são úteis quando executar vários ciclos. Não são um requisito inicial para o primeiro ciclo.

O que é um harness de codebase?

É o conjunto de elementos que permite a um agente trabalhar num repositório sem a presença de uma pessoa: uma configuração executada com um comando, testes que funcionam de forma não interativa e falham claramente, 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 deu origem à engenharia de ciclos. O teste prático é simples: se um novo contribuidor humano não conseguir passar do clone até aos testes verdes com um único comando, um agente também não conseguirá.

Como impeço um ciclo de agente de gerar uma fatura elevada?

Imponha limites em três pontos. Defina TimeoutStartSec numa unidade systemd Type=oneshot como a apresentada acima, para que uma execução bloqueada seja terminada. Num serviço Type=simple, o equivalente é RuntimeMaxSec. Limite as repetições 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 ultrapassar através de argumentos. Depois, registe o custo de cada execução, porque um ciclo cujo custo duplica normalmente é um ciclo cujo âmbito aumentou silenciosamente.

Que tarefas vale a pena transformar primeiro num ciclo?

Escolha uma tarefa com uma condição de sucesso legível por máquina e um impacto potencial reduzido. Corrigir uma compilação com falhas, atualizar uma dependência e gerar novamente um changelog são exemplos adequados, porque uma suite de testes ou um diff pode provar o resultado. Trabalho aberto, como refatoração ou design, ainda não é adequado, porque não existe nada que o gate possa verificar. Um ciclo sem gate é uma forma dispendiosa de gerar dívida de revisão.