Subagente é um assistente que roda numa conversa separada, com contexto próprio, ferramentas próprias e permissão própria. Ele faz o trabalho barulhento lá dentro e devolve só o resumo — o que ele leu não entra na sua conversa.
É a resposta para a conversa que vai piorando: não é o modelo que ficou pior, é que cada arquivo lido, cada busca e cada saída de teste ficou ali ocupando espaço.
Quando não usar (a parte que ninguém conta)
A documentação oficial lista quatro casos em que a conversa principal ganha:
- A tarefa precisa de idas e vindas ou refinamento passo a passo
- Várias etapas compartilham o mesmo contexto (planejar, implementar, testar)
- Você está fazendo uma mudança pequena e direta
- O tempo de resposta importa — um subagente que não é fork começa do zero e precisa de tempo para juntar contexto
Quando vale
- A tarefa produz saída longa que você não precisa ver (rodar a suíte inteira e reportar só as falhas)
- Você quer limitar as ferramentas daquele trabalho
- O trabalho se fecha sozinho num resultado resumido
Criando um
Arquivo de texto em .claude/agents/ (do projeto) ou ~/.claude/agents/ (todos).
Dois campos são obrigatórios: name e description.
.claude/agents/revisor.md:
---
name: revisor
description: Revisa código buscando qualidade e boas práticas
tools: Read, Glob, Grep
model: sonnet
---
Você é um revisor de código. Ao ser chamado, analise o código e dê
retorno específico e acionável sobre qualidade, segurança e boas práticas.
Chamando:
Use o subagente revisor para olhar as mudanças de autenticação.
Ou por menção: @"revisor (agent)" olha essas mudanças
Os campos que mais rendem
| Campo | O que faz |
|---|---|
name | Obrigatório. Minúsculas e hífen. Sem : |
description | Obrigatório. Quando delegar para ele |
tools | Lista do que ele pode usar. Omitido, herda tudo |
model | haiku, sonnet, opus ou inherit (padrão) |
memory | user, project ou local — dá memória persistente |
skills | Skills pré-carregadas na abertura dele |
isolation: worktree | Roda numa cópia isolada do repositório |
Onde o arquivo vive, por prioridade
| Onde | Alcance | Prioridade |
|---|---|---|
| Managed settings | Organização | 1 (maior) |
--agents na linha de comando | Aquela sessão | 2 |
.claude/agents/ | Aquele projeto | 3 |
~/.claude/agents/ | Todos os seus projetos | 4 |
agents/ de um plugin | Onde o plugin está ligado | 5 (menor) |
Os limites
- 20 subagentes rodando ao mesmo tempo. O vigésimo primeiro falha com
Concurrent subagent limit reached, e o erro manda não tentar de novo. Muda emCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. - Profundidade padrão: três camadas abaixo da conversa principal.
- Não há limite de quantos ele pode abrir ao longo da sessão inteira.
O que ele não herda
Ele não recebe o histórico da conversa. Começa do zero com a tarefa que você
descreveu, mais o CLAUDE.md do projeto.
A exceção é o fork, que herda a conversa inteira — e sai mais barato que abrir
um subagente novo, porque reaproveita o cache do pai. Roda com /subtask.
Três padrões que funcionam
Isolar operação barulhenta — rode a suíte de testes num subagente e receba só as falhas, em vez de mil linhas de saída no seu contexto.
Pesquisa em paralelo — vários subagentes olhando módulos diferentes ao mesmo tempo, cada um devolvendo um resumo.
Encadear — o revisor acha os problemas, o otimizador corrige.
Documentação oficial: https://code.claude.com/docs/en/sub-agents