Design de Sub-Agentes no Claude Code

Problema: Tarefas de código grandes precisam de mais do que um tipo de especialista, mas uma sessão única do Claude começa a perder qualidade quando você pede que seja todos ao mesmo tempo.

Solução rápida: Cole este prompt em qualquer revisão que precise de mais do que uma perspetiva:

Create sub-agents and analyze this from these perspectives:
- Senior engineer: Review architecture decisions
- Security expert: Identify vulnerabilities
- Performance reviewer: Find optimization opportunities

Vai ter três leituras especializadas em paralelo, de volta em poucos minutos.

Porquê um Único Contexto Falha

Peça ao Claude para rever código, afinar desempenho e verificar segurança ao mesmo tempo e as respostas ficam genéricas. Cada perspetiva luta por espaço na mesma janela de contexto. Tudo fica superficial.

Os sub-agentes resolvem isto dando a cada perspetiva o seu próprio contexto. Cada agente mantém-se na sua faixa, escolhe as suas próprias ferramentas e trabalha com o seu próprio método. Você junta os resultados no final.

O Claude Code dá-lhe duas formas de os executar:

1. Ferramenta Task: A ferramenta integrada cria sub-agentes isolados, cada um com a sua própria janela de contexto.
2. Prompting por Perspetivas: Um único prompt que pede vários pontos de vista especializados numa só passagem.

Task cria trabalho verdadeiramente paralelo. Prompts por perspetivas fingem isso dentro de uma sessão. De qualquer forma, a qualidade da análise sobe.

1. Encontre as Tarefas Paralelizáveis

Bons candidatos para dividir em sub-agentes:

• Revisão de código de vários ângulos
• Investigação em tecnologias diferentes
• Revisão de documentação para audiências diferentes
• Análise de desempenho em métricas diferentes

Ignore sub-agentes quando o trabalho é serial:

• Edições de ficheiros que dependem umas das outras
• Etapas de build sequenciais
• Migrações de base de dados

2. Desenhe os Papéis Especializados

Escolha as perspetivas que correspondem ao seu domínio. Alguns templates de prompt que valem o esforço:

Revisão de Qualidade de Código:

Analyze this codebase using sub-agents with these specialist roles:
- Factual reviewer: Check technical accuracy against documentation
- Senior engineer: Review architecture decisions and patterns
- Security expert: Identify vulnerabilities and attack vectors
- Consistency reviewer: Check coding standards compliance
- Redundancy checker: Find duplicate logic to consolidate

Análise de Experiência do Utilizador:

Create sub-agents for UX review of this feature:
- Creative thinker: Suggest innovative interaction solutions
- Beginner user: Test ease of use and onboarding friction
- Designer: Evaluate visual hierarchy and spacing
- Marketing analyst: Assess conversion potential
- Accessibility auditor: Check WCAG compliance

3. Orquestre a Análise

Cada sub-agente escolhe as suas próprias ferramentas. Agentes de segurança usam scanners de vulnerabilidades. Revisores de desempenho usam ferramentas de profiling. Arquitetos olham para a estrutura. Um único agente não consegue cobrir as três da mesma forma.

Modo de Planeamento para Leituras Seguras

Antes de soltar sub-agentes especialistas em código crítico, entre no modo de planeamento. Pressione Shift+Tab duas vezes dentro do Claude Code. Isso mantém a execução só de leitura enquanto trabalham.

Depois peça a revisão multi-ângulo:

Use sub-agents to validate this API design from:
- Backend perspective: Data flow and scalability
- Frontend perspective: Consumption patterns and DX
- Security perspective: Authentication and authorization gaps

O modo de planeamento é útil quando um sub-agente pode tentar corrigir coisas por conta própria.

O Padrão de Consolidação

Quando os sub-agentes terminarem, junte os outputs:

