# Merge queue para agentes de IA: mantenha o main verde

URL: https://agentvera.dev/pt/blog/merge-queue-for-ai-agents/ · Publicado: 2026-10-18

Por que branches de agentes de IA em paralelo quebram o main mesmo passando sozinhos, o que é uma merge queue e como o AgentVera faz merge, testa e integra em ordem.

**Resumo:**

- Branches que passam cada um nos próprios testes ainda podem quebrar o main juntos, porque cada um foi testado contra uma base mais antiga.
- A merge queue do AgentVera faz merge de cada branch sobre a ponta atual do branch de destino, numa worktree própria, e roda um check no resultado.
- Um conflito abre um agente resolvedor e um check que falha tem no máximo duas rodadas de correção; por padrão, um branch aprovado espera seu OK antes de entrar.

Uma merge queue para agentes de IA é o jeito mais confiável de manter o main verde quando você roda mais de um agente ao mesmo tempo. Com um agente só não tem drama: ele trabalha num branch, você olha, você faz merge. Mas quando três ou quatro agentes começam a terminar trabalho nos próprios branches, a coisa muda. Cada branch passa sozinho, você faz merge de um depois do outro, e o main fica vermelho.

Este post explica por que branches de agentes em paralelo quebram o main, como uma merge queue resolve isso e como a merge queue do AgentVera funciona passo a passo.

## Verde sozinho, vermelho junto

Comece com um exemplo. O main tem uma função `formatPrice(amount)`. Você roda dois agentes ao mesmo tempo:

- **Agente A** adiciona um parâmetro de moeda: `formatPrice(amount, currency)`, e atualiza todos os pontos de chamada.
- **Agente B** cria uma nova tela de fatura que chama `formatPrice(amount)`.

Os dois branches saíram do mesmo main. Os testes de A passam, porque no mundo de A a tela de fatura não existe. Os testes de B passam, porque no mundo de B a função ainda recebe um argumento. O Git também não vê conflito: os dois branches mexeram em arquivos diferentes.

Você faz merge de A, depois de B. O Git não reclama. Mas agora o main chama uma função de dois parâmetros com um argumento só, e a checagem de tipos falha.

Isso é um conflito semântico: nenhum conflito de texto, mas as mudanças quebram uma à outra. Agentes em paralelo tornam isso mais comum porque:

- **Agentes não se enxergam.** Cada um trabalha na própria worktree e não faz ideia do que os outros estão fazendo.
- **Branches se acumulam rápido.** No meio da tarde pode haver cinco ou seis branches esperando.
- **Cada branch foi testado numa base antiga.** Quanto mais um branch espera, mais desatualizada fica sua base.
- **Fazer merge em ordem na mão é chato.** Depois de cada merge você atualiza o próximo branch, roda os testes de novo e resolve conflitos. As pessoas começam a pular essa etapa.

## O que é uma merge queue?

Uma merge queue enfileira os branches que esperam para entrar, faz merge de cada um sobre a ponta atual do branch de destino e testa esse resultado. A ideia é simples: antes de um branch entrar, teste como o main vai realmente ficar depois que ele entrar.

Comparando com o merge na mão:

| | Merge na mão | Merge queue |
| --- | --- | --- |
| Onde o teste roda | Na base do próprio branch | Ponta atual do main + o branch |
| Conflitos semânticos | Descobertos depois de chegar ao main | Pegos antes de entrar |
| Ordem | Quem clicar primeiro | Ordem da fila |
| Um branch quebrado | Quebra o main | É rejeitado, o main fica limpo |

O GitHub também tem uma merge queue no nível do repositório, que enfileira pull requests e os testa junto com a versão mais recente do branch de destino. A fila do AgentVera aplica a mesma ideia no seu desktop, para os branches dos seus agentes, e acrescenta agentes que resolvem conflitos de merge e corrigem checks que falham no caminho.

## Como a merge queue do AgentVera funciona

A fila fica no app desktop em **Details → Automation → Merge queue**. Cada projeto tem uma fila; num projeto com vários repositórios, cada repositório tem sua própria fila e configurações. Os branches entram um de cada vez.

### 1. Um branch entra na fila

Há três formas de entrar:

- **Na mão:** digite o nome do branch no campo **Branch**, opcionalmente dê um **Title** e aperte **Add to queue**.
- **De uma equipe paralela:** quando uma equipe paralela termina, aperte **Queue** para enviar o branch de integração dela.
- **De uma automação:** escolha **Add to the merge queue** como entrega de uma regra de automação, e o branch do agente que terminou vai direto para a fila.

