Claude Code: SubAgents

Última atualização: 2026-08-31

Sub-agents transformam o Claude Code em um "gerente de equipe" — o agente principal decompõe tarefas, sub-agentes executam em paralelo, a eficiência se multiplica.

💡 Dica: Sub-agents não são múltiplas instâncias do Claude Code, mas um mecanismo de execução paralela dentro de uma única sessão. O agente principal planeja e coordena; sub-agentes executam.

📋 Pré-requisitos: Capítulo 12 - MCP

1. O Que Você Vai Aprender

Como os sub-agentes funcionam
Quando usar sub-agentes
Execução paralela de tarefas
Padrões de colaboração entre agentes
Escalonamento e gerenciamento de recursos

2. Princípios de Funcionamento dos Sub-Agentes

(1) Modelo de Arquitetura

graph TB
    M[Agente Principal<br/>Planejar+Coordenar] --> S1[Sub-agent 1<br/>Refatoração frontend]
    M --> S2[Sub-agent 2<br/>API Backend]
    M --> S3[Sub-agent 3<br/>Escrita de testes]
    S1 --> R[Agregação de Resultados]
    S2 --> R
    S3 --> R

(2) Fluxo de Execução

TEXT 📖 Somente leitura

1. Usuário dá tarefa complexa
2. Agente principal decompõe em sub-tarefas independentes
3. Cria sub-agent para cada sub-tarefa
4. Sub-agentes executam em paralelo (contextos independentes)
5. Agente principal agrega todos os resultados dos sub-agentes
6. Verifica consistência, trata conflitos
7. Gera resultado final

▶ Exemplo 1: Auto-Gatilho de Sub-Agent

TEXT 📖 Somente leitura

> Add complete user management module: data model, API, frontend, tests

Claude Code (Agente Principal):
  Decomposição de tarefas:
  - Sub-tarefa 1: Criar modelo de dados (User model + migration)
  - Sub-tarefa 2: Criar endpoints de API (CRUD)
  - Sub-tarefa 3: Criar páginas frontend
  - Sub-tarefa 4: Escrever testes

  [4 sub-agentes lançados em paralelo]

  Sub-agent 1: ✅ Modelo de dados criado
  Sub-agent 2: ✅ Endpoints de API criados
  Sub-agent 3: ✅ Páginas frontend criadas
  Sub-agent 4: ✅ Testes escritos

  Agente Principal: Agregando, verificando consistência...
  → Found API format mismatch with frontend expectations
  → Auto-correcting frontend API calls
  → Running full tests
  ✅ All 24 tests passed

3. Quando Usar Sub-Agentes

Cenário	Adequado?	Motivo
Modificações independentes em múltiplos arquivos	✅ Sim	Arquivos não se afetam
Desenvolvimento paralelo frontend+backend	✅ Sim	Stacks tecnológicas independentes
Escrita de testes em lote	✅ Sim	Cada arquivo de teste independente
Refatoração profunda de arquivo único	❌ Não	Sem necessidade de paralelismo
Tarefas sequenciais dependentes	❌ Não	Não pode paralelizar
Pequenas modificações	❌ Não	Overhead > benefício

4. Execução Paralela de Tarefas

▶ Exemplo 2: Correção Paralela de Bugs

TEXT 📖 Somente leitura

> Fix these bugs in parallel:
> 1. src/auth/jwt.ts: token refresh logic error
> 2. src/utils/date.ts: timezone handling issue
> 3. src/api/orders.ts: missing pagination validation
> 4. src/services/payment.ts: amount precision issue

Claude Code launches 4 sub-agents:
  Sub-agent 1 [jwt.ts]     → ✅ Fixed (2min)
  Sub-agent 2 [date.ts]    → ✅ Fixed (3min)
  Sub-agent 3 [orders.ts]  → ✅ Fixed (1min)
  Sub-agent 4 [payment.ts] → ✅ Fixed (4min)

  Total: 4min (serial would need 10min)
  Savings: 60%

5. Colaboração Entre Agentes

Modo	Descrição	Caso de Uso
Totalmente independente	Sem interação entre sub-agentes	Lote de tarefas independentes
Convenções compartilhadas	Compartilham CLAUDE.md e estilo de código	Padrões consistentes de equipe
Integração de resultados	Agente principal integra resultados dos sub-agentes	Verificação de consistência necessária
Colaboração iterativa	Saída de um sub-agent alimenta outro	Dependências existem

6. Considerações de Recursos

Dimensão	Agente Único	4 Sub-Agentes
Chamadas de API	Serial	Paralela
Consumo de Tokens	100K	4 × 30K = 120K
Tempo	10 min	3 min
Custo	$2.00	$2.40

❓ Perguntas Frequentes

P: Sub-agentes são acionados automaticamente? R: Sim. O Claude Code detecta automaticamente quando tarefas podem ser paralelizadas. Você também pode solicitar paralelismo explicitamente.

P: Existe limite de sub-agentes? R: Sem limite rígido, mas cada um consome contexto independente e chamadas de API. Recomenda-se máximo 5-6 paralelos para evitar consumo excessivo de recursos.

P: Sub-agentes podem se comunicar? R: Não diretamente. Coordenam-se através do agente principal — que atribui tarefas, agrega resultados, trata conflitos.

P: Execuções paralelas causam conflitos? R: Possivelmente ao modificar o mesmo arquivo. O agente principal detecta e resolve conflitos; recomenda-se que tarefas paralelas trabalhem em arquivos diferentes.

P: Sub-agentes são mais caros? R: Levemente (~10-20% mais Tokens), mas a economia de tempo é substancial (50-70%). Recomendado para cenários sensíveis ao tempo.

📖 Resumo

Sub-agentes são o mecanismo de execução paralela interno do Claude Code
Agente principal decompõe, sub-agentes executam em paralelo, agente principal agrega
Ideais para modificações independentes em múltiplos arquivos, operações em lote, desenvolvimento paralelo frontend+backend
Não adequados para tarefas sequenciais ou modificações simples
Paralelo economiza tempo mas aumenta levemente o custo; atente para conflitos

📝 Exercícios

Básico (⭐): Dê ao Claude Code uma tarefa paralelizável, observe o auto-gatilho de sub-agentes.
Intermediário (⭐⭐): Desenhe um cenário com 4 módulos independentes, compare tempo serial vs paralelo.
Avançado (⭐⭐⭐): Analise consumo de Tokens e custo dos sub-agentes, determine quando paralelo vale a pena.

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós