Subagentes do Claude Code: Configuração, Ajustes e Quando Utilizá-los

A maioria das sessões do Claude Code fica lenta e bagunçada pela mesma razão: cada grep exploratório, cada despejo de logs e cada “deixe-me verificar mais um arquivo” permanece na conversa principal para sempre.

Os subagentes existem para corrigir exatamente esse problema. Eles são um dos primitivos de agente integrados ao Claude Code para lidar com trabalho ruidoso e paralelizável — uma maneira de empurrar a bagunça para uma janela isolada e trazer apenas o resumo que importa.

Um subagente não é um Claude mais inteligente, nem é a mesma coisa que uma Skill (Habilidade). É um agente de raciocínio separado com sua própria janela de contexto, sua própria lista de ferramentas permitidas e sem memória da sua conversa atual, a menos que você o bifurque explicitamente. Compreender essa distinção é a diferença entre uma configuração de subagente que silenciosamente economiza seu orçamento de contexto e outra que apenas adiciona latência sem nenhum benefício.

Subagentes vs Skills vs MCP

O Claude Code oferece três pontos de extensão que resolvem problemas diferentes e que frequentemente são confundidos porque os três podem tecnicamente “ajudar com uma tarefa”.

Uma regra prática útil: um gancho (hook) impõe uma restrição rígida de forma determinística, uma Skill dá ao agente principal uma capacidade inline, e um subagente é para trabalho que você deseja delegar e manter completamente fora do contexto principal. Se o trabalho de uma Skill é orquestrar uma ferramenta que ainda não existe, isso geralmente é um sinal de que você precisa de um servidor MCP, não de um subagente. O Claude Code não está sozinho nessa estrutura — o ecossistema do OpenCode tem uma ideia comparável em seus agentes especializados, que dividem planejamento, pesquisa e revisão entre papéis dedicados de maneira semelhante.

O que é realmente um subagente

Três propriedades definem um subagente do Claude Code, e todas as três importam para o uso:

• Contexto isolado. Um subagente começa com uma janela limpa. Ele não vê o histórico da sua conversa, a menos que você o bifurque explicitamente, o que mantém sua saída livre de contaminação por qualquer coisa discutida três turnos atrás.
• Uma lista de ferramentas permitidas restrita. Subagentes podem usar apenas um subconjunto do que a sessão pai já possui — eles não podem conceder novas capacidades a si mesmos, e um subagente bem projetado deve receber apenas as ferramentas que seu trabalho requer (ferramentas de somente leitura para um agente de pesquisa, por exemplo).
• Sem visibilidade entre subagentes. Subagentes não podem ver o trabalho em andamento uns dos outros. Se a tarefa B realmente precisar da saída da tarefa A, isso é uma dependência sequencial, não algo que você possa paralelizar entre dois subagentes.

O gatilho para recorrer a um não é “esta tarefa é difícil”. É “esta tarefa é ruidosa” — o tipo de trabalho que gera muita saída intermediária (dezenas de leituras de arquivos, um log longo, um grep exploratório em todo o repositório) onde nenhum desse material intermediário precisa sobreviver para o seu próximo turno de conversa.

Quando usar um subagente (e quando não usar)

Bons usos: exploração de base de código antes de uma grande mudança, execuções automatizadas de testes onde você se importa apenas com pass/fail e resumos de falhas, revisões de segurança ou estilo, e qualquer tarefa de pesquisa em múltiplos passos cuja saída bruta inundaria sua sessão principal.

Maus usos: consultas de dois segundos (“o que esta função retorna”), qualquer coisa que exija refinamento contínuo e estreito, e tarefas dependentes que você se tenta “paralelizar” mesmo que a segunda precise da resposta da primeira. Usar um subagente para uma consulta trivial apenas adiciona a sobrecarga de iniciar uma nova janela de contexto sem nenhum benefício real de isolamento.

Medindo o retorno: matemática de contexto e custo

A proposta de valor dos subagentes é abstrata até que você coloque números em uma tarefa real. Pegue uma comum: faça grep em um serviço de ~500 arquivos para encontrar cada lugar onde uma chave de configuração depreciada ainda é lida, e então reporte os matches exatos de arquivo:linha.

Isso é uma redução de aproximadamente 15-20x no que sua sessão principal tem que carregar para aquela etapa, que é o mecanismo real por trás de “subagentes mantêm sessões mais rápidas” — não é mágica, é contexto que nunca foi carregado em primeiro lugar.

O lado do custo se compõe da mesma maneira. Usando os preços da análise de preços do Claude Code, rodar essa mesma passagem de exploração no Opus ($5/MTok entrada, $25/MTok saída) custa aproximadamente $0.20-0.25 apenas pelos ~40K tokens de entrada. Redirecionando para o Haiku ($1/MTok entrada, $5/MTok saída) reduz isso para $0.04-0.05 — e o orçamento do Opus da sessão principal nunca é tocado pelos tokens de exploração, já que ele só vê o resumo de ~2K tokens.

