Testei Multi-Agentes no Claude Code: 2 Horas Virou 25 Minutos

TL;DR

Testei subagentes nativos do Claude Code via Task tool em dois cenários de desenvolvimento
Refatoração de 6 módulos: 2 horas → 25 minutos | Feature OAuth: 40 min → 19 min
A checklist das 3 perguntas para saber quando paralelizar (e quando não paralelizar)
Prompt completo do orquestrador copiável + template de CLAUDE.md para multi-agentes
Análise de custo de tokens com subagentes - o número que ninguém mostra

🎥 Tutorial em Vídeo

Demo completa com Feature OAuth e refatoração de 6 módulos - incluindo o momento onde o orquestrador entrega o relatório de integração.

O Problema Que Eu Tinha

Durante meses, meu workflow com Claude Code era completamente sequencial.

Mandava uma tarefa. Esperava terminar. Mandava a próxima. Esperava de novo.

Para tarefas pequenas, tudo bem. O problema apareceu quando comecei a trabalhar em features maiores, aquelas que naturalmente se dividem em partes: backend, frontend, testes. Eu sabia que essas partes eram independentes entre si. Sabia que o componente de autenticação no frontend não precisava que o endpoint de backend estivesse pronto para ser construído. Sabia que os testes unitários podiam ser escritos com mocks enquanto o backend ainda estava sendo implementado.

Mas eu continuava fazendo tudo em fila. Um de cada vez.

A justificativa que eu me dava era controle. Se um subagente fizesse algo errado, eu queria ver antes de passar para o próximo. Fazia sentido na teoria.

Na prática, estava desperdiçando tempo esperando trabalho que podia estar acontecendo em paralelo.

O momento que quebrou esse padrão foi uma refatoração de logging em 6 módulos do mesmo projeto. Módulos completamente independentes, cada um com seus próprios arquivos, sem dependência cruzada. Eu sabia exatamente o que precisava mudar em cada um. O contrato era claro.

Fiz sequencialmente. Demorou quase 2 horas.

Na semana seguinte, enfrentei uma tarefa parecida. Decidi tentar diferente.

A Descoberta

A Task tool do Claude Code permite que o orquestrador dispare múltiplos subagentes simultaneamente - cada um com contexto isolado, sem ver o trabalho dos outros.

Não é uma extensão. Não exige tmux. Não precisa de ferramentas externas. Está disponível nativamente.

O resultado da segunda refatoração: 25 minutos.

A mesma categoria de trabalho que levou 2 horas foi para 25 minutos - uma redução de 79%. E o output foi melhor. Não só mais rápido.

Isso me forçou a entender por quê.

Um agente carregando o contexto de 6 módulos ao mesmo tempo fica sobrecarregado. Ele tenta manter coerência entre partes que não precisam ser coerentes entre si naquele momento. Comete erros de escopo. Confunde convenções de um módulo com outro.

Cada subagente com contexto focado, apenas o módulo que precisa refatorar, apenas as convenções daquele arquivo, entrega resultado mais preciso. A limitação de contexto que parece uma fraqueza é, na prática, um guardrail.

A feature OAuth foi o segundo teste. Três subagentes simultâneos: um para o backend, um para o frontend, um para os testes unitários.

40 minutos sequencial → 19 minutos paralelo.

Mas o ganho de tempo, aprendi, é o efeito colateral. O ganho real é a clareza que você ganha ao precisar definir o contrato antes de implementar qualquer coisa.

Tutorial Passo-a-Passo

Passo 1 : Defina o contrato antes de tudo

Multi-agentes só funcionam quando as tarefas são genuinamente independentes. E independência exige que o contrato entre as partes esteja definido antes de qualquer implementação começar.

Para a feature OAuth, isso significou criar o arquivo /docs/api/auth.md antes de disparar qualquer subagente. O contrato especificava:

Endpoint: POST /auth/oauth
Request body: { provider: string, token: string }
Response de sucesso: { userId: string, sessionToken: string }
Response de erro: { error: string, code: number }

Com o contrato documentado, o frontend podia construir o componente usando mock. Os testes podiam ser escritos contra a interface esperada. O backend podia implementar o endpoint real. Nenhum precisava do outro para começar.

Resultado esperado: um documento de contrato que qualquer dos três subagentes consegue ler e trabalhar : sem precisar ver o código dos outros.

Passo 2 : Monte o CLAUDE.md com escopo por subagente

Com vários agentes trabalhando em paralelo, o risco de um sair do escopo é real. O CLAUDE.md é o guardrail.

Para cada projeto com multi-agentes, adiciono uma seção de territórios:

# Territórios por Subagente

## Backend
- Pode modificar: src/api/, src/middleware/
- Não pode tocar: src/components/, tests/

## Frontend
- Pode modificar: src/components/auth/
- Não pode tocar: src/api/, src/middleware/, tests/

## Testes
- Pode modificar: tests/components/auth/
- Não pode tocar: src/api/, src/components/

## Convenções
- TypeScript strict mode em todos os arquivos
- Imports absolutos a partir de src/
- Sem console.log em produção

Esse arquivo é lido por cada subagente no início da sessão. Ele sabe seu quadrante e as regras que valem para todos.

Resultado esperado: nenhum subagente modifica arquivos fora do seu escopo.

