Como integrar o trabalho de vários agentes de IA sem quebrar o main

Resposta curta: integre em série, numa branch de integração separada do main, com um portão automático (testes, lint, análise estática) decidindo se cada merge existe, e nunca deixe um agente de IA fazer o merge do próprio trabalho. O paralelismo acontece na produção do código; a integração é serial por natureza, e aceitar esse fato é o que evita o main quebrado.

Por que a integração é onde o paralelismo cobra a conta

Três agentes de IA produzem três branches que passam nos testes separadamente e ainda assim quebram juntas: um renomeou um método que o outro chamou, dois mexeram no mesmo arquivo de rotas, o terceiro assumiu um schema que mudou. O git acusa conflito textual, mas o conflito semântico (código que compila e faz a coisa errada) só aparece quando os trabalhos se encontram. Quanto mais agentes em paralelo, mais cara fica cada hora sem integrar.

A receita: branch de integração e merge em série

O arranjo que tem se mostrado estável: o main recebe só o que já foi integrado e validado; uma branch de integração (chame de stage, develop, o nome não importa) recebe os merges; e cada agente de IA trabalha numa branch própria, saída da integração, de preferência numa worktree do git para nem dividir diretório. O site em que você lê este texto foi construído assim: 59 merges de branches de agente em três semanas, medidos no próprio repositório em agosto de 2026, nenhum deles direto no main.

O portão: o merge só existe se a verificação passar

Um portão é um script único que roda a suíte de testes, o formatador, a análise estática e o build antes de qualquer merge, e barra o merge se qualquer etapa falhar. O ponto é ser binário e automático: sem "passou quase tudo". Com agentes de IA o portão importa mais do que com humanos, porque o agente tem confiança demais no próprio diff e vai declarar pronto o que não está.

Como é o script do portão, na prática?

O nosso é mais longo, principalmente por causa das mensagens de erro legíveis e das flags para pular as etapas lentas, mas a ideia inteira cabe em dez linhas de shell. Esta é a versão simplificada do script que guarda os merges no repositório deste site:

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

php artisan test --compact             # a suíte inteira
vendor/bin/pint --test                 # estilo, só confere, não muta nada
vendor/bin/phpstan analyse             # análise estática
if ! git diff --quiet origin/stage... -- resources/ package.json; then
  npm run build                        # build só quando o diff encosta no front
fi
composer audit --no-scripts            # CVE conhecida nas dependências PHP
npm audit --audit-level=high           # CVE conhecida nas dependências JS

echo "portão passou"

Dois detalhes importam mais que a lista de etapas. O portão só confere, nunca conserta: formatador que reescreve arquivo durante a verificação esconde o problema em vez de relatar. E toda etapa sai com código diferente de zero quando falha, que é o que, junto com o set -e, torna o resultado binário em vez de um relatório que alguém precisa interpretar.

Quem deve fazer o merge, você ou o agente de IA?

O agente propõe, o humano integra. Deixar o agente de IA mergear o próprio trabalho junta o autor e o juiz na mesma cabeça, e o viés de quem escreveu sobrevive à revisão de quem escreveu. Vale até para revisão: revisar com um agente novo, que não produziu o código, encontra o que o autor não vê. O merge é uma decisão, não uma etapa do script.

E quando dois agentes de IA terminam ao mesmo tempo?

Fila, e o mecanismo é mais interessante do que parece. O primeiro integra; o segundo atualiza a própria branch com o resultado do primeiro, roda o portão de novo e só então integra. A fila serializa exatamente o passo que precisa ser serial, e nada mais: a produção de código continua paralela o tempo todo.

Onde a fila mora é a parte que quase todo mundo erra. Ela não pode morar no repositório, porque arquivo commitado numa branch não existe na outra, e cada agente está sentado na branch dele e na worktree dele. Então o estado vai para um diretório compartilhado fora do git: um arquivo com quem está esperando, outro com o nome de quem é o condutor da vez. Quem entra primeiro vira condutor e mergeia; os outros leem que estão aguardando e encerram o turno. Quando o condutor conclui, o mesmo script promove o próximo da fila, e é isso que decide a ordem: chegada, não antiguidade, nem quem grita mais alto.

A única etapa que precisa de trava é entrar na fila contra eleger o próximo condutor, porque dois agentes fazendo as duas coisas no mesmo instante poderiam se achar condutores ao mesmo tempo. O resto pode ser arquivo simples, e arquivo simples é o que faz isso sobreviver a um reinício de máquina no meio de uma integração.

Quanto custa integrar em série?

O custo é real: com o portão levando alguns minutos por rodada, integrar cinco branches é meia hora só de verificação, e o segundo da fila espera o primeiro. A alternativa custa mais caro: um main quebrado para todos os agentes ao mesmo tempo, e a tarde inteira de arqueologia para achar qual combinação de merges quebrou. Meia hora de espera é preço que você consegue prever; a tarde de arqueologia, não.