Trabalho paralelo com Claude Code: worktree, agentes e Workflows

Materiais práticos sobre como trabalhar com agentes em paralelo: documentação Ailoot.

Este guia reúne experiência prática e um mapa de onde as ferramentas se aplicam. Inclui os quatro primitivos oficiais do Claude Code, um mapa das suas aplicações e um enquadramento anti-hype sobre quantos agentes paralelos um vibe coder realmente precisa. Todos os números e citações remetem para fontes primárias da Anthropic.

O que é multi-agent no Claude Code e porque não são «1000 agentes»#

Uma configuração multi-agent é aquela em que uma tarefa é dividida em vários fluxos de trabalho independentes, cada um a tratar da sua parte e a devolver um resultado. O exemplo mais simples: escreve o frontend numa janela do Claude Code e o backend noutra janela, na mesma máquina, com um repositório git partilhado entre ambas. Isso já é multi-agent, apesar de «orquestração» ser uma palavra desnecessária neste caso.

Uma configuração mais complexa: numa sessão do Claude Code, inicia cinco subagentes com funções diferentes (programador de frontend, programador de backend, revisor de segurança, testador, responsável pela documentação) e cada um devolve a sua parte do resultado à conversa partilhada. É a mesma abordagem multi-agent, apenas com um ponto de controlo.

Ainda mais complexa: diz ao Claude «faz uma auditoria de segurança semanal a todos os 500 ficheiros do meu projeto» e ele escreve um script de orquestração JavaScript. O runtime inicia várias dezenas de agentes em segundo plano, cada um audita a sua secção, depois agentes independentes verificam as conclusões uns dos outros e recebes um único relatório. São os Dynamic Workflows, lançados pela Anthropic a 28 de maio de 2026. A análise detalhada das funcionalidades está no guia separado sobre Dynamic Workflows.

A diferença entre estes três cenários não é o número de agentes. A diferença é quem decide o que o agente seguinte faz. No primeiro cenário, és tu. No segundo, é o Claude que decide à medida que a conversa avança. No terceiro, é um script JavaScript escrito pelo Claude.

A propósito, «1000 agentes» é um número real. É o limite máximo de um Dynamic Workflow no Claude Code. A documentação oficial da Anthropic afirma:

Por outras palavras, trata-se de uma salvaguarda técnica contra comportamentos descontrolados, não de uma carga de trabalho recomendada. Na prática, 95% das tarefas são tratadas por 2–8 fluxos de trabalho paralelos. Se estiveres a planear mais, pergunta primeiro a ti próprio o que vão fazer.

4 primitivos do Claude Code: subagentes, skills, agent teams e workflows#

O Claude Code tem quatro primitivos oficiais para dividir uma tarefa entre vários agentes. A Anthropic reuniu-os numa tabela comparativa na documentação dos Dynamic Workflows. Eis a comparação em linguagem simples:

Cada um destes primitivos resolve um problema diferente. Os subagentes servem para delegar 2–3 verificações numa tarefa. As skills servem quando tens instruções prontas que o Claude deve seguir (como «faz uma revisão de PR com esta lista de verificação»). Os agent teams servem quando várias partes de um produto estão em janelas diferentes e precisas de um coordenador. Os workflows servem quando uma tarefa é demasiado grande para uma janela de contexto.

Os subagentes são abordados em detalhe no guia Claude Code Subagents 2026. A árvore de decisão para escolher «o que usar numa determinada tarefa» está no guia Skills, Subagents, MCP, Plugins. Este guia aborda a combinação destes elementos numa configuração multi-agent assente em git worktree.

Nível 1: subagentes numa sessão — a forma mais simples de começar#

Um subagente é a forma mais simples de dividir uma tarefa. A conversa principal funciona como coordenadora. Os subagentes são trabalhadores temporários que o agente principal inicia à medida que o trabalho avança.

Um exemplo concreto do projeto descrito. Depois do primeiro rascunho de um guia, a revisão é feita assim: o Claude recebe o pedido «inicia seis subagentes em paralelo — um verifica indicadores de IA, o segundo o vocabulário jurídico, o terceiro a voz e o tom, o quarto verifica factos com WebFetch, o quinto analisa a estrutura SEO e o sexto verifica a precisão das ligações cruzadas». Cada um devolve um relatório e, depois, aplicam-se as alterações.

