🧩 Subagentes Paralelos
O Claude Code pode criar subagentes isolados para trabalhar em paralelo em partes diferentes de um problema complexo. Cada subagente tem sua própria janela de contexto limpa e, opcionalmente, seu próprio modelo. No final, todos reportam à sessão principal que consolida os resultados.
🧠 Como Funciona o Paralelismo
A sessão principal age como orquestrador: ela define os subproblemas, cria os subagentes, distribui o trabalho e integra os resultados. Cada subagente não vê o contexto dos outros.
- • Contexto isolado: cada subagente começa com janela limpa — sem contaminação entre tarefas
- • Modelo configurável: subagente de pesquisa pode usar Haiku; subagente de síntese usa Sonnet
- • Reporte estruturado: cada subagente devolve um resumo compacto ao orquestrador
- • Paralelismo real: as tarefas ocorrem simultaneamente, não em fila
- Subagente 1: analise os testes existentes e identifique gaps de cobertura
- Subagente 2: pesquise padrões de segurança JWT mais recentes
- Subagente 3: mapeie todos os pontos de entrada da autenticação no código
Quando terminarem, consolide os achados e proponha o plano de refatoração."
💡 Dica Prática
Especifique explicitamente "use subagentes paralelos" no prompt. O Claude não faz isso automaticamente — você precisa pedir. Quanto mais claro for o escopo de cada subagente, melhores serão os relatórios devolvidos.
✓ O que FAZER
- ✓Definir escopo claro para cada subagente
- ✓Usar subagentes para tarefas realmente independentes
- ✓Pedir relatório estruturado de cada subagente
- ✓Escolher modelo adequado por tipo de tarefa
✗ O que NÃO fazer
- ✗Criar subagentes para tarefas sequencialmente dependentes
- ✗Deixar o escopo de cada agente vago
- ✗Usar subagentes para tarefas triviais (overhead desnecessário)
- ✗Ignorar os relatórios e pedir tudo de novo
⚙️ Skills Personalizadas
Skills são arquivos de prompt versionados no repositório que definem procedimentos reutilizáveis. Crie uma vez, invoque em qualquer sessão, compartilhe com toda a equipe. O resultado é padronização de processo sem atrito.
📁 Estrutura de Skills
Skills vivem em .claude/skills/. Cada arquivo é um prompt markdown que descreve um procedimento específico.
- • techdebt.md — instrui o Claude a varrer dívida técnica: TODOs, código duplicado, dependências antigas
- • code-review.md — define como revisar PRs: checklist de segurança, performance, legibilidade
- • api-docs.md — padrão de documentação de endpoints da equipe
- • deploy-check.md — lista de verificação pré-deploy específica do projeto
skills/
techdebt.md
code-review.md
api-docs.md
deploy-check.md
CLAUDE.md
📊 Por que versionar Skills no Repo
- Padronização: todos na equipe usam exatamente os mesmos procedimentos
- Histórico: evolução das skills rastreada pelo git como qualquer outro código
- Onboarding: novo membro do time herda todo o conhecimento acumulado automaticamente
- Revisão: PRs de skills permitem discussão sobre processo antes de adotar
💡 Dica Prática
Comece com apenas 2–3 skills para os processos mais repetitivos da equipe. Skills de code review e techdebt são bons pontos de partida porque todo projeto acumula dívida e toda equipe revisa código. Adicione mais conforme as necessidades ficam claras.
✓ O que FAZER
- ✓Versionar skills no repositório com git
- ✓Nomear arquivos de forma descritiva
- ✓Incluir exemplos de output esperado na skill
- ✓Revisar e atualizar skills conforme o processo evolui
✗ O que NÃO fazer
- ✗Criar skills muito genéricas (sem valor específico)
- ✗Manter skills desatualizadas no repo
- ✗Ter skills só no seu setup local (não compartilhadas)
- ✗Criar skills para tarefas que só acontecem uma vez
💰 Haiku para Subagentes
Ao criar subagentes, você pode definir o modelo de cada um individualmente. Para processamento de grandes volumes de dados ou tarefas mecânicas, use Haiku. Reserve Opus ou Sonnet para síntese e decisões críticas. O resultado: custo controlado sem sacrificar qualidade onde importa.
⚖️ Estratégia de Modelos por Papel
Pense nos subagentes como uma equipe com papéis diferentes. Analistas de dados (Haiku) coletam e processam em volume. O gerente sênior (Opus) toma as decisões com base nos resumos recebidos.
- • Haiku: leitura de arquivos, busca de padrões, extração de dados, sumarização de logs
- • Sonnet: análise de código moderada, escrita de testes, tarefas de complexidade média
- • Opus: síntese final, decisões arquiteturais, revisão crítica, raciocínio complexo
padrões de erro recorrentes.
Use subagentes com Haiku para processar os logs
(centenas de milhares de tokens, tarefa mecânica).
Após o processamento, consolide os achados aqui
no Opus e proponha as correções necessárias."
📊 Impacto no Custo
- Cenário sem otimização: 500k tokens processados no Opus — custo elevado para tarefa mecânica
- Cenário otimizado: 500k tokens no Haiku + 2k tokens de resumo no Opus — economia de ~90%
- Qualidade mantida: o Opus ainda faz a análise final com o resumo compacto recebido
- Escalabilidade: processar 10x mais dados com o mesmo orçamento
💡 Dica Prática
Sempre que um subagente vai processar dados em volume (logs, arquivos, listas longas), use Haiku. A chave é garantir que o subagente devolva um resumo compacto — não o dado bruto — para que o agente principal no modelo mais capaz trabalhe de forma eficiente.
✓ O que FAZER
- ✓Usar Haiku para extração, busca e sumarização em volume
- ✓Pedir resumo compacto de volta (não o dado bruto)
- ✓Reservar Opus para síntese e raciocínio complexo
- ✓Definir o modelo explicitamente por subagente
✗ O que NÃO fazer
- ✗Usar Opus para varrer arquivos em volume
- ✗Deixar subagentes enviarem dados brutos ao orquestrador
- ✗Usar Haiku para decisões arquiteturais complexas
- ✗Não monitorar o custo real das sessões
✅ Resumo do Módulo 2.1
Próximo Módulo:
2.2 — Claude.md como Sistema Vivo: mantenha o contexto do projeto sempre atualizado e evite erros repetidos.