Como e quando usar subagentes no Claude Code

Introdução

Subagentes no Claude Code ganharam um guia oficial em 7 de abril de 2026 detalhando quando delegar compensa, como direcionar a orquestração e quais sinais indicam a hora certa de paralelizar trabalho. A novidade reforça que cada subagente roda em um contexto isolado, entrega apenas o resultado relevante e evita que a conversa principal seja sobrecarregada por arquivos, logs e tangentes.

Em times que programam em monorepos e lidam com múltiplos serviços, a palavra-chave é foco. Subagentes permitem separar exploração de código, validação e implementação, preservando o histórico útil e mantendo a sessão principal enxuta. Além disso, delegação inteligente pode reduzir latência e custo de tokens ao enviar tarefas específicas para modelos mais rápidos, quando apropriado.

Este guia prático mostra como e quando usar subagentes no Claude Code, com exemplos claros, configurações recomendadas, armadilhas comuns e um checklist objetivo para decidir se a delegação vale mesmo a pena no seu fluxo.

O que são subagentes e por que importam

Subagentes são instâncias isoladas do Claude, cada uma com sua própria janela de contexto e permissões. Funcionam como “abas” paralelas, onde uma tarefa secundária, por exemplo investigar um fluxo de autenticação, acontece sem poluir a thread principal. Ao terminar, o subagente retorna apenas os achados relevantes.

O Claude Code já inclui tipos integrados prontos para uso:

Explore, focado em leitura rápida e pesquisa de código, com ferramentas somente leitura e latência baixa.
Plan, usado no modo de planejamento para levantar contexto antes de sugerir estratégias de implementação.
Geral, indicado para tarefas multi etapas que combinam exploração e alterações.

Na prática, isso reduz ruído, economiza contexto e libera a conversa principal para decisões e sínteses, não para despejo de arquivos. Em vários cenários comuns, delegar pesquisa, revisão independente e pequenos consertos paralelos entrega mais resultado por minuto de atenção.

Quando usar subagentes, sinais objetivos de delegação

A decisão de criar um subagente não precisa ser subjetiva. O material oficial lista categorias onde a delegação tende a compensar:

Tarefas com muita pesquisa, quando compreender o sistema exige ler dezenas de arquivos. Sinal, volume de leitura alto. Benefício, receber síntese em vez de raw dumps.
Várias tarefas independentes, como corrigir erros semelhantes em pacotes diferentes. Sinal, subtarefas sem dependência. Benefício, paralelismo encurta o tempo total.
Revisão com olhar fresco, quando isenção é crucial e o histórico pode enviesar o julgamento. Sinal, necessidade de validação limpa. Benefício, feedback objetivo.
Verificação antes do commit, buscando evitar overfitting a testes ou pontas soltas. Sinal, segunda opinião desejável. Benefício, captura de falhas sutis.
Pipelines por fases, por exemplo, desenhar, implementar e testar em etapas distintas, cada qual em seu próprio contexto.

Regra prática simples que melhora resultados, quando a tarefa exige explorar dez ou mais arquivos, ou envolve três ou mais frentes independentes, sinal forte para acionar subagentes.

Como invocar subagentes na conversa diária

A forma mais flexível é pedir explicitamente para usar subagentes. Isso funciona no terminal, no VS Code, no JetBrains, na web e no desktop. Exemplos de comandos naturais efetivos incluem, usar subagente para explorar a autenticação, criar um agente separado para revisão de segurança, ou pesquisar rotas de API, modelos de banco e componentes em paralelo.

Estrutura de prompt que costuma performar bem em paralelismo:

Defina tarefas independentes com bullets claros, por exemplo, mapear endpoints, identificar schema, descrever fluxo de auth.
Diga que podem rodar em paralelo.
Peça somente o sumário de cada parte, não os arquivos completos.