Tecnicamente, isto é feito com ficheiros em .claude/agents/[subagent-name].md que descrevem a função e as ferramentas. A chamada é feita através da ferramenta Agent na conversa principal. O Claude decide quando enviar um pedido a um subagente.

Onde funciona. Tarefas que envolvem 3–7 verificações paralelas de um único artefacto (código, texto, design). Cada verificação é independente. Os resultados cabem na janela de contexto principal.

Onde deixa de ser suficiente. Se tiveres mais de 50 ficheiros ou se cada verificação precisar do seu próprio contexto de 50K tokens, a janela principal ficará cheia. Precisarás de workflows ou agent teams.

Principal risco. Cada subagente consome tokens separadamente. Se iniciares seis num projeto com 200 ficheiros e cada um voltar a ler os 200 ficheiros, pagas 6×. Por isso, TENS de especificar exatamente que ficheiros o subagente deve analisar. Consulta o guia Para onde vão os tokens no Claude Code para mais detalhes.

Nível 2: git worktree — isolar ficheiros entre sessões paralelas#

Quando os subagentes não chegam e precisas de duas instâncias completas do Claude Code a trabalhar no mesmo repositório, em terminais diferentes, surge um problema clássico. Começam a editar o mesmo ficheiro; uma guarda primeiro e a segunda substitui as alterações da primeira. Na semana passada, um cliente perguntou à equipa de apoio: «5 estão a substituir-se uns aos outros ao mesmo tempo».

A solução é git worktree. É uma funcionalidade integrada do git que permite ter várias cópias de trabalho do mesmo repositório, cada uma na sua própria branch, partilhando o repositório .git. Uma origem, diretórios diferentes no disco e sem sobreposição entre os ficheiros. O mecanismo está descrito em detalhe no guia Git worktree no Claude Code.

Comandos para uma configuração de cinco minutos:

# A partir do diretório principal do projeto
cd ~/projects/my-app

# Criar um worktree para feature/auth
git worktree add ../my-app-auth feature/auth

# Criar um worktree para feature/billing
git worktree add ../my-app-billing feature/billing

# Abrir duas janelas de terminal
cd ~/projects/my-app-auth && claude   # primeiro Claude Code
cd ~/projects/my-app-billing && claude # segundo Claude Code

Cada cópia está na sua própria branch. Cada instância do Claude Code escreve no seu próprio diretório. Quando a tarefa estiver concluída, executa git push a partir da respetiva branch e, em seguida, git worktree remove ../my-app-auth.

O que precisas de saber. Um worktree não duplica node_modules, .venv nem outros ficheiros em .gitignore. Se precisares de dependências independentes (uma versão diferente de uma biblioteca em cada branch), executa npm install separadamente no novo diretório depois de worktree add.

Quantos worktrees por pessoa. Com base em inquéritos a equipas de 2026, o limite prático é de 4–8 worktrees paralelos por programador. O fator limitador não é o Claude, mas sim a capacidade de uma pessoa rever e aceitar os resultados. Se tiveres 10 worktrees, ficarão à espera de revisão.

Na prática descrita, as pessoas costumam usar 2–3 worktrees paralelos. Um worktree principal para o trabalho ativo, um de reserva para correções urgentes e um para uma experiência (uma nova funcionalidade sobre a qual ainda tens dúvidas). Não são necessários mais.

Nível 3: agent teams — várias janelas, um agente líder#

Os agent teams são um primitivo relativamente recente. A ideia: um agente líder mantém o plano partilhado como uma lista de tarefas e várias sessões equivalentes, em janelas separadas, assumem as tarefas atribuídas pelo líder. Todos trabalham no mesmo sistema de ficheiros e conseguem ver os artefactos intermédios uns dos outros.

Isto é útil quando uma tarefa se divide em 3–5 grandes fluxos de trabalho, cada um com uma duração de horas (migrar um módulo grande, reescrever um subsistema, fazer uma auditoria de segurança completa). Nesse caso, o líder mantém o plano num único ficheiro partilhado com caminho absoluto fora dos worktrees. Os agentes leem esse caminho e comunicam resultados; só o líder atualiza estados para evitar escritas concorrentes.

Tecnicamente, os agent teams são várias janelas a funcionar sobre git worktree com um ponto de planeamento partilhado. Na prática, 80% das pessoas gerem os agent teams manualmente (como descrito acima com worktree) e não usam um «framework de equipas» específico. Não há problema.