Os cartões da caixa de revisões também oferecem **Send to the merge queue**. Cada item mostra de onde veio: manual, equipe paralela ou automação.

### 2. Merge sobre a ponta atual do destino

Quando chega a vez dele, o branch é mesclado sobre a ponta atual do destino, numa worktree separada da própria fila. Sua pasta de trabalho e as pastas dos seus agentes não são tocadas. Se o repositório tem um remote, o destino é buscado primeiro e o merge é feito sobre a versão mais recente do `origin`.

Você escolhe a estratégia nas configurações: **Merge commit** ou **Squash**. Se o branch já estiver contido no destino, o item é marcado como integrado.

### 3. Um conflito ganha um agente

Se o merge der conflito, a fila não para. Ela abre um agente resolvedor e o item passa para “resolvendo conflitos”. O agente recebe a instrução de preservar a intenção dos dois lados, não deixar marcadores de conflito e fazer commit do resultado.

Quando o agente entrega, o AgentVera não acredita só na palavra dele. Ele procura arquivos não mesclados, busca marcadores `<<<<<<<` e `>>>>>>>` e confirma que o branch foi mesmo mesclado. Se algo disso falhar, o item falha e não entra.

Com o modelo automático ativado, o modelo do resolvedor é escolhido conforme a dificuldade do trabalho.

### 4. O check roda no resultado do merge

Com o resultado do merge pronto, a fila roda um comando de check. Deixe **Check** vazio e ela usa o comando de teste do projeto, ou escreva o seu, como `pnpm typecheck && pnpm test`.

Se o check falhar, o agente resolvedor recebe o final da saída e tenta corrigir. São no máximo duas rodadas de correção. Se o check continuar vermelho, o item é **rejeitado** e a fila segue em frente. O branch quebrado nunca chega ao main.

É exatamente o que acontece no exemplo do `formatPrice`: o branch de B é mesclado sobre um main que já tem A, a checagem de tipos falha, o resolvedor atualiza a chamada da tela de fatura para a nova assinatura, e o check fica verde.

### 5. Aprovação e integração

Um branch que passa fica pronto. Por padrão **Land passing branches automatically** está desligado, então o item espera como “pronto, aguardando aprovação” e você recebe uma notificação. Dê uma olhada e aperte **Land** quando estiver satisfeito.

A integração funciona assim:

- **Com um remote,** o resultado do merge recebe push para o branch de destino. Repositórios do GitHub usam o login do GitHub no seu computador.
- **Sem um remote,** o branch de destino local avança em fast-forward. Ele nunca é movido por baixo de trabalho sem commit.
- **Se o destino mudou nesse meio-tempo,** o item é refeito sobre a nova ponta e testado de novo. Isso acontece no máximo três vezes; se o destino continuar mudando, o item falha.

Feche e reabra o app, e o trabalho que foi interrompido não se perde; ele volta para a fila.

## Configurações

Não são muitas, e todas ficam na mesma aba:

| Configuração | O que faz | Padrão |
| --- | --- | --- |
| Target branch | O branch onde o trabalho entra | Vazio: branch padrão |
| Merge | Merge commit ou Squash | Merge commit |
| Check | Comando rodado no resultado do merge | Vazio: o comando de teste do projeto |
| Land passing branches automatically | Integra branches aprovados sem pedir confirmação | Desligado |

Para itens na fila você pode reordenar com **Up** e **Down**, parar um com **Cancel** e reiniciar um que falhou ou foi cancelado com **Retry**. Cada item tem seu próprio log e histórico, e itens com pull request têm um botão para abri-lo no GitHub.

A fila divide recursos com outros trabalhos em segundo plano e tem prioridade: merges vêm antes de automações e equipes paralelas. Agentes que você inicia por conta própria nunca entram em fila.

## Equipes paralelas e a fila juntas

A merge queue rende mais com uma equipe paralela. Uma equipe paralela divide um trabalho grande em até oito partes; por padrão três agentes rodam ao mesmo tempo, cada um na sua worktree. As partes são mescladas num branch de integração, e um agente de integração cuida dos conflitos e do check.

Quando a equipe termina, você tem um branch de integração. Aperte **Queue** para enviá-lo. Outra equipe ou uma automação pode ter mandado algo para o main nesse meio-tempo; a fila pega tudo em ordem, testando cada um no main mais recente.

Para uma visão mais ampla de trabalhar com vários agentes, veja [agentes de código em paralelo](/pt/blog/parallel-coding-agents/).

## Erros comuns

