Subagents: o que muda quando você deixa de trabalhar sozinho
Até aqui o Claude Code é um único agente conversando com você. Quando a tarefa cresce — refatoração que toca 20 arquivos, investigação em código que você nem conhece, revisão de diff grande — esse modelo começa a pesar. A janela de contexto enche, as respostas ficam lentas, e o agente perde o fio da meada do que era o objetivo original.
Subagents são a solução estrutural. Em vez de fazer tudo no mesmo processo, você dispara agentes secundários em contextos isolados. Cada um tem sua própria janela de contexto, seu próprio conjunto de ferramentas, e devolve ao agente principal só o que interessa: um resumo, um patch, um veredito.
O resultado prático: você consegue rodar três investigações em paralelo enquanto o agente orquestrador mantém o contexto limpo para decisões. Ganha uma fração significativa de tempo em tarefas médias — não porque o modelo ficou mais rápido, mas porque você parou de desperdiçar contexto em trabalho delegável.
Se você chegou aqui sem o panorama geral, volte ao guia definitivo do Claude Code — subagents fazem mais sentido depois de entender as outras seis camadas.
O mecanismo: Task tool + subagent_type
Você dispara um subagent via a ferramenta Task. Um chamado típico:
Task({
description: "Audit auth middleware for token leaks",
subagent_type: "security-auditor",
prompt: "Review src/middleware/auth.ts for..."
})
Três partes importantes:
description— 3-5 palavras para aparecer no transcript do orquestrador.subagent_type— qual tipo de agente rodar (Explore,Plan,debugger,code-reviewer,general-purpose, etc.).prompt— o briefing completo. O subagent não vê a sua conversa; o prompt precisa ser autocontido.
Quando o subagent termina, ele devolve uma única mensagem ao orquestrador. Todo o contexto intermediário (os arquivos que leu, os greps que fez, as ideias descartadas) fica dentro da janela dele — nunca chega ao orquestrador. É essa assimetria que protege o contexto principal.
O catálogo padrão
O Claude Code traz um conjunto de subagents built-in que cobre 80% dos casos reais:
general-purpose— agente genérico para pesquisa multi-passo e tarefas abertas.Explore— busca rápida na codebase, otimizada para encontrar arquivos e símbolos sem encher contexto.Plan— arquiteto de software, desenha planos de implementação.code-reviewer— revisor sênior, checa qualidade antes de merge.debugger— analista de causa raiz para erros, falhas de teste e comportamento inesperado.test-writer— engenheiro de testes, escreve testes de alto valor.security-auditor— audita código para vulnerabilidades.refactorer— especialista em estrutura de código e redução de duplicação.doc-writer— especialista em documentação técnica.
A regra de uso é simples: delegue para o tipo certo em vez de sempre usar o general-purpose. Um code-reviewer roda com prompt system diferente do debugger — ele foi ajustado para procurar problemas típicos de review (naming, duplicação, edge cases), não para rastrear um stack trace.
Para criar seus próprios tipos quando o catálogo não bate com sua rotina, pule para Criando Subagents customizados passo a passo.
Três padrões que pagam o investimento
1. Exploração paralela antes de planejar. Quando você recebe uma tarefa grande numa codebase que não conhece, não faça o orquestrador ler arquivos um por um. Dispare 2-3 Explore em paralelo, cada um com um ângulo diferente: "onde vive a lógica de auth?", "quais testes cobrem essa rota?", "que componentes consomem esse hook?". O orquestrador recebe três resumos e começa a pensar com o mapa na mão — sem ter gasto contexto lendo arquivo por arquivo.
2. Validação independente. Depois de implementar uma mudança sensível — migration, mudança em auth, refatoração de um módulo crítico — dispare um code-reviewer passando o diff e o contexto mínimo. Como ele não viu a conversa original, ele não herda suas racionalizações. Essa "leitura fria" pega problemas que o orquestrador não enxerga mais porque já se convenceu do próprio raciocínio.
3. Trabalho em paralelo ao seu. Nem todo subagent precisa bloquear. Você pode disparar um test-writer em background enquanto continua implementando a feature; quando ele termina, o orquestrador é notificado. Ganha tempo sem perder foco.
Esses três cobrem o básico — padrões mais avançados (fan-out/fan-in, supervisores, delegação encadeada, uso de worktrees para isolamento de filesystem) estão em Padrões de orquestração multi-agente no Claude Code.
Anti-padrões comuns
Delegar o que você não entende. A frase proibida num prompt de subagent é "com base nas suas descobertas, resolva o problema". Isso empurra para o subagent o trabalho de síntese que era seu. O resultado volta vago, porque o subagent tomou decisões sem o seu contexto. Delegue execução ou pesquisa — nunca compreensão.
Prompt pequeno demais. Subagents não veem sua conversa. Se você escreve "revise o diff", ele não sabe qual diff, qual arquivo, qual objetivo. O bom prompt tem três partes: o que fazer, o contexto mínimo (arquivos, linhas, histórico relevante) e o formato esperado da resposta (bullet list curta, veredito sim/não, patch em diff).
Subagent para tarefa trivial. Disparar um subagent para ler um arquivo que você já sabe que precisa ler é overhead puro — você paga latência de startup e perde a interação direta. Use subagent quando o trabalho é paralelo, isolado em contexto, ou precisa de perspectiva independente.
Ignorar o resultado. O orquestrador vê apenas a mensagem final. Se você não sintetiza o que voltou — se não lê, extrai o útil, e integra ao seu próximo passo — o subagent foi desperdício. Delegue só quando vai usar.
Segurança e ferramentas restritas
Cada tipo de subagent carrega um conjunto específico de ferramentas. Um security-auditor pode ter Read, Grep, Glob, Bash(grep *) e Bash(find *) apenas — nada de Edit, Write, curl. Essa restrição é deliberada: limita o blast radius do que um agente pode fazer caso interprete mal o prompt.
Quando você cria subagents customizados, herde essa disciplina. A regra é least privilege: dê ao subagent só as ferramentas que ele precisa para a função. Um revisor não deveria poder editar. Um gerador de testes não deveria poder rodar git push. Para o raciocínio completo sobre autorização, isolamento por worktree e práticas defensivas com o Claude Code, veja Segurança e boas práticas com Claude Code.
Próximos passos
O próximo passo natural depois de entender o conceito é ver subagents resolvendo um problema real. Dois caminhos: se sua prioridade é criar seus próprios tipos, vá para Criando Subagents customizados passo a passo. Se a prioridade é debugar uma falha difícil, leia Debugando com o agente debugger — é o caso de uso onde subagents mais brilham, porque o contexto de debugging é exatamente o tipo de coisa que você não quer no orquestrador. Quando você for levar tudo isso para CI e integrações de time, fecha o ciclo com Claude Code no seu fluxo de desenvolvimento diário.