Se não tens a certeza de que precisas de um framework, é quase certo que não precisas. Usa worktree manualmente e um agente líder no diretório principal.

Nível 4: Dynamic Workflows — o Claude escreve um script de orquestração JS#

Nos três níveis acima, o plano continua numa conversa: na cabeça do agente principal ou na lista de tarefas do agente líder. Os Dynamic Workflows transferem o plano para o código. O Claude exprime a tarefa como um script JavaScript, o runtime executa-o num ambiente isolado, os resultados intermédios ficam em variáveis do script em vez de ocuparem o contexto e a sessão continua a responder enquanto os agentes trabalham em segundo plano.

Um exemplo concreto da documentação oficial. Dizes:

ultracode: audit every API endpoint under src/routes/ for missing auth checks

O Claude escreve um script JavaScript com aproximadamente esta lógica: «recolher todos os ficheiros de src/routes/, dividi-los em grupos de 30 endpoints, executar um agente em cada grupo com a mesma verificação e, em seguida, executar dois agentes avaliadores independentes sobre as respetivas conclusões e consolidar um relatório final». O script é executado. Recebes uma tabela de resultados e uma lista de endpoints que precisam definitivamente de ser revistos.

Onde funciona.

• Auditar um projeto inteiro à procura de um problema (segurança, tipagem, APIs obsoletas).
• Migrações de grande dimensão (mais de 500 ficheiros abrangidos por uma regra comum).
• Questões de investigação que precisam de ser verificadas de vários ângulos independentes (a Anthropic faz isto no comando integrado /deep-research).

Uma análise detalhada dos Dynamic Workflows, dos seus limites e do funcionamento de ultracode está no guia separado sobre Dynamic Workflows no Claude Code.

Quando NÃO o usar. Quando a tarefa é linear e clara. Não precisas de um workflow para uma tarefa como «termina este componente». Um workflow faz sentido quando uma tarefa se divide em mais de 10 subtarefas independentes e precisas de cruzar as respetivas verificações.

Principal limitação. Um workflow consome significativamente mais tokens do que uma sessão normal. A Anthropic recomenda na sua documentação:

Por outras palavras, executa o primeiro workflow num diretório, não no projeto inteiro. Vê quanto custou e depois decide se vale a pena aumentar a escala.

Outcomes: uma grelha de critérios e um revisor independente#

O mais perigoso no trabalho multi-agent é confiar nos resultados dos agentes. Cada agente devolve texto que parece trabalho concluído. Uma citação parece verdadeira, um relatório parece completo, uma migração parece terminada. Com um agente, podes verificar tudo pessoalmente. Com 10, não consegues — não terás tempo.

A Anthropic aborda este problema com Outcomes, uma funcionalidade de Managed Agents lançada a 6 de maio de 2026. A ideia é simples: a sessão recebe um SEGUNDO agente (um avaliador), cuja única função é verificar o trabalho do primeiro agente segundo uma grelha rigorosa.

Como funciona tecnicamente. Escreves uma grelha — um documento Markdown com uma lista detalhada do que significa «concluído», das fontes a verificar e das etiquetas a usar. A plataforma cria automaticamente um agente avaliador numa janela de contexto nova. Este recebe apenas a grelha e o resultado, nada mais. Após cada tentativa do agente principal (o redator), o avaliador volta a ler o resultado e aprova-o ou devolve uma lista por pontos do que continua incompleto.

Uma citação do Anthropic Cookbook:

Resultados concretos: depois da integração de Outcomes no Claude Managed Agents, a taxa de conclusão de tarefas da empresa de IA Harvey aumentou cerca de 6×. Na Wisedocs (documentação médica), o tempo gasto a rever um documento diminuiu 50%. Estes números são do anúncio oficial da funcionalidade.

O que importa para quem faz vibe coding, e não para uma grande empresa. Outcomes é um padrão, não apenas uma funcionalidade específica. Podes criar o teu próprio agente avaliador descrevendo os mesmos critérios em .claude/agents/grader.md e pedindo ao agente principal que o execute após cada tentativa. Funciona com qualquer configuração multi-agent, não apenas com Managed Agents.