Definindo um subagente personalizado

Subagentes personalizados vivem como arquivos Markdown com frontmatter YAML, seja com escopo de projeto em .claude/agents/ (cometido ao repositório, compartilhado por toda a equipe) ou escopo de usuário em ~/.claude/agents/ (ferramentas pessoais que você traz para cada projeto).

---
name: code-reviewer
description: >
  Revisa mudanças em staged por bugs, problemas de segurança e violações de estilo
  antes do commit. Use quando o usuário pedir para revisar, auditar ou verificar
  mudanças antes de fazer commit ou abrir um PR.  
tools: Read, Grep, Glob
model: sonnet
skills:
  - security-checklist
---
Você é um revisor de código cuidadoso. Leia o diff em staged, sinalize
problemas concretos com referências de arquivo:linha e termine com um
resumo curto de pass/fail. Não modifique nenhum arquivo.

O campo description é a linha mais importante do arquivo. É o que a lógica de roteamento da sessão pai lê para decidir se este subagente se encaixa na tarefa atual. Escreva como um anúncio de vaga — nomeie a condição de gatilho explicitamente, não algo vago como “ajuda com código”. Descrições vagas são puladas ou mal aplicadas pelo despacho automático.

O campo tools é sua fronteira de isolamento. Dê a um subagente de pesquisa Read, Grep e Glob e nada mais; dar acesso a todas as ferramentas disponíveis derrota todo o ponto de rodá-lo em um sandbox restrito. O campo opcional skills pré-carrega o conteúdo completo de Skills nomeadas no contexto de inicialização do subagente — útil quando um subagente precisa de conhecimento de domínio sem gastar um turno descobrindo e carregando-o no meio da tarefa.

Roteamento de modelo: modelos baratos para trabalho braçal

Subagentes também são onde o controle de custos fica real. Roteie descoberta de arquivos, varredura de logs e outro trabalho barato de verificar para o Haiku, e reserve Sonnet ou Opus para as etapas pesadas de raciocínio — decisões de arquitetura, debug ambíguo, qualquer coisa onde errar seja caro. Haiku é aproximadamente 15x mais barato por token que Opus, e no tipo de exploração ruidosa para a qual os subagentes são feitos, essa lacuna se soma rapidamente em uma sessão de trabalho real.

O padrão Explore, Plan, Execute

Para trabalho complexo e em múltiplos passos, o padrão que se sustenta na prática é Explore, Plan, Execute — usando subagentes baratos para as partes que geram ruído, e mantendo o gate de revisão humana no único lugar onde realmente importa.

O detalhe chave que as pessoas entendem ao contrário é onde o gate de revisão pertence. A exploração é barata, então deixe um subagente ler livremente sem pedir permissão primeiro. O planejamento é analítico, então deixe o agente desenhar a abordagem por conta própria. Mas antes que qualquer agente modifique arquivos, você quer ver o plano e aprová-lo — é para isso que o modo de planejamento do Claude Code (permissionMode: plan) serve, e é o mesmo princípio discutido nas melhores práticas de vibe coding ao revisar cada diff antes que ele seja aplicado.

Erros comuns

Um punhado de erros aparece repetidamente quando equipes começam a escrever subagentes personalizados:

• Descrições vagas. “Ajuda com código” nunca roteará corretamente. Nomeie a condição de gatilho exata.
• Acesso a ferramentas excessivamente amplo. Dar acesso de escrita e bash a um subagente de pesquisa de somente leitura remove a garantia de isolamento que o tornou digno de criação em primeiro lugar.
• Paralelização de tarefas dependentes. Se a tarefa B precisa da saída finalizada da tarefa A, rode-as sequencialmente — subagentes não podem coordenar em meio à tarefa como um orquestrador compartilhado pode. Para fluxos de trabalho que realmente precisam de agentes conversando entre si em meio à tarefa, isso é um formato diferente de problema; veja padrões de orquestração multi-agente se você estiver construindo um sistema de produção em vez de um fluxo de trabalho de repositório único.
• Usar um subagente para trabalho trivial. “Formate este JSON” ou “rode este único comando” não precisa de uma janela de contexto fresca; faça-o diretamente.

Exemplo prático: um subagente de revisão de código do início ao fim

Digamos que você queira que todo commit não trivial seja revisado antes de ser aplicado. Coloque a definição code-reviewer mostrada anteriormente em .claude/agents/code-reviewer.md, faça commit para que toda a equipe compartilhe o mesmo revisor, e invoque-o com uma solicitação natural como “revise minhas mudanças em staged antes de eu fazer commit”. O Claude Code corresponde sua solicitação à description do subagente, inicia-o com acesso apenas a Read, Grep e Glob, e ele retorna com achados referenciados por arquivo:linha e um resumo de pass/fail — nenhum do ruído arquivo por arquivo para chegar lá nunca toca sua sessão principal.

