🛠️ Agent tool (era Task tool)
Na v2.1.63, a Anthropic renomeou o Task tool para
Agent tool. É a primitiva oficial de dispatch — toda delegação passa por ela.
Aliases Task(...) ainda funcionam, mas a doc usa "Agent" agora.
📜 Linha do tempo
Antes da v2.1.63: Task(description="...", subagent_type="...")
Da v2.1.63 em diante: Agent(description="...", subagent_type="...")
Aliases: Task(...) continua resolvendo internamenteO comportamento é idêntico — só o nome mudou. Material antigo com Task não quebra.
📥 O que entra
- •
description— frase curta do trabalho - •
prompt— instrução completa ao subagente - •
subagent_type— qual perfil usar
📤 O que volta
- • Resumo curto do que o subagente fez
- • Não o contexto inteiro dele
- • Orchestrator decide o próximo passo
📝 AGENT.md com frontmatter
Subagentes customizados moram em arquivos .md dentro de .claude/agents/ (projeto)
ou ~/.claude/agents/ (usuário). Frontmatter YAML define o perfil.
⚙️ Estrutura canônica
---
name: revisor-pr
description: "Revisa PRs grandes e devolve checklist priorizado"
model: sonnet # opcional — padrão = modelo do orchestrator
tools: Read, Grep, Glob, Bash # allowlist
disallowedTools: Write, Edit # denylist (aplicada antes)
---
Você é um revisor sênior. Foco em:
- Segurança (injeção, secrets, perms)
- Performance (N+1, alocações)
- Clareza (nomes, comentários, dead code)
Devolva um resumo Markdown com 3 seções:
CRÍTICOS / IMPORTANTES / NICE-TO-HAVE.
O name é o identificador único. Subpastas dentro de agents/ são escaneadas recursivamente
mas não afetam o nome. Nomes duplicados: Claude Code mantém um e descarta o outro sem aviso.
✓ Boas descrições
- ✓"Revisa PRs grandes e devolve checklist priorizado"
- ✓"Pesquisa código legado em
./services/" - ✓"Escreve testes E2E com Playwright"
✗ Descrições ruins
- ✗"Faz coisas" (vago — nunca dispara)
- ✗"Agente útil" (sem critério)
- ✗"Tudo de backend" (sobrepõe outros)
🧠 Subagent vs main agent — escopo de contexto
O ponto fundamental: subagente roda em contexto isolado. O orchestrator não vê o que ele leu — só recebe o resumo final. Isso é feature, não bug.
Main agent: contexto da sessão
Conhece CLAUDE.md, histórico do chat, decisões tomadas. É o "cérebro" da conversa.
Subagent: contexto próprio em branco
Recebe só o prompt da chamada. Lê o que precisa do disco. Devolve resumo.
Explore e Plan pulam o pai
Built-in Explore e Plan pulam CLAUDE.md e git status — ficam rápidos e baratos.
O orchestrator preserva tokens
Em vez de ler 500 arquivos, manda subagente ler. Volta resumo de 200 tokens em vez de 200k.
📐 Modelo mental
Pense em subagentes como estagiários: você delega uma pesquisa, eles voltam com memorando. Você decide. Eles não viram seu cérebro — viram suas mãos.
⚡ Paralelização
Como cada subagente é isolado, você pode rodar vários ao mesmo tempo. Instrução em linguagem natural — Claude faz o spawn.
🚀 Dispatching natural
"Pesquisa os módulos de auth, database e API em paralelo,
cada um em um subagente separado, e sintetize no fim."
# Claude spawna 3 subagentes simultâneos:
# - Subagent A → leu auth/, devolveu resumo
# - Subagent B → leu db/, devolveu resumo
# - Subagent C → leu api/, devolveu resumo
# Orchestrator sintetiza os 3 resumos em uma resposta final.Background tasks: background: true roda sem bloquear. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 desabilita.
✓ Bons casos paralelos
- ✓Pesquisa em N pastas independentes
- ✓Code review por dimensão (sec / perf / clareza)
- ✓Geração de N variantes do mesmo conteúdo
- ✓Auditoria multi-serviço (cada serviço uma instância)
✗ Quando NÃO paralelizar
- ✗Tarefas que dependem do output anterior
- ✗Escrita no mesmo arquivo (corrida de race)
- ✗Coisa pequena (overhead supera ganho)
- ✗Bugs onde estado partilhado importa
💾 Memória persistente em 3 escopos
Subagentes têm memória que sobrevive entre sessões. Três escopos com regra clara de uso.
👤 user
~/.claude/agent-memory/<name>/
- • Persiste entre projetos
- • Preferências pessoais
- • Não vai pro git
📁 project (padrão)
.claude/agent-memory/<name>/
- • Compartilhado pela equipe
- • Vai pro git
- • Recomendado por padrão
🔒 local
.claude/agent-memory-local/<name>/
- • Específico do clone
- • Fora do git (.gitignore)
- • Notas pessoais no projeto
💡 Dica prática
Default project: o ganho de "a equipe inteira tem o mesmo subagente afiado" é maior que o custo de subir notas no repo. Reserve local pra coisa que muda por dev (caminhos absolutos, IDs de ambiente).
⚖️ Quando dispatchar vs fazer direto
Nem toda tarefa merece subagente. Overhead de spawn + lida com resumo às vezes é maior que só fazer.
✓ DISPATCHAR quando
- ✓Pesquisa que vai ler >20 arquivos
- ✓Múltiplas dimensões independentes
- ✓Especialização (revisor sec, escritor de testes)
- ✓Quer preservar contexto do orchestrator
- ✓Trabalho longo que pode ir pra background
✗ FAZER DIRETO quando
- ✗Tarefa pequena (<3 ferramentas)
- ✗Decisões precisam do contexto da conversa
- ✗Iterativo com humano-no-loop
- ✗Output precisa do raw, não resumo
- ✗Debug interativo de um único bug
🧪 Heurística rápida
- Vai usar >30% do contexto se eu fizer direto? → dispatch.
- São N coisas independentes do mesmo tipo? → dispatch em paralelo.
- Preciso do raw output pra próxima decisão? → faça direto.
- É iteração curta com humano vendo? → faça direto.
- É auditoria/varredura que dá pra deixar rodando? → dispatch background.
💡 Dica prática
Em demo de Claude Code, dispatch é o "uau" técnico. Mostre 3 subagentes em paralelo auditando 3 serviços — a sala vê paralelização real, contextos isolados e síntese. Vende Code sozinho.
📋 Resumo do Módulo
Próximo Módulo:
4.8 — 🧩 Skills, connectors, plugins (estrutura, diferenças, onde achar)