Subagentes: quando delegar e quando não

Delegue quando a tarefa produz muita saída, quando ela precisa de ferramentas restritas, ou quando você vai repetir a mesma instrução muitas vezes. Fora disso, sessão única resolve melhor.

O que subagente entrega é isolamento de contexto: a saída verbosa fica na janela dele, e só o resumo volta para a sua conversa. O ganho é a sua janela não encher. Quem delega esperando velocidade costuma se decepcionar.

Este guia cobre o que carrega no início de um subagente, o que não carrega, e três comportamentos documentados que contrariam a intuição.

Três formas de estender o Claude Code, com trade-offs diferentes.

A regra oficial: subagente para operação de alto volume, restrição de ferramenta ou tarefa autocontida. Skill para prompt reutilizável na conversa principal. Agent team para paralelismo sustentado ou coordenação entre sessões.

Traduzindo para decisão: se a saída suja o seu contexto, subagente. Se é conhecimento que você quer aplicar ao trabalho em andamento, skill. Se os trabalhadores precisam conversar entre si, agent team.

Onde cada uma se encaixa está no mapa das cinco camadas de um setup que aguenta produção.

Um subagente é markdown com frontmatter YAML. Só name e description são obrigatórios.

---
name: revisor
description: Revisa código em busca de qualidade e segurança. Use depois de escrever mudanças.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---

Você é um revisor de código sênior.

Ao ser invocado:
1. Rode `git diff` para ver as mudanças recentes
2. Revise apenas os arquivos modificados
3. Cheque clareza, nomenclatura, duplicação, tratamento de erro e segurança

Formato do retorno: Crítico (corrigir), Alerta (deveria corrigir), Sugestão.

São mais de quinze campos disponíveis. Estes seis resolvem quase tudo:

Duas restrições de ferramenta que valem conhecer. Algumas são sempre removidas de subagente, mesmo que você as liste — entre elas AskUserQuestion, EnterPlanMode/ExitPlanMode e EndConversation. E dá para limitar o que o subagente pode criar: tools: Agent(worker, researcher) permite spawnar só esses dois tipos.

Esta é a que mais pega, porque contradiz a feature vizinha.

Leia as linhas 3 e 4 com atenção. Em subagente, o do projeto ganha do pessoal. Em skill, o pessoal ganha do projeto.

Se você tem uma skill deploy pessoal e outra no projeto, roda a pessoal. Se você tem um subagente deploy pessoal e outro no projeto, roda o do projeto. Mesmo nome, mesma estrutura de pastas, comportamento invertido.

A documentação oficial recomenda guardar subagente específico de projeto em .claude/agents/ justamente porque ali ele é versionado e o time compartilha — e a precedência acompanha essa intenção.

A precedência das skills, e o resto do formato, está em como escrever a sua primeira Agent Skill.

Subagente não-fork começa quase do zero. A lista exata importa mais do que parece.

Carrega: o system prompt do corpo do arquivo, a mensagem de delegação que o Claude escreveu, a hierarquia de CLAUDE.md, um snapshot do git status, as skills pré-carregadas pelo campo skills, e a lista dos irmãos que ele pode mensagear.

Não carrega: o histórico da conversa, o seu output style, a memória automática (a menos que o subagente tenha o campo memory próprio) e as skills que você invocou antes.

Essa última é a que gera mais confusão. Você invoca uma skill na conversa principal, delega uma tarefa relacionada, e o subagente se comporta como se a skill não existisse — porque, para ele, não existe. Para levá-la junto, use o campo skills no frontmatter.

E há duas exceções que quase ninguém conhece: os subagentes embutidos Explore e Plan pulam o CLAUDE.md e o git status. É deliberado — os dois existem para ser rápidos e baratos em busca no código, e carregar a hierarquia de contexto atrapalharia esse objetivo.

Ou seja: se você delegou uma busca ao Explore e ele ignorou uma convenção que está no seu CLAUDE.md, isso é o desenho da ferramenta, não um defeito.

O que exatamente entra nessa hierarquia está na anatomia de um CLAUDE.md que funciona.

A janela separada é só uma das camadas. Existem mais três, e elas resolvem problemas diferentes.

Worktree. O campo isolation: worktree roda o subagente num git worktree temporário, criado a partir da branch padrão e removido automaticamente se nada mudou. É a saída para trabalho em paralelo que mexe em arquivo: dois subagentes editando o mesmo repositório se sobrescrevem, dois em worktrees separados não.

isolation: worktree

MCP com escopo. Em vez de deixar um servidor MCP disponível na sessão inteira, o campo mcpServers prende ele a um subagente:

---
name: testador-browser
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

O Playwright existe só para esse subagente. A sessão principal não paga o contexto dele, e nenhum outro subagente o alcança.

Hooks de validação. O frontmatter aceita hooks, o que permite validar antes de executar em vez de confiar no prompt:

tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validar-query-somente-leitura.sh"

O script recebe JSON pelo stdin e sai com código 2 para bloquear. É a diferença entre pedir ao subagente que não escreva no banco e impedir que ele escreva.

Há ainda o maxTurns, que limita quantos turnos agênticos ele roda antes de parar — útil para subagente autônomo que pode entrar em loop.

Um fork é um subagente que herda a sua conversa inteira em vez de começar do zero.

