# Subagentes do Claude Code: como criar e usar

URL: https://agentvera.dev/pt/blog/claude-code-subagents/ · Publicado: 2026-10-23

O que são os subagentes do Claude Code, como escrever um em .claude/agents, o que fazem os campos tools e model e quando agentes paralelos separados são a melhor opção.

**Resumo:**

- Um subagente roda na própria janela de contexto, com seu próprio prompt, ferramentas e modelo, e só a resposta final volta para a conversa principal.
- Subagentes são arquivos Markdown em .claude/agents/ em que só name e description são obrigatórios; sem tools, o subagente recebe todas as ferramentas da sessão principal.
- Subagentes servem para tarefas curtas como busca e revisão, enquanto agentes paralelos separados servem para features e tarefas longas que terminam em uma branch própria.

Os subagentes do Claude Code são ajudantes para os quais a sessão principal do Claude Code entrega uma única tarefa. Cada um roda na própria janela de contexto, com seu próprio system prompt, lista de ferramentas e modelo, e só a resposta final volta para a conversa principal. Você define um subagente como um arquivo Markdown em `.claude/agents/`, e o Claude o usa automaticamente quando a tarefa combina com a descrição dele, ou quando você pede por ele pelo nome.

Este post explica como os subagentes funcionam, o formato do arquivo, os campos `tools` e `model`, como chamá-los e a fronteira entre um subagente e um agente separado rodando ao lado do primeiro. Os fatos vêm da [documentação oficial de subagentes](https://code.claude.com/docs/en/sub-agents "Documentação de subagentes do Claude Code"). Para a versão em um parágrafo, veja o [verbete de subagente no glossário](/pt/glossary/subagent/ "Subagente").

## Como os subagentes funcionam

Quando o Claude decide delegar, ele chama a ferramenta Agent (chamada Task antes da versão 2.1.63) com um briefing curto. O subagente começa com um contexto novo. Ele recebe o próprio system prompt, a mensagem de delegação, o seu `CLAUDE.md`, o git status e quaisquer skills que você pré-carregou para ele. Ele não vê o histórico da conversa principal.

Em seguida, ele trabalha na tarefa com as ferramentas permitidas e devolve um único resultado. Tudo o que ele leu pelo caminho, como dezenas de arquivos, saídas longas de grep ou logs de testes, fica no contexto dele. Esse é o principal motivo para usar subagentes: a conversa principal recebe um resumo, não o ruído.

Alguns limites que vale conhecer:

- Subagentes podem iniciar seus próprios subagentes, até três níveis de profundidade por padrão.
- Até 20 podem rodar ao mesmo tempo por padrão.
- As solicitações deles contam para os mesmos limites de uso da sessão principal.
- Um subagente pode rodar em primeiro plano, enquanto o agente principal espera, ou em segundo plano enquanto o agente principal segue trabalhando.

## Subagentes embutidos

O Claude Code vem com alguns subagentes que você pode usar sem escrever nada:

| Subagente | Ferramentas | Uso típico |
| --- | --- | --- |
| Explore | Somente leitura | Buscar e ler pela base de código, com profundidade quick, medium ou very thorough |
| Plan | Somente leitura | Pesquisa durante o modo plan |
| General-purpose | Todas as ferramentas | Tarefas de várias etapas que precisam de pesquisa e de mudanças |

O Explore é o que você mais vai ver. Quando o Claude precisa descobrir onde algo está definido ou como uma feature funciona entre vários arquivos, ele costuma passar isso para o Explore, para que os despejos de arquivos não caiam no seu contexto principal.

## Onde ficam os arquivos de subagentes

Subagentes são arquivos Markdown com frontmatter YAML. O Claude Code os carrega de vários lugares e, quando dois têm o mesmo nome, vence o que está mais acima nesta lista:

| Local | Escopo |
| --- | --- |
| Configurações gerenciadas | Toda a organização, definido pelos administradores |
| Flag `--agents` (JSON) | Uma sessão |
| `.claude/agents/` | Um projeto, compartilhado pelo git |
| `~/.claude/agents/` | Todos os seus projetos |
| Pasta `agents/` de um plugin | Onde o plugin estiver instalado |

Os subagentes de projeto em `.claude/agents/` são os que você deve commitar, para que a equipe inteira compartilhe o mesmo revisor ou executor de testes.

## O formato do arquivo de subagente

Só `name` e `description` são obrigatórios. O corpo depois do frontmatter é o system prompt do subagente.

```markdown
---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When called:

1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.

Do not edit files. Report only.
```

A `description` importa mais do que parece. É o que o Claude lê quando decide se vai delegar, então diga o que o subagente faz e quando usá-lo. Frases como “use after writing code” (use depois de escrever código) ajudam o Claude a escolhê-lo por conta própria.

### O campo tools

`tools` é uma lista de permissões. Com `tools: Read, Grep, Glob, Bash`, o revisor acima consegue ler e rodar comandos, mas não consegue editar arquivos. Se você deixar `tools` de fora, o subagente herda todas as ferramentas da sessão principal, incluindo as ferramentas MCP. Também existe `disallowedTools`, para quando é mais fácil dizer o que remover do que o que manter.

Mantenha a lista tão curta quanto o trabalho permitir. Um revisor não precisa de Edit. Um pesquisador não precisa de Bash. Menos ferramentas significa menos surpresas e uma tarefa mais clara.

### O campo model

`model` aceita um alias (`sonnet`, `opus`, `haiku`), um ID de modelo completo ou `inherit` para usar o modelo da sessão principal. Quando o subagente é chamado, o Claude Code escolhe o modelo nesta ordem: um modelo passado naquela chamada, depois o campo `model` do arquivo, depois a variável de ambiente `CLAUDE_CODE_SUBAGENT_MODEL` e, por fim, o modelo da sessão principal.

É aqui que os subagentes podem economizar dinheiro de verdade. Buscas amplas em arquivos e leitura de logs raramente precisam do modelo mais forte. Coloque-as no Haiku e mantenha a sessão principal no modelo maior para as decisões. O post sobre uso de tokens do Claude Code traz mais formas de cortar gastos.

### Outros campos úteis

| Campo | O que faz |
| --- | --- |
| `permissionMode` | Modo de permissão do subagente, por exemplo plan ou acceptEdits |
| `skills` | Skills a carregar no contexto do subagente ao iniciar |
| `mcpServers` | Servidores MCP que o subagente pode usar |
| `hooks` | Hooks que valem enquanto este subagente roda |
| `memory` | Memória persistente no escopo de usuário, projeto ou local |
| `maxTurns` | Limite máximo de turnos do subagente |
| `background` | Rodar em segundo plano por padrão |
| `isolation: worktree` | Rodar em uma git worktree temporária |
| `effort` | Esforço de raciocínio do subagente |

## Como chamar um subagente

Há três formas:

1. **Deixe o Claude decidir.** Se o pedido combina com a descrição de um subagente, o Claude delega por conta própria.
2. **Peça pelo nome.** “Use the code-reviewer subagent to check my last commit.” (use o subagente code-reviewer para checar meu último commit). Você também pode mencioná-lo com @ pelo menu.
3. **Rode uma sessão inteira como ele.** `claude --agent code-reviewer` inicia uma sessão que usa o prompt, as ferramentas e o modelo desse subagente.

Para uma sessão avulsa, você pode passar subagentes como JSON sem criar arquivos:

```bash
claude --agents '{
  "code-reviewer": {
    "description": "Reviews code changes. Use after edits.",
    "prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
```

Para impedir o Claude de usar um subagente específico, adicione-o à lista de negação nas suas permissões, por exemplo `Agent(Explore)`.

## Subagentes vs agentes paralelos separados

Subagentes e agentes paralelos dividem o trabalho, mas resolvem problemas diferentes.

| | Subagentes | Agentes paralelos separados |
| --- | --- | --- |
| Quem os inicia | A sessão principal do Claude | Você |
| O que você vê | O resultado final, dentro do chat principal | A sessão completa de cada agente |
| Contexto | Novo a cada tarefa, descartado depois | De longa duração, um por agente |
| Arquivos | A mesma pasta de trabalho, a menos que haja `isolation: worktree` | Geralmente uma git worktree para cada |
| Sua participação no meio da tarefa | Nenhuma, o agente principal conversa com ele | Você pode guiar cada um |
| Bom para | Busca, revisão, pesquisa, tarefas curtas e focadas | Features, refatorações, tarefas longas que terminam em uma branch |

Use um subagente quando o agente principal precisa de uma resposta para continuar: “encontre todos os chamadores desta função”, “revise este diff”, “resuma estes logs”. O trabalho é curto, o resultado é o que importa e você não precisa acompanhar.

Use agentes separados quando cada parte é um trabalho de verdade por si só: uma feature, uma migração, uma suíte de testes. Você quer ver o que cada um está fazendo, responder às perguntas dele e revisar as mudanças como uma branch. Esse é o setup descrito em [agentes de código em paralelo](/pt/blog/parallel-coding-agents/ "Agentes de código em paralelo") e em [rodar vários agentes do Claude Code](/pt/blog/run-multiple-claude-code-agents/ "Rodar vários agentes do Claude Code"), com cada agente na sua própria [git worktree](/pt/blog/git-worktree-parallel-agents/ "Git worktree para agentes paralelos").

Os dois combinam bem. Um agente separado ainda pode usar subagentes para as próprias buscas e revisões. Um bom padrão é agentes separados para o trabalho que você daria a uma pessoa, e subagentes para as tarefinhas que esses agentes executam. Para equipes maiores, o post sobre equipes de agentes de IA cobre papéis e passagens de tarefa, e o verbete de orquestração multiagente cobre a ideia geral.

O Claude Code também tem um recurso separado chamado agent teams, em que várias sessões do Claude trabalham juntas. Isso não é o mesmo que subagentes e fica fora deste post.

## Dicas para subagentes que funcionam

- **Uma tarefa por subagente.** “Revisor” e “executor de testes” funcionam melhor que “ajudante”.
- **Escreva a descrição para o Claude.** Diga quando usá-lo, não só o que ele é.
- **Limite as ferramentas.** Subagentes somente leitura para pesquisa e revisão, ferramentas de edição só onde for preciso.
- **Escolha o modelo de propósito.** Haiku para busca e resumos, um modelo mais forte para design e correções difíceis.
- **Peça um relatório curto.** O resultado vai para o contexto principal, então diga ao subagente para devolver conclusões, não despejos de arquivos.
- **Versione os subagentes do projeto.** `.claude/agents/` no git significa que todo mundo recebe os mesmos ajudantes.

## Como o AgentVera mostra os subagentes

O AgentVera é um app desktop para rodar vários agentes de código, como Claude Code, Codex e outros, lado a lado. Ele lida com subagentes de duas formas.

**Você consegue vê-los.** No painel de um agente Claude Code, o botão “Subagents” abre uma visão ao vivo dos subagentes que esse agente iniciou e do que eles estão fazendo agora. Cada um mostra seu status (Running, Done, Error, Stopped), se roda “in background”, a “Assigned task” que recebeu e seu “Report”. Enquanto alguns estão trabalhando, aparece uma linha “{count} subagents running — show” para você não perdê-los de vista. O [tour do projeto e mapa de código](/pt/features/project-tour-and-code-map/ "Tour do projeto e mapa de código") também tem uma linha do tempo de subagentes com tipo, status, número de ferramentas e duração. Ambos leem as transcrições locais e, por enquanto, são para agentes Claude Code.

**Um Explore mais barato.** Em Settings → “Token saving”, a opção “Explorer subagent” dá aos agentes Claude um explorador somente leitura para buscas amplas. A varredura de arquivos roda em um modelo mais barato, o Haiku por padrão, e só o resultado volta para a conversa principal. Se você já tem seu próprio arquivo de subagente Explore, o AgentVera mantém o seu. Ela fica ao lado das smart tools na mesma seção.

**Agentes separados quando o trabalho é maior.** A [visão de equipe](/pt/features/team-view/ "Visão de equipe") mostra até 24 agentes ao mesmo tempo. A [equipe paralela](/pt/features/parallel-team/ "Equipe paralela") (planos Pro e Team) divide um objetivo em partes, roda cada uma na própria worktree e as junta em um único PR. As mensagens entre agentes permitem que eles façam perguntas uns aos outros, até entre CLIs diferentes, e a coordenação de agentes avisa quando dois agentes mexem no mesmo arquivo. Isso dá a você o lado de agentes separados da tabela acima, com os subagentes ainda disponíveis dentro de cada agente Claude.

## Conclusão

Subagentes são a ferramenta certa quando o agente principal precisa de uma resposta e você não precisa acompanhar o trabalho: busca, revisão, pesquisa. Escreva um arquivo Markdown com uma descrição clara, uma lista curta de ferramentas e um modelo escolhido de propósito. Quando o trabalho for grande o bastante para merecer uma branch própria e a sua atenção, rode um agente separado.

Leia mais:

- [Subagente (glossário)](/pt/glossary/subagent/ "Subagente")
- [Agentes de código em paralelo](/pt/blog/parallel-coding-agents/ "Agentes de código em paralelo")
- [Tour do projeto e mapa de código](/pt/features/project-tour-and-code-map/ "Tour do projeto e mapa de código")
- [Equipe paralela](/pt/features/parallel-team/ "Equipe paralela")
- [Agente Claude Code](/pt/agents/claude-code/ "Claude Code no AgentVera")

Para experimentar o AgentVera, comece pela [página inicial](/pt/ "AgentVera").

## Perguntas frequentes

**O que é um subagente no Claude Code?** Um subagente é um ajudante que a sessão principal do Claude Code inicia para uma tarefa. Ele roda na própria janela de contexto, com seu próprio system prompt, ferramentas e modelo, e só o resultado final volta para a conversa principal.

**Como crio um subagente do Claude Code?** Adicione um arquivo Markdown em .claude/agents/ no seu projeto, ou em ~/.claude/agents/ para todos os projetos. O frontmatter YAML precisa de name e description; o corpo é o system prompt. Campos opcionais incluem tools, model, permissionMode e isolation.

**Qual modelo um subagente usa?** O campo model aceita um alias como sonnet, opus ou haiku, um ID de modelo completo ou inherit. Se não estiver definido, o subagente usa o modelo da sessão principal, a menos que a variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL diga outra coisa.

**Subagentes economizam tokens?** Eles mantêm o contexto principal limpo, porque leituras de arquivos e resultados de busca ficam no subagente. Mas não tornam o trabalho gratuito: as solicitações dos subagentes contam para os mesmos limites de uso, então mandar buscas amplas para um modelo mais barato como o Haiku é o que mais economiza.

**Quando devo usar agentes separados em vez de subagentes?** Quando as tarefas são longas, editam muitos arquivos, precisam da sua revisão no caminho ou devem terminar como branches separadas. Agentes separados, cada um na sua git worktree, dão isso; subagentes servem para tarefas curtas e focadas cujo resultado o agente principal precisa.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/