Desenvolvimento

Vários agentes Claude Code em paralelo: o que funciona e o que falha

· fundador da ETCSEC · atualizado a 9 de novembro de 2026 · 6 min
A resposta curta

Para pôr vários agentes Claude Code a trabalhar ao mesmo tempo, dê a cada um o seu git worktree e o seu branch. A partir de três ou quatro agentes, os verdadeiros problemas são os conflitos de ficheiros, a revisão e o custo: é preciso um ticket por agente, um âmbito de ficheiros e uma revisão antes do merge.

Porquê paralelizar, e o que falha a partir do segundo agente

Uma equipa de desenvolvimento humana quase nunca trabalha com um único engenheiro de cada vez num projeto ativo: várias pessoas avançam em paralelo em partes diferentes do mesmo repositório, com um sistema de branches, de revisão e de integração já rodado para isso há anos. A mesma lógica aplica-se a agentes Claude Code: em princípio, nada impede fazer avançar vários agentes no mesmo projeto ao mesmo tempo, desde que cada um se mantenha no seu próprio âmbito, da mesma forma que se esperaria de um engenheiro humano que não tocasse no módulo de um colega sem coordenação prévia.

Fazer trabalhar um único agente Claude Code de cada vez tem uma limitação simples: o tempo total continua a ser a soma do tempo de cada tarefa, mesmo quando várias tarefas não têm rigorosamente nada em comum. Traduzir um artigo em seis línguas, corrigir um erro do lado do servidor enquanto se desenvolve uma página de documentação, ou avançar três tickets independentes de uma mesma ficha de trabalho são casos em que nada obriga a esperar que um agente termine antes de lançar o seguinte. Paralelizar vários agentes Claude Code, seja através de subagentes numa mesma sessão, de equipas de agentes coordenadas, ou de sessões independentes em worktrees separados, promete reduzir esse tempo total ao tempo da tarefa mais longa, em vez da soma de todas as tarefas.

Lançar vários agentes em paralelo quase nunca é o problema: qualquer terminal consegue abrir várias sessões Claude Code em poucos segundos. Os problemas começam assim que dois agentes tocam, ainda que brevemente, num estado partilhado, seja um ficheiro, um branch, uma porta de servidor local ou um orçamento de revisão já ocupado noutro lado. Há quatro sintomas que se repetem, mais ou menos por esta ordem de aparecimento à medida que o número de agentes aumenta.

O primeiro sintoma é o conflito de ficheiros: dois agentes que alteram o mesmo ficheiro ao mesmo tempo, no mesmo diretório de trabalho, acabam quase sempre por sobrepor parte do trabalho um do outro, sobretudo quando nenhum dos dois relê o estado mais recente antes de fazer commit. O risco agrava-se ainda mais quando os dois agentes partilham o mesmo diretório de trabalho Git, o que significa que cada um vê, no mesmo instante, as alterações ainda não submetidas do outro, muito antes de qualquer um dos dois as poder validar.

O segundo sintoma é o contexto perdido: um agente que retoma uma tarefa depois de outro agente ter alterado um ficheiro vizinho trabalha por vezes sobre uma versão do código que já deixou de existir, porque o seu próprio contexto de conversa nunca foi informado da alteração. Este desfasamento nem sempre produz um erro visível de imediato; produz muitas vezes um código que compila, que parece correto localmente, mas que contradiz uma decisão tomada entretanto por um agente vizinho no mesmo ficheiro ou num ficheiro que dele depende.

O terceiro sintoma é a revisão que satura: cada agente adicional produz um diff adicional para rever, e a revisão não se paraleliza tão facilmente como a escrita, porque exige atenção humana ou uma revisão automatizada cuja capacidade se mantém, essa, mais ou menos fixa. Segundo um estudo da CodeRabbit divulgado pelo The Register em dezembro de 2025, os pull requests coescritos por IA contêm 1,7 vezes mais problemas do que os pull requests escritos sem assistência: multiplicar os agentes sem multiplicar a capacidade de revisão equivale a acumular uma dívida que só se torna visível no momento da integração.

O quarto sintoma é o custo, que sobe mais depressa do que o número de agentes, em vez de crescer ao mesmo ritmo: cada agente reconstrói parte do seu próprio contexto em cada sessão, cada conflito resolvido a posteriori volta a consumir tokens para rever e corrigir, e uma coordenação mal definida entre agentes acrescenta idas e voltas que não existiriam com um único agente. A documentação do Claude Code sobre a gestão de custos recomenda, precisamente por esta razão, delimitar o âmbito de cada sessão antes de a lançar, em vez de o deixar crescer ao longo da conversa.

Estes quatro sintomas não são argumentos contra a paralelização em si: indicam apenas que, para lá de um único agente, o trabalho de coordenação não desaparece, desloca-se da escrita do código para a definição do âmbito, dos critérios e da revisão. A secção seguinte detalha, passo a passo, como estabelecer este enquadramento antes de lançar o segundo agente, em vez de o fazer depois de se constatar o primeiro conflito.

