Subagentes no Claude Code: Delegar sem perder o controle

O problema do contexto infinito

Imagine que você pede ao Claude para 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 em 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 ser executado em foreground (bloqueante) ou background (paralelo)

Pense neles como estagiários especializados. Você atribui uma tarefa, eles trabalham de forma independente, e reportam quando terminam.

Os subagentes que você já tem

O Claude Code vem com vários subagentes integrados:

O mais útil é o Explore. Quando o Claude precisa buscar algo na sua codebase, 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 seja executado em um subagente isolado com context: fork:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

---
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 é executado em um subagente. Com agent: Explore, você especifica que tipo de agente usar.

Lançamento explícito por tipo

Se você 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 são executados em foreground. Sua sessão espera que terminem.

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 o 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, pressione Ctrl+B. O agente passa para background e você pode continuar.

> Analise todos os testes do projeto
[Começa a executar...]
[Você pressiona Ctrl+B]
> Beleza, enquanto isso, me explique o que faz este 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, status 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 status. Quando termina, o Claude te notifica automaticamente com o resultado.

Dar instruções adicionais

Se um subagente está rodando e você quer adicionar contexto:

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 for possível.

Parar um subagente

Para parar uma tarefa em background:

Pare a tarefa de análise
Cancele o subagente que está rodando

Ou de /tasks, você pode cancelar tarefas específicas por ID.

Retomar um subagente

Os subagentes mantêm seu histórico dentro da sessão. Você pode retomar de 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 prévio.

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 para você.

Manualmente

Crie um arquivo Markdown em .claude/agents/ (projeto) ou ~/.claude/agents/ (global):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
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 por:

- Injeção SQL
- XSS
- Secrets hardcodeados
- Validação de input insuficiente
- Dependências vulneráveis

Relate por severidade: Crítico > Alto > Médio > Baixo.
NÃO modifique código, apenas relate.

Configuração do frontmatter

Modos de permissão

Exemplo: Agente só leitura

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

---
name: test-runner
description: Executa testes e relata 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. Relate:
   - Testes passaram: X
   - Testes falharam: Y
   - Resumo de cada falha (arquivo, linha, erro)

NÃO tente corrigir os testes, apenas relate.

Casos de uso habituais

1. Investigação de codebase

Use 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 esta funcionalidade

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

A revisão acontece em contexto separado. Você recebe feedback sem ruído.

5. Refatoração segura

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

---
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

Você também pode combiná-los: 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-rejeitam 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:

1
2
3
4
5

{
  "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:

1

export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50

Ver transcrições

Os logs dos subagentes são salvos em:

~/.claude/projects/{projeto}/{sessao}/subagents/agent-{id}.jsonl

Útil para debugging ou auditoria.

Desativar background tasks

Se você preferir que tudo seja bloqueante:

1

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