Passo 3 : Monte o prompt do orquestrador

O orquestrador não implementa. Ele planeja, delega e consolida.

# Prompt Orquestrador : Feature OAuth

Você é o orquestrador desta feature. Sua função é planejar,
delegar e consolidar : não implementar diretamente.

## Tarefas paralelas : use a Task tool para criar 3 subagentes simultaneamente:

### Subagente 1 : Backend
- Escopo: apenas src/api/auth.ts e src/middleware/oauth.ts
- Tarefa: Implemente o endpoint POST /auth/oauth seguindo o contrato em /docs/api/auth.md
- Restrição: não modifique nenhum outro arquivo

### Subagente 2 : Frontend
- Escopo: apenas src/components/auth/
- Tarefa: Implemente o componente OAuthButton que chama POST /auth/oauth
- Restrição: use mock para o endpoint : não dependa da implementação real

### Subagente 3 : Testes
- Escopo: apenas tests/components/auth/
- Tarefa: Testes unitários para OAuthButton com mocks do endpoint
- Restrição: não crie testes de integração : apenas unitários com mock

## Após os 3 subagentes terminarem:
NÃO tente integrar automaticamente : gere relatório consolidado.
O relatório deve incluir: o que cada subagente implementou, decisões tomadas,
pontos que precisam de revisão humana antes da integração.

A última instrução é crítica. Deixar o orquestrador integrar automaticamente é onde a maioria dos problemas aparece. A integração é sua responsabilidade.

Resultado esperado: três implementações independentes e um relatório consolidado pronto para revisão.

Passo 4 : Revise o relatório antes de integrar

O orquestrador vai entregar algo como:

Subagente 1 (Backend): Implementou POST /auth/oauth em src/api/auth.ts.
Criou middleware de validação em src/middleware/oauth.ts.
Decisão: adicionou rate limiting não especificado no contrato : revisar se desejado.

Subagente 2 (Frontend): Implementou OAuthButton em src/components/auth/OAuthButton.tsx.
Usando mock em development mode, pronto para trocar pela URL real.
Decisão: adicionou loading state : alinhado com design system existente.

Subagente 3 (Testes): 12 testes unitários em tests/components/auth/.
Cobertura: 94% do componente OAuthButton.
Ponto de atenção: mock do endpoint não cobre o caso de timeout : considere adicionar.

Pontos para revisão humana antes da integração:
1. Rate limiting no backend : manter ou remover?
2. Caso de timeout nos testes : adicionar antes de fazer merge?

Você lê, decide, ajusta onde necessário, e então faz a integração manual.

Resultado esperado: controle total sobre o que entra no codebase, com visibilidade das decisões que cada subagente tomou.

Passo 5 : A checklist antes de qualquer orquestrador

Antes de montar qualquer time de agentes, responda:

Consigo definir o contrato entre as partes antes de implementar qualquer uma?
Se não → defina primeiro. Multi-agentes sem contrato é caos organizado.
Cada subagente consegue trabalhar só com esse contrato, sem ver o código dos outros?
Se não → a tarefa tem dependência oculta. Sequencial.
Os arquivos que cada subagente vai tocar não se sobrepõem?
Se sobrepõem → conflito garantido. Redivida o escopo ou sequencial.

Se as três respostas forem sim: paralelize com confiança.

Caso de Uso

A situação foi uma sprint onde precisávamos adicionar suporte a múltiplos provedores OAuth (Google, GitHub, Microsoft) num produto B2B.

Cada provedor tinha suas próprias peculiaridades de implementação, mas o contrato da API era idêntico para os três. O frontend sempre chamaria POST /auth/oauth com { provider: string, token: string } : independente de qual provedor.

Montei um orquestrador com 5 subagentes simultâneos:

Subagente 1: implementação OAuth Google
Subagente 2: implementação OAuth GitHub
Subagente 3: implementação OAuth Microsoft
Subagente 4: componente de seleção de provedor no frontend
Subagente 5: testes unitários para o componente de seleção

Estimativa sequencial: 3 horas e meia.
Resultado paralelo: 47 minutos.

O relatório do orquestrador apontou uma inconsistência no tratamento de erros entre Google e GitHub que eu teria encontrado só na revisão de código. Com o relatório consolidado, resolvi antes de integrar.

O ganho não foi só tempo. Foi a clareza do relatório me dando uma visão que o trabalho sequencial não daria tão limpo.

Próximos Passos

Hoje: Identifique uma tarefa que você faria sequencialmente esta semana e verifique se ela passa na checklist das 3 perguntas. Mesmo que não vá executar agora, o exercício de pensar em termos de contratos e escopos isolados já muda como você planeja.
Amanhã: Monte o CLAUDE.md do seu projeto atual com uma seção de territórios : mesmo que você ainda não vá usar multi-agentes. Definir fronteiras explicitamente ajuda até no modo sequencial.
Esta semana: Escolha uma tarefa pequena com 2-3 partes claramente independentes e teste o modelo orquestrador pela primeira vez. Comece pequeno para entender como o relatório final funciona antes de escalar.
Próxima semana: Aplique em uma feature real de médio porte. Meça o tempo sequencial estimado versus o tempo real paralelo. Anote onde o modelo funcionou e onde você precisou ajustar o contrato.

Grande Abraço, Adriano Viana