Vista geral de um projeto na Atipol: agentes por estado, dois agent leads
Vários agentes em paralelo, por estado: a trabalhar, em revisão, bloqueados, com os respetivos agent leads.

Método passo a passo para manter o controlo

Cinco práticas cobrem a maior parte dos sintomas descritos acima. Nenhuma depende de uma ferramenta em particular: aplicam-se tanto a subagentes numa mesma sessão como a sessões independentes lançadas em worktrees separados. Apresentam-se por esta ordem, porque cada uma reduz um risco que a seguinte já não consegue corrigir totalmente depois de este ter ocorrido.

A primeira prática é um worktree Git e um branch por agente. O comando git worktree add cria um diretório de trabalho separado, com o seu próprio estado de ficheiros, partilhando ao mesmo tempo o mesmo histórico Git que o repositório principal: dois agentes instalados em dois worktrees diferentes deixam de poder, por construção, ver ou sobrepor os ficheiros não submetidos um do outro, mesmo que trabalhem no mesmo instante sobre o mesmo repositório. A documentação do Claude Code sobre os fluxos de trabalho correntes descreve precisamente este esquema para fazer correr várias sessões em paralelo sem que se pisem, mantendo-se cada sessão no seu próprio branch até que um merge explícito aproxime o trabalho dos outros. Um agente que termina a sua tarefa deixa atrás de si um branch pronto a rever, que a integração aceite ou rejeite sem nunca ter tocado no diretório de trabalho dos agentes ainda em curso.

A segunda prática é um âmbito de ficheiros definido por tarefa, antes de o agente começar a escrever. Um ticket que especifique exatamente que ficheiros ou que pastas um agente pode alterar retira grande parte do risco de conflito antes mesmo de este surgir, uma vez que dois agentes cujos âmbitos não se sobrepõem não podem, por definição, escrever no mesmo ficheiro. Este âmbito deve permanecer mais estreito do que aquilo que a função geral do agente permitiria, porque é o ticket em curso, e não o papel do agente, que determina aquilo de que uma tarefa precisa realmente. Um âmbito demasiado amplo, mesmo com boas intenções, equivale a devolver aos agentes a mesma exposição de um único agente sem qualquer divisão, apenas repartida entre várias sessões em vez de concentrada numa só.

A terceira prática é escrever os critérios de aceitação antes de lançar o agente, não depois de ler a sua entrega. Um critério escrito antecipadamente, do tipo «o comando de build passa» ou «as cinco traduções retomam as mesmas secções», dá ao agente um alvo verificável e dá ao seu revisor um teste objetivo em vez de uma impressão geral sobre a qualidade do resultado. Sem um critério prévio, a revisão deriva para uma apreciação caso a caso, que rapidamente se torna incoerente de um agente para outro e de uma tarefa para outra. Este mesmo critério serve também de ponto de paragem: um agente que não consiga satisfazê-lo sinaliza um bloqueio antes da revisão, em vez de entregar um resultado aproximado na esperança de que passe despercebido.

A quarta prática é uma revisão antes de qualquer merge, nunca depois. Um diff revisto antes do merge ainda pode ser corrigido sem afetar o trabalho dos outros agentes; um diff que passa primeiro pelo merge e só é revisto depois obriga a desfazer um histórico já partilhado, com o risco de remover, de passagem, um trabalho válido feito entretanto por um agente vizinho num ficheiro que dele depende. A revisão deve incidir sobre o diff real, não apenas sobre o resumo que o agente fornece do seu próprio trabalho, precisamente porque um resumo otimista nem sempre revela um critério de aceitação que ficou por satisfazer. Esta disciplina custa um pouco de tempo em cada entrega, mas custa sempre menos do que desembaraçar, depois de um merge, qual dos dois agentes produziu qual parte de um mesmo ficheiro.

A quinta prática é limitar o número de sessões simultâneas àquilo que a revisão consegue realmente absorver. A documentação do Claude Code sobre subagentes e equipas de agentes recomenda começar com três a cinco colegas de equipa antes de considerar ir mais além, lembrando que dois agentes no mesmo ficheiro produzem quase sempre uma sobreposição em vez de um merge limpo. Este número não é um limite técnico do protocolo; é um limite prático daquilo que um revisor, humano ou automatizado, consegue verificar seriamente antes de integrar. Aumentar este número continua a ser possível mais tarde, assim que o âmbito de ficheiros, os critérios de aceitação e a revisão antes do merge já estiverem rodados com um pequeno número de agentes.

Tabela de armadilhas e soluções

A tabela seguinte retoma as armadilhas mais frequentes observadas para lá de dois agentes, com o seu sintoma concreto e a solução que o evita; cada solução remete diretamente para uma das cinco práticas da secção anterior.

