A primeira vez que usei um subagente, usei de forma errada. Ativei um para renomear uma variável. Uma variável. Foi como contratar um empreiteiro para trocar uma lâmpada — mais lento, mais caro e ligeiramente ridículo. Então, antes de mostrar como configurar um subagente no Claude Code, deixa eu ser direto sobre quando você não deveria usá-lo.
Um subagente é uma instância separada do Claude para a qual sua sessão principal pode delegar uma tarefa. Ele tem sua própria janela de contexto — uma ardósia em branco —, faz o trabalho e devolve um resumo. A palavra-chave é separada. O trabalho do subagente não polui a sua conversa principal. Ele explora, percorre dez arquivos, e a sua sessão principal só vê a conclusão.
Esse é o objetivo completo dos subagentes, e é por isso que a maioria dos iniciantes os usa errado.
Quando os subagentes realmente ajudam
Eles ajudam quando uma tarefa de outra forma encheria seu contexto principal com coisas que você não precisa manter.
Pense em procurar em uma base de código grande "onde tratamos a autenticação?" Sem um subagente, o Claude lê quinze arquivos na sua conversa principal, e esses quinze arquivos ficam no contexto pelo resto da sessão, consumindo tokens a cada turno. Com um subagente, essa exploração acontece em uma janela descartável. Você recebe de volta "a autenticação está em src/auth/, veja como funciona" — três frases em vez de quinze arquivos.
Portanto: os subagentes justificam seu uso quando o trabalho é exploratório (muita leitura, pequena conclusão) ou paralelo (várias coisas independentes ao mesmo tempo). Buscar, investigar, executar uma grande suíte de testes e resumir os falhos, revisar um diff contra uma checklist — esses são casos de uso perfeitos.
Este é o teste que uso agora. Pergunte a si mesmo: esta tarefa vai ler muito, mas produzir pouco? Se sim, subagente. Se a tarefa é uma edição direta que você já sabe como fazer, faça diretamente. Renomear uma variável não lê nada e produz uma mudança precisa. Sem subagente.
Quando NÃO usá-los
Não use um subagente para uma edição de arquivo único que você já entende. Não use um para trabalho sequencial onde cada etapa depende de ver a anterior. E não use apenas porque parece sofisticado. Cada subagente tem uma sobrecarga — ele inicializa, constrói seu próprio contexto, reporta de volta. Para trabalhos pequenos, essa sobrecarga custa mais do que economiza.
Os modelos Claude mais recentes também são bem conservadores em criar subagentes por conta própria, o que geralmente está correto. Se você quiser delegar, muitas vezes precisa pedir explicitamente ou configurá-lo. O que nos leva ao como.
Configurando um subagente personalizado
O Claude Code permite que você defina subagentes nomeados como arquivos. Coloque um arquivo markdown em .claude/agents/ no seu projeto (ou na configuração do seu diretório home para um global). Aqui está um real que uso para revisão de código:
---
name: reviewer
description: Reviews a diff for bugs and missing edge cases. Use after writing code, before committing.
tools: Read, Grep, Bash
---
You are a focused code reviewer. Given a diff or a set of changed files:
1. Read the changed code and the files it touches.
2. Look for actual bugs — off-by-one, null handling, wrong async behavior.
3. Check for missing edge cases and untested paths.
4. Report findings as a short list, each with a severity (high/medium/low).
Don't rewrite the code. Don't nitpick style. Report what you find and stop.
Algumas coisas merecem destaque. Aquela linha description não é decoração — é como o Claude decide quando delegar para este agente. Escreva-a como você escreveria a descrição de uma ferramenta: diga quando recorrer a ela, não apenas o que ela faz. "Use após escrever o código, antes de fazer o commit" dá ao Claude um gatilho concreto.
A linha tools delimita o que o subagente pode tocar. Meu reviewer recebe Read, Grep e Bash — suficiente para inspecionar e executar testes, nada para editar. Isso é deliberado. Um reviewer não deveria estar mudando o seu código. Restringir a lista de ferramentas mantém o subagente focado na tarefa e é uma preocupação a menos.
O corpo é o prompt de sistema do subagente — toda a sua personalidade e função. Note que é específico e delimitado. "Reporte o que encontrar e pare" importa, porque do contrário um subagente ansioso começa a corrigir coisas, e agora você tem mudanças que não pediu.
Usando-o
Uma vez que o arquivo exista, você pode invocá-lo em uma sessão:
Use o subagente reviewer no meu último commit.
O Claude o lança, o subagente faz sua leitura e reporte no próprio contexto, e você recebe de volta uma lista limpa de descobertas — sem que quinze arquivos aterrisem na sua conversa principal. Para exploração, você nem precisa de um arquivo personalizado; o subagente geral embutido lida bem com tarefas ad hoc de "vá descobrir X".
A mudança de mentalidade
Isso é o que finalmente fez os subagentes fazerem sentido para mim. Pare de pensar neles como "um Claude mais poderoso". Eles não são mais inteligentes. São uma forma de manter o contexto principal limpo, enviando o trabalho bagunçado para outro lugar.
Uma vez que você vê dessa forma, a questão de quando usar se responde sozinha. Trabalho bagunçado, cheio de leitura, descartável? Delegue. Trabalho preciso que você já consegue imaginar? Só faça. Um reviewer que executa seus testes e entrega uma lista de descobertas — ótimo. Um empreiteiro para trocar uma lâmpada — não tanto.
Escreva um subagente esta semana. Faça-o o reviewer acima. Execute-o no seu próximo commit. Então você sentirá a diferença, e saberá exatamente quando recorrer ao próximo.