Dicas táticas que fazem diferença na prática, delimite escopo, peça explicitamente paralelização, especifique formato de saída e, quando buscar isenção, solicite um subagente que não veja a discussão anterior. Ao notar que uma execução vai demorar, envie em background e continue a conversa, os resultados aparecem automaticamente ao concluir.

![Laptop com editor de código e caneca de café, representando foco e produtividade]

Criando subagentes personalizados para especialistas recorrentes

Quando o time repete pedidos do tipo revisor de segurança, escritor de testes ou revisor de docs, vale criar um subagente customizado e deixar o Claude delegar automaticamente quando a tarefa corresponder à descrição. Esses agentes ficam em arquivos Markdown dentro de .claude/agents no projeto, ou em ~/.claude/agents no nível do usuário, cada um com prompt do sistema, permissões de ferramentas e modelo definido.

Há um comando que agiliza a configuração, /agents, que guia a criação interativa, gera um primeiro rascunho e permite definir permissões, modelo, cor de identificação e até memória persistente no escopo do usuário, ~/.claude/agent-memory, para acumular padrões aprendidos entre sessões. Alternativamente, é possível definir via CLI com o parâmetro --agents passando JSON.

Exemplo enxuto de frontmatter para um revisor de segurança, com escopo, ferramentas e modelo alinhados ao objetivo, seguido de instruções objetivas para reportar achados com referências de arquivo e linha. Esse nível de especificidade torna a delegação mais precisa e reduz hallucinations.

Decisão crítica na personalização, usar o modelo certo para cada papel. Em tarefas de leitura rápida e ampla, um modelo mais veloz pode ser suficiente. Já em análises complexas, optar por um modelo mais capaz faz sentido. A documentação oficial cita que subagentes ajudam a controlar custos ao rotear trabalho adequado para modelos como Haiku, quando a natureza da tarefa permitir.

Políticas com CLAUDE.md, como padronizar delegação na equipe

Ilustração do artigo

Além de especialistas, projetos podem formalizar quando um subagente deve ser usado por padrão. O arquivo CLAUDE.md permite definir regras como, toda revisão de código deve usar um subagente somente leitura, checar vulnerabilidades, performance e aderência a padrões. Ao carregar CLAUDE.md no início de cada conversa, a consistência se mantém entre sessões e colegas, sem depender de alguém lembrar de pedir.

Exemplo útil, uma seção chamada Code review standards que exige uso de subagente read only em toda revisão, elenca checagens obrigatórias e define o formato do relatório, priorizado e com file:line. Resultado, previsibilidade, qualidade e menos variação entre revisores.

Skills, a ponte entre playbooks e subagentes

Skills estendem o que o Claude pode fazer com comandos reutilizáveis. Cada skill vive em um diretório com SKILL.md, frontmatter e corpo com instruções detalhadas. Diferente do CLAUDE.md, o conteúdo da skill só é carregado quando usado, o que minimiza custo de contexto até a invocação. Existem skills empacotadas como /simplify, /batch, /debug e /loop.

As skills seguem o padrão aberto Agent Skills e podem rodar dentro de um subagente, basta definir context, fork, e indicar o agente preferido no frontmatter. Isso permite transformar checklists extensas em procedimentos automatizados que rodam isolados, por exemplo, uma skill de pesquisa que sempre usa o Explore com thoroughness apropriado.

Caminho recomendado para começar, criar uma skill simples, como explain-code, com passos para analogias e diagramas, e iterar. Ao perceber uso recorrente, evoluir para rodar essa skill em um subagente e ganhar isenção, paralelismo e organização.

![Matriz verde simbolizando análise automatizada e leitura massiva de arquivos]

Casos práticos, prompts e padrões que funcionam

