Subagentes no Claude Code: como criar e quando usar

Pra criar um subagente no Claude Code, salve um arquivo Markdown em .claude/agents/ (ou ~/.claude/agents/ pra todos os projetos) com frontmatter YAML com name e description, e escreva o system prompt no corpo. Restrinja tools e escolha um model mais barato quando der. Use subagente pra tarefa autocontida que gera muita saída, como rodar testes ou ler log: ela roda em contexto próprio e só o resumo volta pra conversa principal.

Este guia mostra o arquivo de um subagente que roda testes, onde salvar, como validar o YAML antes de abrir uma sessão e os três jeitos de chamar. No fim, uma tabela de quando delegar e quando não. Tudo segue a documentação oficial de subagentes, e o arquivo e a validação foram rodados no Claude Code 2.1.300.

O que é um subagente no Claude Code?

É um assistente separado que roda dentro da sua sessão com janela de contexto própria, system prompt próprio e permissões próprias. Ele não vê o histórico da conversa principal: recebe só a mensagem de tarefa que o Claude escreve ao delegar, faz o trabalho e devolve um resumo.

O Claude Code já vem com alguns prontos. O Explore e o Plan são só leitura (Write e Edit negados) e servem pra buscar e entender código. O general-purpose lê e edita. Os seus entram do lado desses.

Como criar um subagente?

Um subagente é um arquivo Markdown com frontmatter YAML. O frontmatter configura, o corpo vira o system prompt. Crie .claude/agents/test-runner.md na raiz do projeto:

---
name: test-runner
description: Roda a suíte de testes e devolve só as falhas. Use proativamente depois de editar código.
tools: Read, Grep, Glob, Bash
model: haiku
---

Você roda testes e resume o resultado.

Quando for chamado:
1. Descubra o comando de teste do projeto (package.json, pyproject.toml ou Makefile).
2. Rode a suíte inteira uma vez.
3. Devolva só os testes que falharam: nome, arquivo e mensagem de erro.

Não edite arquivos. Se tudo passar, responda com o total de testes.

Só name e description são obrigatórios. Os campos que mais importam:

Escreva a description curta e específica. Todas as descriptions ocupam contexto da conversa principal, e o Claude Code avisa na inicialização quando a soma passa de 15.000 tokens. Detalhe vai no corpo, que só carrega quando o subagente roda. Pra estimular a delegação automática, a documentação sugere frases como "use proativamente".

Onde salvar o arquivo do subagente?

O lugar define quem enxerga o subagente. Quando dois têm o mesmo name, vence o de prioridade maior:

Pra testar sem criar arquivo, passe o subagente em JSON. Ele existe só naquela sessão:

claude --agents '{
  "test-runner": {
    "description": "Roda os testes e devolve só as falhas.",
    "prompt": "Você roda testes e resume o resultado. Não edite arquivos.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "haiku"
  }
}'

Uma pegadinha: o Claude Code recarrega sozinho quando você edita um arquivo de subagente, mas só observa pastas que já existiam quando a sessão abriu. Se .claude/agents/ acabou de ser criada, reinicie a sessão.

Como validar o subagente antes de usar?

Frontmatter quebrado não dá erro na sessão: o arquivo simplesmente não carrega. Rode o validador apontando pra pasta. Ele funciona sem login:

$ claude plugin validate .claude/agents
Validating components in: /home/voce/projeto/.claude/agents

✔ Validation passed

E com uma aspa sem fechar na description, o mesmo comando sai com código 1:

---
name: quebrado
description: "aspas sem fechar
---

$ claude plugin validate .claude/agents
Validating agent: .../.claude/agents/quebrado.md

✘ Found 1 error:

  ❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected EOF. At runtime this agent does not load at all — with no frontmatter name it is treated as a co-located reference document and skipped.

✘ Validation failed

O validador não reclama de arquivo sem name, que também é ignorado. Confira os dois campos obrigatórios no olho.

Como chamar um subagente?

São três jeitos, do mais solto ao mais forte:

# 1. Linguagem natural: o Claude decide se delega
Use o subagente test-runner pra rodar os testes

# 2. @-menção: garante que esse subagente roda
@"test-runner (agent)" roda os testes do módulo de auth

# 3. Sessão inteira como o subagente
claude --agent test-runner

Com a @-menção, sua mensagem inteira ainda vai pro Claude, que escreve o prompt da tarefa. A menção escolhe qual subagente roda, não o texto que ele recebe. Com --agent, o system prompt do subagente substitui o do Claude Code na sessão toda.

Quando usar subagente e quando não usar?

A regra da documentação: delegue o que é autocontido e gera muita saída que você não vai reler.

Subagente não é de graça. As requisições dele contam no mesmo limite de uso da conversa principal, e um subagente comum não reaproveita o prompt cache dela. Por isso o exemplo usa model: haiku. O que muda pra conta está em como economizar tokens no Claude Code.

Como restringir o que um subagente pode fazer?

• tools é lista de permissão; disallowedTools é lista de bloqueio. Com os dois, o bloqueio é aplicado primeiro.
• disallowedTools: Bash(git push *) tira o Bash inteiro, não só o push. Pra bloquear um comando e manter o Bash, use permissions.deny no settings, que vale pra conversa principal e pros subagentes.
• Pra impedir o Claude de usar um subagente, negue Agent(nome).
• Regra condicional (só SELECT no banco, por exemplo) vai num hook PreToolUse no frontmatter do subagente. O formato é o mesmo dos hooks do Claude Code.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Bash(git push *)"]
  }
}

Dois limites que valem saber: um subagente pode criar outros até três níveis abaixo da conversa principal (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH muda isso), e com 20 rodando ao mesmo tempo o próximo falha com Concurrent subagent limit reached.

O que foi testado aqui

• claude plugin validate no Claude Code 2.1.300, sem login: o test-runner.md passou e o arquivo com aspa aberta falhou com a mensagem acima.
• Não testado: a delegação numa sessão logada. O comportamento descrito nas seções de chamada e restrição vem da documentação oficial.

Perguntas frequentes

Leia também

• Claude Code é um harness, o guia principal de Claude Code
• Como economizar tokens no Claude Code
• Como criar uma Skill no Claude Code
• Como configurar hooks no Claude Code
• Como configurar MCP no Claude Code

Quer colocar agentes de IA pra trabalhar no fluxo do seu time? Fale com a Capiva.