A principal regra para escrever a grelha, retirada do cookbook, é especificar algo verificável, não algo genérico. Não «verifica se o briefing cobre a faturação», mas «abre o briefing, encontra a secção sobre faturação e confirma que especifica um montante em $ ou uma percentagem das receitas». A primeira instrução permite ao avaliador ler por alto e assinalar uma caixa. A segunda obriga-o a abrir o documento e encontrar um número específico.

Antipadrão: «50 agentes a fazer disparates»#

Este é o principal antipadrão multi-agent. Alguém descobre que o Claude Code consegue executar 16 agentes de cada vez e que os Dynamic Workflows podem executar 1000 por execução, senta-se e inicia-os. O efeito: zero. Consumo de tokens: 10× o de uma sessão normal.

Um teste simples. Pega numa folha de papel e desenha uma caixa para cada um dos teus agentes. Em cada caixa, escreve:

1. O que faz exatamente (uma frase).
2. Em que ficheiros mexe.
3. O que devolve.
4. Quem verifica o resultado.

Se não conseguires responder a alguma destas perguntas em 30 segundos, não devias ter esse agente. Esta regra funciona em todos os níveis: subagentes, agent teams e Dynamic Workflows.

O segundo antipadrão é executar em paralelo trabalho que devia ser sequencial. Se o frontend precisar primeiro do backend porque lê o esquema da API, não os executes em paralelo. Faz primeiro o backend e depois o frontend. As tarefas só devem ser paralelas se forem independentes.

O terceiro antipadrão é usar multi-agent para ganhar velocidade. Isto só funciona até certo ponto. Se dividires uma tarefa em quatro fluxos de trabalho independentes, terminarão aproximadamente no tempo que um único fluxo demoraria (mais uma sobrecarga mínima de coordenação). Mas se houver 50 fluxos numa máquina, cada um ficará mais lento porque partilham a CPU. O limite prático num portátil é de 4–6 instâncias simultâneas do Claude Code; a partir daí, começa o estrangulamento do desempenho.

Quanto custa e como evitar esgotar os limites?#

Em maio–junho de 2026, o setor confrontou-se com a realidade de que a programação com IA custava mais do que o esperado.

Uma sessão normal de chat do Claude Code tem um custo relativamente razoável. Ativa os Dynamic Workflows para um repositório inteiro e recebes uma fatura 20× superior. Da documentação oficial da Anthropic:

O que fazer na prática. Regras de poupança da experiência descrita.