Como isso parece no transcript principal, anotado:

Você:  revise minhas mudanças em staged antes de eu fazer commit

Main: [despacha subagente code-reviewer — 6 arquivos lidos, 1 passagem de grep,
       zero disso mostrado aqui]

Main: achados do code-reviewer:
      - auth/session.go:142 — caminho de refresh do token não lida com token
        de refresh expirado; cai em dereferência nula
      - auth/session.go:203 — estilo: erro envolvido sem %w
      PASS/FAIL: FAIL (1 problema bloqueante)

Seis leituras de arquivo e uma passagem de grep aconteceram, e sua sessão principal pagou exatamente por quatro linhas disso. Essa lacuna — tudo o que o subagente fez versus o resumo de três linhas que você realmente vê — é toda a proposta de valor em um único transcript.

Se sua equipe também usa andaimes de Spec-Driven Development, um subagente de revisão encaixa-se naturalmente na etapa de validação; veja GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows para comparar como esse gate de revisão se compara em setups SDD portáteis e integrados ao IDE.

Vale a pena configurar subagentes personalizados?

Não no primeiro dia. O subagente de propósito geral integrado já cobre a maioria das delegações de exploração e pesquisa sem você escrever um único arquivo YAML, e uma única passagem Explore-Plan-Execute é suficiente para a maioria do trabalho diário. Escreva um arquivo personalizado .claude/agents/*.md apenas depois que você tiver delegado a mesma tarefa manualmente três vezes — um revisor de código, um triager de testes, um agente de lookup de docs para uma biblioteca interna específica. Equipes que escrevem cinco subagentes em sua primeira semana geralmente acabam com cinco campos description obsoletos que ninguém atualiza quando a condição de gatilho real deriva, o que quebra silenciosamente o roteamento automático meses depois. Comece com zero subagentes personalizados, adicione um de cada vez, e apenas quando a repetição — não a utilidade teórica — exigir.

Limitações conhecidas

Algumas arestas ásias valem a pena conhecer antes de construir em torno de subagentes:

• Sem delegação recursiva. Um subagente não pode gerar seus próprios subagentes. Se uma tarefa realmente precisar de uma segunda camada de delegação, isso é um sinal de que você quer um formato de orquestração diferente — veja padrões de orquestração multi-agente para ver como isso se parece fora de uma única sessão do Claude Code.
• Sem memória entre invocações. Cada despacho começa do zero, mesmo que você tenha chamado o mesmo subagente cinco minutos atrás em uma tarefa relacionada. Não há mecanismo integrado para um subagente lembrar sua última execução.
• Isolamento é uma lista de ferramentas permitidas, não um sandbox. Um subagente com acesso Bash ainda pode tocar o sistema de arquivos e a rede como qualquer outra chamada de ferramenta. Restringir tools reduz o raio de explosão; não cria uma fronteira de segurança rígida.

Solução de problemas

Subagente nunca aciona. A descrição quase sempre é o problema. Reescreva-a em torno da condição de gatilho específica em vez de uma declaração de capacidade geral, e verifique duas vezes se o arquivo está em .claude/agents/ (projeto) ou ~/.claude/agents/ (pessoal) com a extensão correta.

Subagente consome muito contexto mesmo assim. Verifique a lista de ferramentas permitidas (tools) — um conjunto de ferramentas excessivamente amplo convida a uma exploração excessivamente ampla. Verifique também se a tarefa deveria ter sido dividida em dois subagentes em vez de um fazendo tudo.

Uma skill listada não carrega dentro do subagente. O Claude Code ignora uma skill ausente ou desativada nomeada no campo skills em vez de falhar na execução, e registra uma linha a esse respeito na saída de debug (/debug da sessão principal, então reproduza o despacho) — algo como skill "security-checklist" not found, skipping. Rode /doctor depois para confirmar que o resto da sua configuração está saudável.

Os resultados parecem inconsistentes entre execuções. Isso frequentemente é um problema de roteamento de modelo, não um problema de design de subagente — trabalho pesado de raciocínio atribuído a um modelo barato variará mais. Mova-o para Sonnet ou Opus e mantenha Haiku para as etapas determinísticas e de baixa ambiguidade.

Subagentes são uma peça de um conjunto de ferramentas muito maior; se você está comparando o Claude Code com o resto do ecossistema de ferramentas de desenvolvimento de IA antes de se comprometer com este fluxo de trabalho, esse panorama é um bom próximo passo.

Links úteis

• Instalação e configuração do Claude Code para Ollama, llama.cpp, preços
• Claude Skills e SKILL.md para Desenvolvedores
• GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows
• O que é Vibe Coding?
• Padrões de Orquestração Multi-Agentes: Um Guia Prático
• Aprofundamento nos Agentes Especializados Oh My Opencode
• Ferramentas de Desenvolvimento de IA: O Guia Completo