O ponto contraintuitivo está na linha do cache. O fork carrega muito mais contexto e, ainda assim, a documentação lista custo menor entre os motivos para usá-lo — porque ele reaproveita o cache de prompt da conversa principal. Subagente comum começa do zero e paga cache separado.

Isso inverte o instinto de "menos contexto é mais barato". Para tarefa lateral que precisa de bastante contexto da conversa, o fork é o caminho certo e não o desperdício que parece.

Fork serve bem para três coisas: tarefa lateral que depende do que já foi discutido, tentar várias abordagens em paralelo a partir do mesmo ponto, e execução mais barata. Começa com /subtask, e o modo é controlado por CLAUDE_CODE_FORK_SUBAGENT — ligado por padrão em sessão interativa, desligado em headless.

A decisão não é sua, é uma árvore de cinco regras onde a primeira que casa vence:

1. Teammate de agent team in-process → primeiro plano
2. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 → primeiro plano
3. Fork mode ligado (padrão interativo) → background
4. Fork mode desligado e o Claude precisa do resultado → primeiro plano
5. Fork mode desligado e background: true na definição → background

Em primeiro plano, o subagente bloqueia a conversa e os prompts de permissão vão direto para você. Em background, ele roda em paralelo e os prompts sobem para a sessão principal, onde você aprova ou nega cada chamada.

A pegadinha do background: subagente em segundo plano perde quase todas as ferramentas embutidas. Sobra uma allowlist — Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, e mais algumas de worktree e mensagem.

Isso explica um sintoma que parece aleatório: o subagente funciona quando você testa e falha quando roda sozinho. Não é instabilidade — é o conjunto de ferramentas mudando com o modo de execução.

O campo memory liga acúmulo de conhecimento entre sessões, com três escopos:

O project é o mais interessante: um revisor de código que registra os padrões e problemas recorrentes daquele repositório vira conhecimento institucional versionado, e não sai da cabeça de quem configurou.

Vale a mesma restrição do MEMORY.md da memória automática: entram as primeiras 200 linhas ou 25 KB. O resto fica em arquivos de tópico, lidos sob demanda.

Para funcionar, o corpo do subagente precisa instruir explicitamente:

Atualize sua memória com padrões, convenções e problemas recorrentes que
encontrar. Revise a memória antes de começar.

Sem essa instrução, o campo fica ligado e ninguém escreve nada.

Quatro situações em que subagente é a escolha errada.

Quando você precisa do resultado no meio de um raciocínio. Subagente devolve resumo, não o material bruto. Se você precisa dos detalhes para decidir o próximo passo, delegar joga fora justamente o que você ia usar.

Quando a tarefa é curta. O custo de montar contexto novo, carregar CLAUDE.md e o git status não se paga numa tarefa de dois arquivos.

Quando você não sabe avaliar o retorno. Delegar o que você não consegue revisar transfere o risco sem transferir a responsabilidade — e a responsabilidade continua sua no code review.

Quando o problema é ambiguidade, não volume. Subagente resolve contexto sujo. Não resolve requisito mal definido: ele vai começar com menos contexto que você e chutar com mais confiança.

O uso que sempre compensa é o inverso disso: rodar a suíte de testes e devolver só as falhas, buscar documentação e devolver a resposta, processar log e devolver o padrão. Saída grande, retorno pequeno, critério objetivo.

Se a dúvida ainda é qual mecanismo usar, e não quando delegar, a comparação entre skills, subagentes e comandos decide em quatro perguntas.

Um caso de delegação com regra própria é a revisão de código, que roda como subagente forkado em segundo plano: está em git com agente.

Subagente deixa a tarefa mais rápida?

Não necessariamente. Em background ele roda em paralelo, o que pode reduzir tempo de parede. Mas o ganho principal é de contexto: a saída verbosa fica isolada e sua janela não enche. Se você delegar esperando velocidade, o resultado provavelmente decepciona.

Dá para continuar um subagente que já terminou?

Dá. Subagente concluído mantém o histórico completo e pode ser retomado — basta pedir a continuação, e o Claude reabre o mesmo subagente com o contexto que ele já tinha, em vez de criar outro do zero.

Como garanto que um subagente específico seja usado?

Três níveis. Linguagem natural (use o agente revisor) deixa o Claude decidir. A menção @agent-revisor garante a execução. E claude --agent revisor usa o subagente como agente principal da sessão inteira.

Meu subagente não é invocado nunca. Por quê?

Quase sempre a description não bate com o jeito que você pede as coisas — é por ela que o Claude decide delegar. Deixe-a específica sobre quando usar, não só sobre o que o subagente faz. Se quiser garantia, use a menção direta.

• Anthropic — Claude Code Docs: Sub-agents. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Extend Claude with skills. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Orchestrate teams of Claude Code sessions. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: How Claude remembers your project. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Hooks reference. Acesso em 20/08/2026.

Verificado em 20 de agosto de 2026.

Gatilho de reavaliação: revisar quando (a) a precedência entre escopo de projeto e pessoal for alinhada entre skills e subagentes, (b) mudar a lista de ferramentas disponíveis para subagente em background, (c) Explore e Plan passarem a carregar o CLAUDE.md, ou (d) o comportamento de cache do fork mudar.