No final de novembro do ano passado eu estava três semanas dentro de um build WooCommerce para um cliente de atacado. Cerca de trinta tipos de post personalizados, um motor de precificação sob medida e um fluxo de checkout com mais lógica condicional do que gostaria de lembrar. Eu era o único desenvolvedor nele. E estava perdendo dias apenas alternando contexto entre a camada de plugin, os overrides de tema e os endpoints da REST API.
Foi aí que me comprometi adequadamente com a execução de subagentes Claude Code em paralelo. Não apenas experimentando. Reestruturando de verdade como divido o trabalho para que múltiplos agentes possam avançar simultaneamente sem se atrapalharem.
Aqui está o que aprendi, incluindo onde cometi erros inicialmente.
---
O que "Subagentes" realmente significa no Claude Code
As pessoas usam a palavra livremente. No framework agentico do Claude, um subagente é simplesmente uma instância do Claude que recebe uma tarefa com escopo definido de um orquestrador, executa e retorna o resultado. O orquestrador (que pode ser ele mesmo uma sessão do Claude) decide como dividir o trabalho, quais subagentes iniciar e como combinar os resultados.
Na prática, para a maioria de nós que construímos sites e aplicações, isso significa executar múltiplas sessões de terminal, cada uma com um contexto Claude Code focado, contra o mesmo repositório. Às vezes a orquestração é automatizada através de um script. Muitas vezes, para ser honesto, é apenas eu coordenando manualmente o que cada agente está trabalhando em um documento de planejamento no Notion.
A diferença entre trabalho sequencial e paralelo
Trabalho agentico sequencial é o que a maioria dos desenvolvedores faz por padrão: peça ao Claude para fazer a tarefa A, espere, depois peça para fazer a tarefa B. Funciona para coisas simples. Mas se A e B não dependem da saída um do outro, você está desperdiçando tempo.
Subagentes paralelos executam simultaneamente em fluxos de trabalho independentes. No projeto WooCommerce que mencionei: eu tinha um agente refatorando a lógica do motor de precificação enquanto outro estava gerando comentários PHPDoc nos controladores da REST API. Sem sobreposição. Ambos prontos no tempo que levaria para fazer um.
---
Como estruturo realmente a divisão de trabalho
Essa é a parte que ninguém explica com clareza suficiente. A configuração do agente é fácil. A parte difícil é descobrir o que dividir.
Uso uma regra simples que surgiu após um incidente doloroso de merge conflict em 2022: nenhum dos dois agentes deve tocar no mesmo arquivo durante a mesma sessão. Ponto final. Se não posso garantir isso, as tarefas não executam em paralelo.
Meu passo de planejamento antes de qualquer execução paralela
Antes de iniciar qualquer coisa, escrevo um breve manifesto de tarefas. Nada sofisticado, apenas um arquivo de texto simples ou uma página no Notion com:
- Nome da tarefa e uma descrição de uma frase
- Arquivos no escopo (lista explícita)
- Arquivos fora do escopo (qualquer coisa adjacente que possa tentar um agente a se desviar)
- Formato de saída esperado
- Qualquer contexto que o agente necessite que não está na base de código
Isso me leva talvez 15 minutos. Tem me salvo de um número genuinamente envergonhado de conflitos.
---
Os Três Tipos de Workstream Que Divido com Mais Frequência
Com mais de 12.000+ construções de site na Seahawk, e meu próprio trabalho com clientes solo paralelo, notei as mesmas categorias aparecendo repetidamente como boas candidatas para paralelização.
1. Geração de documentação e código
Um agente escreve ou refatora código. Outro escreve documentação, testes ou comentários para um módulo diferente. Esses quase nunca entram em conflito e ambos são genuinamente tedioso fazer manualmente. No projeto WooCommerce wholesale, tive um subagentem gerando stubs de teste PHPUnit para as funções de precificação enquanto outro estava construindo as colunas de admin customizadas. Os stubs de teste levaram cerca de quatro minutos. As colunas de admin levaram doze. Não perdi nenhum daqueles quatro minutos esperando.
2. Isolamento de frontend e backend
Se seu frontend e backend vivem em diretórios claramente separados (o que deveria acontecer, mas isso é outro post), essa é uma divisão natural. Rodei um subagentem construindo componentes React em /resources/js enquanto outro estava conectando controladores Laravel em /app/Http . O único ponto de coordenação foi concordar com o contrato da API antes de qualquer agente começar. Eu escrevi isso em um arquivo AGENTS.md na raiz do projeto. Ambos os agentes o referenciaram.
3. Refatoração módulo por módulo
Grandes refatores são miseráveis quando feitos sequencialmente. Se você tem, digamos, oito módulos de feature que cada um precisa do mesmo tipo de mudança (atualizando um método deprecado, migrando para um novo helper, o que for), divida entre agentes. Uma vez rodei quatro agentes simultâneos migrando um plugin legado de loops WP_Query para um padrão de repositório. Cada agente recebeu dois módulos. Pronto em menos de uma hora. Sequencialmente isso seria meio período.
---
Configuração de Ferramentas: O Que Eu Realmente Uso
Não vou fingir que tenho uma infraestrutura elaborada. Minha configuração real é:
- Claude Code rodando em múltiplos painéis
tmuxem um único MacBook Pro M3 - Um arquivo
AGENTS.mdcompartilhado na raiz do projeto que define convenções, propriedade de arquivos e o contrato da API entre workstreams - Branches Git por agente. Sempre. Mesmo se o branch apenas viver por vinte minutos
- Um rápido
git diff --statantes de qualquer merge para pegar surpresas
O arquivo AGENTS.md provavelmente é a coisa mais útil que adicionei ao meu workflow no ano passado. É um arquivo markdown comum que diz a qualquer agente (ou humano, aliás) quais são as convenções do projeto, quais arquivos pertencem a qual workstream e o que evitar tocar. Pense nisso como um CONTRIBUTING.md mas escrito para janelas de contexto de IA.
Sobre gestão de janela de contexto
Aqui é onde as pessoas ficam preguiçosas e depois confusas. Cada subagentem tem seu próprio contexto. Isso significa que se o Agente B precisa saber o que o Agente A decidiu, você tem que dizer explicitamente. Ele não saberá automaticamente.
Lido com isso mantendo um SESSION_LOG.md que atualizo manualmente após cada agente completar um chunk. São três a cinco pontos no máximo: o que foi feito, o que mudou, o que o próximo agente precisa saber. Overhead é baixo. A alternativa é um agente fazer suposições que quebram seu código, e esse overhead é muito mais alto.
---
Onde Dá Errado (Da Experiência Dolorosa)
Seahawk tinha um projeto de dashboard fintech na primavera passada onde tentamos rodar subagentem em um monorepo sem propriedade de arquivo adequadamente definida. Dois agentes ambos decidiram atualizar o arquivo compartilhado utils/formatters.ts . Nenhum sabia do outro. O merge resultante foi tecnicamente ok, mas gastamos 40 minutos reconciliando intenção. Completamente evitável.
Os modos de falha que vejo repetidamente:
- Arquivos de utilidade compartilhados. Esses são uma armadilha. Tranque-os. Se um subagentem precisa atualizar uma utilidade compartilhada, essa tarefa deve rodar sozinha, não em paralelo.
- Descrições de tarefas vagas. Um agente recebendo "limpar o módulo de auth" vai interpretar isso de forma muito diferente dependendo do que está no seu contexto. Seja específico. "Refatore
AuthController.phppara usar a interfaceUserRepositoryjá definida emapp/Repositories/UserRepository.php. Não modifique a interface em si." Esse é um prompt seguro. - Sem isolamento de branch. Rodar todos os agentes em
mainé como você cria tardes de sexta-feira emocionantes. Branches não custam nada. - Pulando o manifesto. Eu sei, eu sei. Parece overhead. Faça mesmo assim. Toda vez que pulei, me arrependi dentro de uma hora.
---
Uma Execução Paralela Real, Passo a Passo
Aqui está mais ou menos como ficou a sessão de terça-feira passada para um projeto de migração Shopify-para-WooCommerce (anonimizado, mas a estrutura é exata).
- Escrevi o manifesto de tarefas no Notion. Quatro tarefas identificadas como paralelizáveis.
- Criei quatro branches git: agent/product-import, agent/tax-logic, agent/rest-endpoints,
agent/admin-ui. - Abri quatro panes
tmux, uma sessão Claude Code em cada uma. - Colei a seção relevante de
AGENTS.mdno início de cada sessão como contexto. - Dei a cada agente seu prompt de tarefa, referenciando arquivos específicos.
- Rodei os quatro simultaneamente. Fiz um café. Na verdade bebi enquanto ainda estava quente, o que pareceu um milagre.
- Revisei o output de cada branch. Rodei
phpcsno PHP,eslintem qualquer JS tocado. - Mergeei em sequência: importação de produto primeiro (os outros tinham dependências leves do seu schema), depois tax logic, depois os REST endpoints, depois admin UI.
- Atualizei
SESSION_LOG.mdcom o que mudou.
Tempo total para as quatro tarefas combinadas: cerca de 35 minutos. Minha estimativa para conclusão sequencial era 90 minutos a 2 horas. Vou com isso.
---
O Que Isso Faz (e Não Faz) Substituir
Subagentes paralelos não são um substituto para pensar. Esse passo de planejamento de 15 minutos é genuinamente você fazendo o trabalho de arquitetura. Os agentes executam. Você ainda precisa saber o que construir, como as peças se encaixam, e se o output é realmente correto.
Reviso todo o output de cada agente antes de tocar em main. Toda vez. Já peguei um subagente escrever confiantemente uma camada de caching que teria causado problemas de dados obsoletos em um setup multisite. O código parecia correto. Era logicamente errado para o contexto específico. Só peguei porque li.
A própria orientação da Anthropic sobre tarefas agentic sinaliza especificamente a importância de checkpoints humanos antes de ações irreversíveis. Isso não é blá-blá corporativo. É realmente um conselho importante, especialmente quando agentes têm acesso de escrita a bancos de dados ou estão rodando migrations.
A outra coisa que isso não substitui: comunicação com clientes. Um agente pode construir uma feature. Não pode dizer a um cliente por que um deadline mudou ou gerenciar expectativas sobre scope creep. Essa parte ainda é sua.
---
FAQ
Preciso de acesso especial à API ou ferramentas para rodar subagentes Claude Code?
Nenhuma setup exótica necessária. Claude Code é a ferramenta de coding baseada em terminal da Anthropic, e você pode rodar múltiplas instâncias em sessões de terminal separadas (eu uso tmux). Você precisa de uma chave Claude API com rate limits suficientes se estiver batendo a API diretamente. Para workloads paralelos pesados, verifique seu tier de rate limit antes de começar para não sofrer throttling no meio da sessão.
Como faço para parar os agentes de conflitarem em arquivos compartilhados?
Defina a propriedade dos arquivos antes de começar. A convenção AGENTS.md que descrevi funciona bem. Se duas tarefas precisam que um arquivo utilitário compartilhado seja alterado, não paralelizarize essas duas tarefas. Execute a alteração do utilitário compartilhado primeiro, faça commit, depois execute as outras tarefas em paralelo a partir dessa base limpa.
Isso é útil apenas em projetos grandes?
Honestamente, não. Usei em sites de uma única página onde queria que a documentação fosse gerada junto com novo código de funcionalidade. O overhead do planejamento é baixo o suficiente para que até economias modestas de tempo justifiquem. Dito isto, se um projeto tem menos de talvez cinco tarefas paralelizáveis distintas, o tempo de configuração começa a superar o benefício. Use seu julgamento.
O que acontece se um agente produz uma saída ruim?
Você identifica na revisão, descarta o branch e tenta novamente com um prompt mais específico. Esse é o objetivo inteiro do isolamento de branch. Uma saída ruim do agente custa apenas o tempo para revisar e fazer um novo prompt. Não deveria custar um codebase quebrado se você estiver seguindo a regra de um branch por agente.
Posso automatizar a orquestração em vez de fazer manualmente?
Sim, e para workflows repetidos vale a pena. Escrevi scripts simples em Bash que executam chamadas sequenciais do Claude Code com prompts e contexto pré-definidos. Para orquestração paralela totalmente automatizada, você construiria uma camada orquestradora que spawna agentes programaticamente, coleta resultados e trata dependências. Isso é um investimento de engenharia maior. Para a maioria dos freelancers e pequenas agências, coordenação manual com tmux e um manifest de tarefas é suficiente.
---
A verdade honesta é que subagentes paralelos não me tornaram um desenvolvedor dramaticamente melhor. Me tornaram um desenvolvedor mais rápido, na classe específica de tarefas onde o gargalo era execução em vez de pensamento. O pensamento ainda é meu. As decisões de arquitetura, as chamadas do cliente, a revisão de código. Tudo ainda é meu.
Mas as partes entediantes da execução? Vou aproveitar cada minuto que conseguir recuperar.