1. Especifica com precisão os ficheiros de cada agente. Não «analisa o projeto e encontra problemas», mas «analisa src/auth/*.ts e verifica se cada função valida userId». O segundo pedido dá-te exatamente o trabalho pelo qual estás a pagar.

2. Experimenta sempre um workflow primeiro num diretório. Não em todo o src/. Começa por src/auth/. Se gostares dos resultados e compreenderes o custo, alarga-o depois.

3. Usa /effort high por predefinição e ultracode apenas deliberadamente. /effort ultracode significa xhigh mais orquestração automática. É muito dispendioso. Usa-o quando uma tarefa exigir realmente vários fluxos de trabalho paralelos.

4. Muda os subagentes para um modelo mais pequeno quando possível. Seis subagentes a reverem um guia não precisam de Opus, nem o agente de QA que procura sinais de IA nem o verificador de ligações cruzadas. O Sonnet chega. Isto reduz a utilização em 3–5×.

Uma análise detalhada da poupança de tokens está nos guias Para onde vão os tokens no Claude Code e Como não esgotar os limites do Claude Code.

Por onde começar hoje: uma lista de verificação de 30 minutos#

1. Atualiza o Claude Code para v2.1.154+

   Esta é a versão mínima compatível com Dynamic Workflows. Executa claude update no terminal.

2. Ativa os Dynamic Workflows em /config

   Estão desativados por predefinição no plano Pro. Abre /config, encontra a linha «Dynamic workflows» e ativa-a. Já estão ativados nos planos Max, Team e Enterprise.

3. Cria o teu primeiro worktree

   No diretório principal do projeto, executa git worktree add ../<project>-experiment <branch>. Abre uma segunda janela de terminal nesse diretório. Executa claude.

4. Adiciona uma lista de tarefas partilhada

   Usa um caminho absoluto fora de todos os worktrees. Cada tasks.md dentro de um worktree é independente e não sincroniza automaticamente. A sessão líder é a única a escrever; os agentes leem a lista e comunicam-lhe os resultados.

   Cria uma vez a pasta de coordenação e a lista:

   mkdir -p "$HOME/projects/my-app-coordination"
   printf '%s\n' '# Tasks' '- Auth: assigned to the auth worktree' '- Billing: assigned to the billing worktree' > "$HOME/projects/my-app-coordination/tasks.md"
   

   No primeiro terminal:

   cd "$HOME/projects/my-app-auth"
   printf 'Shared task list: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
   claude
   

   No segundo terminal:

   cd "$HOME/projects/my-app-billing"
   printf 'Shared task list: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
   claude
   

   Nas duas sessões, fornece o mesmo caminho absoluto expandido apresentado acima: «Lê esta lista partilhada. Trabalha só na tarefa e ficheiros atribuídos. Não edites a lista; comunica conclusão e bloqueios ao líder, que atualiza.» Confirma que ambos leem esse ficheiro exato antes de começar; resolve qualquer pedido de permissão desse caminho. A lista coordena estados; as alterações ao código continuam em worktrees separados.

5. Trabalha assim durante uma semana

   Não instales logo um wrapper GUI. Passa uma semana a trabalhar manualmente com dois worktrees. Vais perceber o que falta; depois escolhe uma ferramenta para resolver um problema específico.

6. Só depois ativa `/effort ultracode`

   Escolhe uma tarefa, como «encontra todos os endpoints da API sem verificações de autenticação em src/routes/». Ativa /effort ultracode. Vê que workflow o Claude escreve, quanto custa e que resultado produz. Esse será o teu primeiro Dynamic Workflow.

Próximos passos: memória entre sessões, Code Review e Multi-Agent v2#

O que surgiu em maio–junho de 2026 e para onde se dirige o multi-agent no Claude Code.

Managed Agents com Dreaming. Lançado a 6 de maio de 2026, no Code with Claude. Um processo agendado que lê as transcrições anteriores de um agente entre sessões, identifica padrões recorrentes e atualiza a respetiva memória. A conclusão de tarefas da empresa de IA jurídica Harvey aumentou seis vezes especificamente após o Dreaming. Ainda está em pré-visualização de investigação.

Outcomes como funcionalidade de Managed Agents. Descrito acima. Está disponível através do Claude Agent SDK, não diretamente na CLI do Claude Code. Podes aplicar manualmente o mesmo padrão agora, usando um subagente avaliador.

Multi-Agent Orchestration v2 no Claude Agent SDK. Um agente líder delega ele próprio tarefas a subagentes, utilizando um sistema de ficheiros partilhado. É o passo de «iniciar N subagentes manualmente» para «descrever uma tarefa e deixar o líder decidir por si a quem delegar e como». Se estás a começar a aprender sobre subagentes, não te preocupes ainda com a v2. Aprende o padrão clássico — «um agente principal + 3–5 subagentes com funções» — e passa naturalmente à v2 dentro de 3–6 meses.

Code Review por uma equipa de agentes. A Anthropic anunciou no Code with Claude uma funcionalidade de revisão automática de código quando é aberto um PR. Uma equipa de agentes de IA verifica o diff em paralelo, procura erros, valida conclusões entre si e ordena-as por gravidade. Disponível nos planos Team e Enterprise, ainda não no Pro.

Plugin Marketplace. Lançado a 23 de maio de 2026, na v2.1.128-136. Alguns plugins do marketplace são configurações multi-agent prontas (parallel-review, security-audit, migration-helper). Podes instalá-los com /plugin install <name>@claude-plugins-official e ver como foram montados — é uma boa forma de aprender a escrever os teus próprios.

O multi-agent no Claude Code continua a ser um conjunto de primitivos em diferentes fases de maturidade. Os subagentes e git worktree são estáveis, comprovados e funcionam em todo o lado. Os agent teams são parcialmente automatizados e parcialmente manuais. Os Dynamic Workflows estão em pré-visualização de investigação e mudam rapidamente. Managed Agents v2 só está disponível para empresas. Isso significa que, no próximo ano, a configuração ideal para quem faz vibe coding não será a versão mais recente, mas sim a configuração mínima necessária para a tarefa específica. Dois worktrees e um subagente avaliador chegam para um mês de trabalho ativo. Acrescenta complexidade só quando começares a sentir limitações.

Uma configuração funcional para vibe coding#

Materiais práticos: documentação Ailoot.

Mais materiais e ferramentas: Ailoot.