Pesquisa de autenticação em um monorepo, acione um subagente Explore para mapear middlewares, handlers de login e rotas de refresh, pedindo um sumário com trechos relevantes e referências de arquivo. Se o volume for grande, aumente a thoroughness.
Busca de problemas de segurança antes do merge, use um subagente revisor com ferramentas de leitura, peça achados priorizados e recomendações de correção, exigindo menção explícita quando nada for encontrado para evitar falsos positivos inventados.
Correções paralelas de erros de tipagem TypeScript em pacotes independentes, solicite três subagentes simultâneos, cada um focado em um pacote. A independência entre subtarefas destrava ganho real de tempo.
Revisão independente pós implementação, peça um subagente com contexto fresco e somente leitura para verificar fluxos críticos, como pagamentos, checando vulnerabilidades, casos de borda e lacunas de tratamento de erro.

Prompt base reutilizável para paralelismo controlado:

Objetivo, “Use subagentes para explorar o codebase em paralelo”.
Tarefas, listar endpoints e propósitos, identificar schema e relacionamentos, mapear fluxo de auth.
Saída, “Entregue apenas sumários, cite arquivos, não inclua conteúdo integral”.
Observação, “Estes itens podem rodar em paralelo”.

Onde subagentes podem atrapalhar, limites e trade offs

Nem todo cenário pede delegação. A própria documentação destaca casos onde um único contexto é mais simples, por exemplo, trabalho estritamente sequencial em que cada etapa depende integralmente da anterior, ou edições no mesmo arquivo, que tendem a gerar conflitos se feitas por agentes paralelos. Nesses casos, concentre o trabalho em uma só sessão para evitar sobrecarga de coordenação.

Outro limite operacional, subagentes não criam outros subagentes, evitando recursão descontrolada. Em contrapartida, é possível rodá los em foreground ou background, retomar execuções e até isolar operações de alto volume para não poluir o histórico. Quando custos importam, rotear partes da investigação para um modelo mais barato e rápido pode ser um ajuste fino relevante.

Configuração, permissões e memória, garantindo segurança e eficiência

Subagentes customizados permitem granularidade no acesso a ferramentas, definindo listas permitidas e bloqueadas, além de modos de permissão. Isso ajuda a reforçar princípios de menor privilégio, por exemplo, revisores que não podem editar, apenas ler. As definições podem viver no projeto, no usuário, em plugins ou até serem injetadas por administradores via configurações gerenciadas, respeitando precedências claras entre escopos.

Para cargas recorrentes, a memória persistente por usuário ajuda a acumular conhecimento útil, como padrões e convenções, sem carregar tudo em cada sessão. Hooks permitem regras condicionais, por exemplo, ativar um agente específico em determinadas rotas ou fases do pipeline. E, quando skills entram no jogo, dá para pré carregar instruções, exemplos e scripts, compondo um toolkit sob medida que roda dentro de subagentes quando necessário.

Checklist decisório, vale delegar agora

Existem 3 ou mais subtarefas independentes que não se bloqueiam mutuamente?
A exploração deve ler 10 ou mais arquivos ou vasculhar diretórios extensos?
Uma segunda opinião isenta agregaria valor antes do commit?
É desejável separar pesquisa, planejamento e implementação por fases nítidas?
Um especialista recorrente, como segurança ou testes, já merece um subagente fixo?

Se a resposta positiva aparecer duas vezes ou mais, delegar via subagentes tende a trazer ganhos de tempo, clareza e custo.

Conclusão

Subagentes no Claude Code encurtam o caminho entre pergunta e entrega, já que executam investigações pesadas fora do contexto principal e devolvem apenas o que importa. A documentação de 7 de abril de 2026 consolida padrões e sinais objetivos para acertar o timing da delegação, além de mostrar como invocar, personalizar e automatizar o uso com CLAUDE.md e skills.

Ao adotar critérios claros e configurar especialistas recorrentes, times criam um ecossistema de agentes que trabalha em paralelo, sem atrito e com custo sob controle. Valor real vem do equilíbrio, delegar quando os sinais apontam ganho e concentrar quando a sequência pede continuidade. Essa cadência faz o Claude Code render mais com menos atrito, e coloca cada tarefa no contexto certo para evoluir sem ruído.