- **Check vazio e nenhum comando de teste.** A fila ainda faz merge, mas sem nada para verificar ela não consegue pegar conflitos semânticos. Defina o comando de teste do projeto ou coloque um comando em **Check**.
- **Só testes unitários.** Muitas quebras como a do exemplo aparecem na checagem de tipos ou no build. Inclua isso no check.
- **Ativar a integração automática no primeiro dia.** Não ative **Land passing branches automatically** antes de observar a fila por um tempo. Aprove na mão por algumas semanas primeiro.
- **Branches enormes.** A fila aceita, mas as chances de conflitos e falhas crescem com o tamanho. Dê aos agentes trabalhos pequenos e focados.
- **Ignorar itens rejeitados.** Uma rejeição geralmente aponta para um choque real de design. Leia o log e devolva o trabalho ao agente com uma observação, se precisar.

## Um dia de exemplo

### Manhã

Você inicia três agentes em três trabalhos: a página de checkout, a API de relatórios e uma atualização de dependências. Cada um trabalha na sua worktree. Também há uma falha de CI da noite anterior; uma regra de automação já a pegou e mandou a correção para a fila.

### Fim da manhã

À medida que os agentes terminam, você abre os cartões deles na caixa de revisões. A página de checkout e a API de relatórios estão boas, então você usa **Send to the merge queue** nas duas. A fila agora tem três itens: a correção de CI, a página de checkout e a API de relatórios.

### Meio-dia

A correção de CI passa no check e espera aprovação. Você aperta **Land**. A página de checkout é mesclada sobre o novo main e passa. A API de relatórios conflita com um tipo que a página de checkout mudou; o agente resolvedor entra, atualiza os pontos de chamada, e o check fica verde. Tudo o que você fez foi aprovar duas vezes.

### Tarde

A atualização de dependências continua vermelha depois de duas rodadas de correção e é rejeitada. O main fica limpo. O log mostra uma mudança de versão major numa biblioteca, então você devolve o trabalho a um agente com instruções mais restritas.

## Checklist

- [ ] O projeto tem um comando de teste, ou há um comando em **Check**?
- [ ] O check cobre a checagem de tipos e o build?
- [ ] O **Target branch** está certo? Vazio significa o branch padrão.
- [ ] A estratégia de merge combina com o hábito da sua equipe: Merge commit ou Squash?
- [ ] **Land passing branches automatically** está ligado ou desligado de propósito?
- [ ] Para repositórios do GitHub, você está logado no GitHub neste computador?
- [ ] Os trabalhos dos seus agentes são pequenos e focados?

## Concluindo

Agentes em paralelo são rápidos, mas velocidade que quebra o main não dura. Uma merge queue faz merge e testa cada branch sobre o main mais recente, então branches que passam sozinhos não conseguem quebrar o main juntos. No AgentVera a fila entrega conflitos e checks que falham a um agente, verifica o resultado por conta própria e, por padrão, deixa a decisão final com você.

Leia mais:

- [Merge queue](/pt/features/merge-queue/)
- [Equipe paralela](/pt/features/parallel-team/)
- [Git e GitHub](/pt/features/git-and-github/)
- [Git worktrees para agentes em paralelo](/pt/blog/git-worktree-parallel-agents/)
- [Revisão de código com IA](/pt/blog/ai-code-review/)

Para experimentar o AgentVera, comece pela [página inicial](/pt/).

## Perguntas frequentes

**O que é uma merge queue?** Uma merge queue enfileira os branches que esperam para entrar, faz merge de cada um sobre a ponta atual do branch de destino e testa esse resultado antes de integrar. Dois branches que passam sozinhos não conseguem quebrar o main juntos.

**Por que o main quebra se todos os branches passaram nos próprios testes?** Cada branch foi testado contra um main mais antigo. Se o main mudou nesse meio-tempo, duas mudanças podem conflitar no significado sem conflitar no texto, e só testar o resultado do merge mostra isso.

**O que a merge queue do AgentVera faz quando há conflito?** Ela abre um agente resolvedor que preserva a intenção dos dois lados e faz commit. Depois o AgentVera confere que não sobrou nenhum marcador de conflito e que o branch foi mesmo mesclado. Se não, o item falha e nunca entra.

**Branches aprovados entram sozinhos?** Não por padrão. Com “Land passing branches automatically” desligado, um branch que passa nos checks espera sua aprovação e entra quando você aperta Land. Você pode ativar essa opção.

**Qual plano inclui a merge queue?** A merge queue está nos planos Pro e Team. No app desktop ela fica em Details → Automation → Merge queue.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/