ArmadilhaSintomaSolução
Dois agentes no mesmo ficheiroSobreposição de parte do trabalho antes do commit ou no mergeUm worktree e um branch por agente
Âmbito de tarefa pouco claroDois agentes alteram ficheiros que se sobrepõem sem o saberUm âmbito de ficheiros escrito no ticket antes do lançamento
Critério de aceitação ausenteA entrega parece concluída mas não responde ao pedido realCritérios de aceitação escritos antes do lançamento do agente
Merge antes da revisãoUm defeito descoberto a posteriori obriga a desfazer um histórico partilhadoUma revisão do diff real antes de qualquer integração
Demasiadas sessões ao mesmo tempoA revisão satura e a dívida de código acumula-se sem ser vistaUm número de sessões simultâneas limitado àquilo que a revisão absorve
Contexto não partilhado entre agentesUm agente trabalha sobre uma versão do código já alterada por outroUm ticket por agente com o seu próprio âmbito, revisto antes do merge

Como a Atipol procede

Na Atipol, cada agente trabalha no seu próprio worktree Git, no seu próprio branch: dois agentes nunca alteram os mesmos ficheiros no mesmo instante, por construção e não por disciplina individual. Cada ticket reserva um âmbito de ficheiros antes de o agente começar a escrever, e dois tickets em curso não podem reservar o mesmo âmbito: o risco de sobreposição entre dois agentes é retirado antes do primeiro commit, e não no momento do merge. Esta reserva é verificada no próprio momento em que o ticket é transmitido a um agente, não a posteriori numa revisão de fim de semana, o que evita que uma sobreposição só seja descoberta depois de os dois agentes já terem escrito nas mesmas linhas.

Cada ticket exige critérios de aceitação escritos antes do lançamento do agente, o que evita que uma tarefa termine sem se saber precisamente o que tinha de ser verdade para a considerar concluída. O agent lead do projeto revê cada entrega antes de a integrar, e essa integração volta a correr os controlos do projeto em vez de confiar apenas na revisão que a precedeu. Esta revisão incide sobre o diff real produzido pelo agente, e a integração que se segue não se contenta com o parecer do revisor: ela própria volta a correr os controlos do projeto, para que um esquecimento na revisão não se transforme num defeito silencioso no branch principal.

O número de sessões simultâneas regula-se ao nível do projeto, para que a carga de revisão e o custo em tokens fiquem sob o controlo da equipa, em vez de crescerem apenas com o número de agentes que se poderia lançar. Esta regulação permanece nas mãos da equipa responsável pelo projeto, e não é um parâmetro fixado de uma vez por todas pela própria plataforma. A Atipol não está limitada ao Claude Code: o mesmo enquadramento de tickets, de âmbito de ficheiros e de revisão antes da integração aplica-se a outros agentes de desenvolvimento.

Organigrama em árvore na Atipol: pessoas, agent leads, agentes e subagentes
Quem pilota o quê: cada pessoa tem o seu agent lead, que coordena os seus agentes e os respetivos subagentes.

Perguntas frequentes

É preciso um worktree para cada agente Claude Code?

Assim que dois agentes tocam no mesmo repositório ao mesmo tempo, sim: um worktree e um branch por agente eliminam o risco de conflito de ficheiros na raiz, em vez de o gerir a posteriori.

Quantos agentes se podem lançar em paralelo?

Tantos quantas as tarefas realmente independentes. O limite concreto não é o número de sessões que se pode abrir, mas sim a capacidade de revisão e o orçamento disponíveis para as verificar.

O que fazer se dois agentes tiverem de tocar no mesmo ficheiro?

Encadeá-los em vez de os paralelizar nesse ficheiro em concreto, ou dividir a tarefa para que cada agente receba um âmbito de ficheiros distinto antes de começar.

Um subagente substitui um worktree separado?

Não: um subagente permanece na mesma sessão e no mesmo contexto, para uma tarefa secundária curta. Um worktree separado serve para trabalho longo e independente, no seu próprio branch.

Como evitar que a revisão se torne o estrangulamento?

Limitando o número de sessões simultâneas àquilo que um revisor consegue verificar seriamente, e escrevendo os critérios de aceitação antes do lançamento, em vez de depois da entrega.

Como é que a Atipol impede dois agentes de reservar o mesmo âmbito?

Cada ticket reserva um âmbito de ficheiros antes de o agente começar a escrever, e dois tickets em curso não podem reservar o mesmo âmbito: o conflito é afastado antes do primeiro commit.

Fontes

Para ligar este método a um enquadramento completo de governação, consulte o nosso guia de governação dos agentes de IA.

Para o que estes agentes em paralelo custam na prática, consulte o nosso artigo sobre o custo dos agentes de IA.

Experimente num projeto real

A demo pública mostra uma organização fictícia em funcionamento, sem conta. O plano gratuito inclui um projeto, três agentes e um agent lead.