1. Relatórios Individuais: Cada agente escreve os seus próprios resultados.
2. Resolução de Conflitos: Escolha um vencedor quando duas recomendações discordam.
3. Classificação por Prioridade: Ordene as correções por impacto.
4. Plano de Ação: Defina os passos para implementar.

Erros Comuns

Erro: Criar sub-agentes para tarefas minúsculas.

Erros de digitação, patches de uma linha, renomear rapidamente. O overhead de coordenação elimina o ganho. Salte os agentes.

Melhor: Guarde a equipa de especialistas para problemas complexos e com múltiplas facetas:

Use sub-agents to redesign this authentication system:
- Security expert: Audit current vulnerabilities
- UX designer: Simplify the login flow
- Performance engineer: Optimize token handling

Erro: Empilhar papéis que se sobrepõem muito.

"Especialista em segurança, pentester, scanner de vulnerabilidades, arquiteto de segurança" é a mesma perspetiva com quatro chapéus diferentes.

Melhor: Escolha papéis que cobrem lados diferentes do problema e não se pisam uns aos outros.

Execução em Segundo Plano

Qualquer sub-agente pode correr em segundo plano agora. Pressione Ctrl+B enquanto está a trabalhar:

You: Audit our authentication module for security issues
Claude: I'll spawn a sub-agent to analyze the auth module...
[Sub-agent starts]
You: [Press Ctrl+B]
You: While that runs, let's optimize the database queries...

Acompanhe a execução em segundo plano com /tasks. Quando terminar, acorda o agente principal e entrega os resultados.

Especialistas bloqueantes tornam-se paralelos. A cobertura async completa está no guia de Agentes em Segundo Plano.

Vantagem de Custo

Sub-agentes esticam o Claude Sonnet sem pagar por Opus. Análise paralela chega perto do output de nível Opus a preços de Sonnet.

De onde vêm as poupanças:

• Várias perspetivas especializadas numa sessão
• Trabalho paralelo reduz o tempo total de execução
• Contexto especializado evita a leitura superficial generalista
• Output melhor do que um único modelo premium
• Execução em segundo plano elimina a espera

Rotação de Papéis

Em projetos mais longos, rotacione o conjunto de especialistas por componentes.

Semana 1 - Arquitetura Principal:

Analyze the database design using sub-agents:
- Data architect: Schema optimization and normalization
- Security expert: Access control and encryption
- Performance optimizer: Query patterns and indexing

Semana 2 - Camada API:

Review API endpoints with these specialist sub-agents:
- Backend engineer: Implementation quality and patterns
- Documentation writer: API clarity and examples
- Integration specialist: Third-party compatibility

Refinamento Iterativo

Sub-agentes são naturais para passes progressivas:

1. Perspetivas amplas na primeira olhada
2. Deep dive especializado na segunda
3. Revisão centrada no utilizador na terceira

O resultado é mais completo, mais centrado no utilizador e apanha coisas que um agente sozinho perde.

Onde os Sub-Agentes Compensam

• Revisões de Arquitetura: Várias lentes técnicas ao mesmo tempo
• Auditorias de Documentação: Audiências diferentes leem coisas diferentes
• Gates de Qualidade de Código: Muitas dimensões de qualidade numa passagem
• Estratégia de Produto: Leitura multi-funcional
• Análise Competitiva: Ângulos de mercado diferentes

Comece com revisões de código. Expanda para trabalho estratégico assim que sentir a "comichão pelo paralelismo."

Próximos Passos

• Padrões de execução: Quando ir paralelo, sequencial ou em segundo plano.
• Fundação: Os Fundamentos de Agentes cobre o básico.
• Implementação: Agentes Personalizados para cenários especializados.
• Coordenação: Distribuição de Tarefas para grandes projetos multi-agente.
• Otimização: Modos de Planeamento para execuções seguras de sub-agentes.
• Gestão de Contexto: Manter qualidade alta em toda a equipa.

Experimente na sua próxima revisão de código. A divisão por especialistas é o tipo de coisa que você nota da primeira vez.