O problema do contexto infinito
Imagine que você pede para o Claude investigar como funciona a autenticação do seu projeto. Ele começa a ler arquivos. Muitos arquivos. De repente você tem 50.000 tokens de contexto cheios de código que você só precisava consultar, não lembrar.
Agora cada resposta fica mais lenta. E mais cara. E quando você quiser fazer outra coisa, todo esse contexto ainda está lá, ocupando espaço mental.
A solução: subagentes. Você lança um agente especializado que faz o trabalho pesado no seu próprio contexto isolado, te devolve um resumo, e desaparece. Sua conversa principal fica limpa.
O que é um subagente
Um subagente é uma instância separada do Claude que:
- Tem seu próprio contexto (não contamina sua conversa)
- Pode ter ferramentas restritas (só leitura, só bash, etc.)
- Pode usar um modelo diferente (haiku para tarefas simples, opus para as complexas)
- Pode executar em foreground (bloqueante) ou background (paralelo)
Pense neles como estagiários especializados. Você atribui uma tarefa, eles trabalham de forma independente, e te reportam quando terminam.
Os subagentes que você já tem
Claude Code vem com vários subagentes integrados:
| Agente | Modelo | Para que serve | Ferramentas |
|---|---|---|---|
| Explore | Haiku | Buscar e analisar código | Só leitura |
| Plan | Herda | Investigar durante planejamento | Só leitura |
| general-purpose | Herda | Tarefas complexas multi-etapa | Todas |
| Bash | Herda | Comandos em contexto separado | Só Bash |
| Claude Code Guide | Haiku | Perguntas sobre Claude Code | Documentação |
O mais útil é o Explore. Quando o Claude precisa buscar algo na sua base de código, lança um Explore que lê arquivos como louco, processa tudo, e devolve só o relevante.
Como lançar subagentes
Do REPL (conversa normal)
Simplesmente peça em linguagem natural:
Use um subagente para investigar como funciona o sistema de cache
Lance o agente Explore para encontrar todos os endpoints da API
Investigue a autenticação em paralelo enquanto eu continuo trabalhando
O Claude entende essas solicitações e usa a ferramenta Task internamente para lançar o subagente apropriado.
De um Skill
Em um skill você pode forçar que execute em um subagente isolado com context: fork:
---
name: deep-analysis
description: Análise profunda de arquitetura
context: fork
agent: Explore
---
Analise a arquitetura completa do projeto.
Gere um relatório com:
- Estrutura de diretórios
- Dependências principais
- Padrões de design detectados
Com context: fork, o skill executa em um subagente. Com agent: Explore, você especifica que tipo de agente usar.
Lançamento explícito por tipo
Se quiser ser específico:
Use o agente Explore para mapear a estrutura do projeto
Use um agente general-purpose para refatorar o módulo de pagamentos
Use o agente Bash para executar a suíte de testes completa
Foreground vs Background
Foreground (bloqueante)
Por padrão, os subagentes executam em foreground. Sua sessão espera até eles terminarem.
Investigue como funciona o rate limiting
[Claude lança subagente, você espera, recebe resultado]
Útil quando você precisa do resultado imediatamente.
Background (paralelo)
Você pode enviar um subagente para background de duas formas:
1. Pedindo explicitamente:
Investigue o sistema de cache em background enquanto reviso outra coisa
2. Com Ctrl+B enquanto está executando:
Se um subagente já está rodando e você quer continuar trabalhando, aperte Ctrl+B. O agente vai para background e você pode continuar.
> Analise todos os testes do projeto
[Começa a executar...]
[Você aperta Ctrl+B]
> Beleza, enquanto isso, me explique o que faz esse arquivo
[Você continua trabalhando, a análise continua em paralelo]
Ver tarefas em background
Use o comando /tasks para ver o que está rodando:
/tasks
Isso mostra todas as tarefas em background com seus IDs, estado e progresso.
Comunicação com subagentes
Saber o que está fazendo
Enquanto um subagente está em foreground, você vê seu progresso em tempo real (que arquivos lê, que comandos executa).
Se está em background, use /tasks para ver o estado. Quando termina, o Claude te notifica automaticamente com o resultado.
Dar instruções adicionais
Se um subagente está rodando e você quer adicionar contexto:
Ah, aliás, ignore os arquivos de teste, só me interessa o código de produção
O Claude tenta passar essa informação para o subagente se possível.
Parar um subagente
Para parar uma tarefa em background:
Pare a tarefa de análise
Cancele o subagente que está rodando
Ou do /tasks, você pode cancelar tarefas específicas pelo ID.
Retomar um subagente
Os subagentes mantêm seu histórico dentro da sessão. Você pode retomar onde pararam:
Continue a análise de autenticação que você fez antes
e agora revise também a autorização
O Claude retoma o subagente com todo seu contexto anterior.
Criar seus próprios subagentes
Com o comando /agents (recomendado)
/agents
Selecione Create new agent, escolha o scope (usuário ou projeto), descreva o que quer, e o Claude gera o arquivo pra você.
Manualmente
Crie um arquivo Markdown em .claude/agents/ (projeto) ou ~/.claude/agents/ (global):
---
name: security-scanner
description: Escaneia código em busca de vulnerabilidades. Usar proativamente após mudanças em autenticação ou manipulação de dados.
tools: Read, Grep, Glob
model: opus
---
Você é um especialista em segurança. Analise o código procurando:
- Injeção SQL
- XSS
- Secrets hardcoded
- Validação de input insuficiente
- Dependências vulneráveis
Reporte por severidade: Crítico > Alto > Médio > Baixo.
NÃO modifique código, apenas reporte.
Configuração do frontmatter
| Campo | Obrigatório | Descrição |
|---|---|---|
name | Sim | Identificador único (minúsculas e hífens) |
description | Sim | Quando usar o agente (Claude lê isso) |
tools | Não | Ferramentas permitidas (padrão: todas) |
disallowedTools | Não | Ferramentas proibidas |
model | Não | haiku, sonnet, opus, ou inherit |
permissionMode | Não | Como lidar com permissões |
skills | Não | Skills a injetar no contexto |
hooks | Não | Hooks do ciclo de vida |
Modos de permissão
| Modo | Comportamento |
|---|---|
default | Pede permissão como sempre |
acceptEdits | Auto-aceita edições de arquivos |
dontAsk | Auto-nega operações não solicitadas |
bypassPermissions | Pula todas as permissões (perigoso) |
plan | Modo só leitura |
Exemplo: Agente só leitura
---
name: code-reader
description: Lê e analisa código sem modificar nada
tools: Read, Grep, Glob
disallowedTools: Write, Edit, Bash
permissionMode: plan
---
Analise o código solicitado.
NUNCA sugira modificações, apenas descreva o que encontra.
Exemplo: Agente de testes
---
name: test-runner
description: Executa testes e reporta falhas. Usar após mudanças de código.
tools: Bash, Read
model: haiku
---
1. Execute: `uv run pytest -x --tb=short`
2. Se houver falhas, leia os arquivos relevantes
3. Reporte:
- Testes passou: X
- Testes falharam: Y
- Resumo de cada falha (arquivo, linha, erro)
NÃO tente consertar os testes, apenas reporte.
Casos de uso comuns
1. Investigação de base de código
Use o Explore para entender como funciona o sistema de notificações
O Explore lê tudo que é necessário, você recebe um resumo sem contaminar seu contexto.
2. Análise paralela
Investigue em paralelo:
- Como funciona a autenticação
- Como funciona o sistema de pagamentos
- Como funciona o envio de emails
O Claude lança três subagentes simultâneos. Cada um investiga sua área.
3. Testes em background
Execute os testes em background enquanto implemento essa feature
Você não precisa esperar. Quando falharem (ou passarem), ele te avisa.
4. Code review isolado
Use um subagente para revisar a segurança das mudanças que acabei de fazer
O review acontece em contexto separado. Você recebe feedback sem ruído.
5. Refatoração segura
---
name: safe-refactor
description: Refatora código com verificações
tools: Read, Edit, Bash
hooks:
PostToolUse:
- matcher: "Edit"
hooks:
- type: command
command: "uv run pytest -x"
---
Cada edição dispara os testes automaticamente.
Subagentes vs Skills: Quando usar cada um
| Necessidade | Usar |
|---|---|
| Instruções reutilizáveis no contexto principal | Skill |
| Tarefa que gera muito output | Subagente |
| Restringir ferramentas para uma operação | Subagente |
| Trabalho paralelo independente | Subagente |
| Processo com etapas definidas que quero acompanhar | Skill |
| Investigação que não preciso lembrar | Subagente |
Você também pode combinar: um skill com context: fork lança um subagente.
Limitações
- Não podem aninhar: Um subagente não pode lançar outro subagente
- Permissões em background: Os subagentes em background auto-negam permissões não pré-aprovadas
- Sessão única: O contexto do subagente vive apenas durante a sessão
Dicas avançadas
Desativar subagentes específicos
No settings.json:
{
"permissions": {
"deny": ["Task(Explore)", "Task(meu-agente-custom)"]
}
}
Auto-compactação
Os subagentes têm auto-compactação aos 95% do contexto. Para disparar antes:
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
Ver transcrições
Os logs de subagentes são salvos em:
~/.claude/projects/{projeto}/{sessão}/subagents/agent-{id}.jsonl
Útil para debugging ou auditoria.
Desativar background tasks
Se preferir que tudo seja bloqueante:
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
Conclusão
Os subagentes são a forma de escalar seu uso do Claude Code sem que o contexto exploda. Delegam trabalho pesado, mantêm sua conversa limpa, e podem trabalhar em paralelo.
Use-os para investigação, análise, testes, e qualquer tarefa que gere muito output que você não precisa lembrar. Crie os seus próprios para tarefas repetitivas com restrições específicas.
A combinação de skills (o que fazer) + subagentes (onde fazer) + hooks (quando validar) te dá um controle bem fino sobre como o Claude trabalha.
TL;DR: Os subagentes são instâncias isoladas do Claude para tarefas específicas. Mantêm seu contexto limpo, podem rodar em paralelo (Ctrl+B), e você pode criar os seus em .claude/agents/. Use /tasks para monitorá-los e /agents para gerenciá-los.
Documentação oficial: Subagents - Claude Code Docs
Este artigo foi escrito originalmente em espanhol e traduzido com a ajuda de IA.