Subagents no Claude Code: Guia Prático (2026)

por Jasmine, uma dev que usa Claude Code e subagents todo dia.

O que são subagents no Claude Code?

Um subagent é uma instância especializada do Claude que o agente principal pode disparar para lidar com uma tarefa específica, rodando na sua própria janela de contexto, com o seu próprio system prompt e o seu próprio conjunto de ferramentas, e depois devolvendo um resultado condensado para o agente principal. Em resumo: em vez de deixar um Claude carregar o trabalho inteiro dentro de uma única conversa, você divide o trabalho entre pequenos assistentes - cada um um agente de IA especializado em um único papel.

Imagine o agente principal como uma líder técnica. Quando chega um trabalho grande - digamos, "revise todo o código em busca de segurança" - a líder técnica não lê cada arquivo na própria cabeça. Ela repassa a um especialista em segurança, que lê, resume e traz o retorno. Um subagent é exatamente esse especialista: ele tem uma descrição da tarefa (o system prompt), recebe certas permissões (ferramentas) e, quando termina, devolve só a conclusão de que você realmente precisa.

A diferença central em relação a apenas digitar mais instruções na mesma sessão: os subagents do Claude Code têm um contexto isolado. Toda a informação intermediária que um subagent precisa ler para fazer o seu trabalho vive na "cabeça" dele e nunca transborda de volta para a sessão principal. Você declara cada subagent com um simples arquivo Markdown colocado no diretório .claude/agents/, e o Claude Code os detecta automaticamente.

Como os subagents funcionam? (isolamento de contexto)

O mecanismo por trás dos subagents se chama isolamento de contexto. Essa é a verdadeira razão de valer a pena usar subagents, e não só "subir mais uma IA para aparecer".

Uma execução típica é assim:

1. O agente principal pega o seu pedido e decide qual tarefa deve ser repassada a um subagent.
2. Ele dispara o subagent correspondente junto com uma descrição específica da tarefa.
3. O subagent roda na sua própria janela de contexto - um "sandbox cognitivo". Ele lê arquivos, executa comandos e raciocina sobre o problema, tudo no seu próprio espaço.
4. Ao terminar, o subagent devolve só um resultado condensado (um resumo, uma lista de bugs, um trecho de código), em vez de despejar o processo inteiro na sessão principal.

You
 └─► Main agent (main context, lean)
 ├─► subagent: test-runner ──► returns: 2 tests failing
 ├─► subagent: security-scan ──► returns: 1 SQLi vulnerability
 └─► subagent: style-checker ──► returns: 5 lint warnings
 (each subagent = its own context window)

Como um subagent "engole" o contexto pesado (ler dezenas de arquivos, logs longos) e só exala a essência, a sua sessão principal mantém um contexto limpo que dura mais. Isso é em parte economia de tokens (o contexto principal não incha) e em parte uma questão de qualidade: o agente principal não fica poluído por ruído intermediário, então o raciocínio dele continua mais afiado. O mecanismo e o escopo são descritos pela Anthropic na documentação oficial de Subagents do Claude Code (acessada em 08/2026).

Ajuda distinguir isso de abrir uma nova aba de chat na mão. Quando você conversa manualmente em várias sessões, é você quem fica copiando resultados de um lado para o outro - lento e fácil de esquecer alguma coisa. Com subagents, o agente principal orquestra o fluxo inteiro: ele decide o que repassar, para quem, e costura os resultados de volta automaticamente dentro de um único turno de trabalho. Você nunca precisa sair do terminal.

Uma coisa que as pessoas costumam entender errado: o isolamento de contexto não deixa o subagent "mais burro". Ele continua sendo a mesma linha de modelo que você escolheu, só que focado em exatamente uma tarefa, com exatamente as ferramentas de que precisa. Restringir o escopo geralmente melhora o resultado, não piora - como dar um trabalho claro a um especialista em vez de pedir a uma pessoa que faça dez coisas ao mesmo tempo.

Crie o seu primeiro subagent - o arquivo .claude/agents

Essa é a parte central de mão na massa. Há duas formas de criar um subagent: usar a interface /agents (recomendada da primeira vez) ou escrever o arquivo Markdown na mão. As duas produzem a mesma coisa - um arquivo em .claude/agents/.

Passo 1 - Abra o gerenciador de agentes

Dentro de uma sessão do Claude Code, digite:

/agents

A interface lista os seus agentes existentes e deixa você criar um novo, escolher um escopo, escolher um modelo e limitar ferramentas por um menu. Se você prefere controle direto, pode pular este passo e escrever o arquivo você mesma - o resultado é idêntico.

Passo 2 - Escolha um escopo: projeto ou usuário

Há dois lugares para colocar um arquivo de agente, e escolher o certo faz diferença:

• Nível de projeto - .claude/agents/ dentro da pasta do projeto. Vale só para este projeto e pode ser commitado no Git, para que o time inteiro compartilhe. Escolha isto para agentes específicos do projeto (por exemplo, uma revisora que entende as convenções do seu time).
• Nível de usuário - ~/.claude/agents/ no seu diretório home. Vale para todos os seus projetos. Escolha isto para agentes que você quer ter à mão em qualquer lugar (por exemplo, uma redatora de documentação geral).

Quando os nomes colidem, o agente de nível de projeto tem prioridade sobre o de nível de usuário.

Passo 3 - Escreva o arquivo do agente (um exemplo de verdade)

Crie o arquivo .claude/agents/code-reviewer.md com o conteúdo abaixo. O topo é o frontmatter YAML; o corpo é o system prompt do subagent:

---
name: code-reviewer
description: Review code for bugs, security, and maintainability. Use right after you write or change code.
tools: Read, Grep, Glob
model: sonnet
---

You are a senior-level code reviewer. Your job:
- Read the code that just changed (use Read/Grep/Glob, do NOT edit files).
- Find logic bugs, security holes, and hard-to-maintain spots.
- Rank findings by severity: critical / should-fix / suggestion.
- Return a short list with file paths and line numbers.
Do not run write commands, do not commit, do not change code.

Passo 4 - Verifique

Rode /agents de novo para confirmar que o code-reviewer aparece na lista. É isso - você acabou de construir o seu primeiro subagent. A partir de agora, sempre que você tiver acabado de mexer no código, o Claude pode chamá-lo automaticamente, ou você pode chamá-lo diretamente: "use o subagent code-reviewer para olhar o que eu acabei de mudar."

Os campos do frontmatter (name, description, tools, model)

O frontmatter decide como um subagent se comporta. São só quatro campos para lembrar:

Duas dicas que valem ouro: (1) Escreva uma description clara, com verbos e situações ("Use logo depois de..."), porque é isso que o Claude usa para chamar sozinho o agente certo na hora certa. (2) Para um agente somente leitura, limite as tools a Read, Grep, Glob - assim o subagent fica fisicamente impossibilitado de, por descuido, editar ou apagar um arquivo.

Chamando e gerenciando subagents

Há três formas de acionar um subagent:

1. Autodelegação - o Claude escolhe o subagent certo com base no campo description. Você só trabalha normalmente e, quando o contexto bate (por exemplo, logo depois de você terminar de editar código), o Claude repassa para o code-reviewer por conta própria.
2. Chamada direta - nomeie o agente no seu pedido: "use o subagent code-reviewer para checar o módulo de pagamentos." Esse é o caminho mais garantido quando você sabe exatamente do que precisa.
3. Gerencie pelo /agents - abra a interface para listar, editar ou apagar agentes; troque modelos, adicione ou remova ferramentas sem abrir arquivos na mão.

Se um subagent "nunca é chamado" mesmo quando você acha que deveria, o culpado é quase sempre uma description vaga demais. Reescrevê-la para ser específica resolve.

Rodando em paralelo e orquestrando vários subagents

É aqui que os subagents brilham de verdade, e é a parte que a maioria dos guias pula. Como cada subagent roda no seu próprio contexto, o agente principal pode abrir vários subagents de uma vez sobre a mesma base de código.

Exemplo: três subagents em paralelo

Digamos que você acabou de terminar uma funcionalidade e quer uma verificação completa antes de abrir um PR. Em vez de fazer sequencialmente, peça:

Run 3 subagents in parallel on the current branch:
- test-runner: run the full test suite, report which tests fail
- security-scanner: scan the code that just changed for vulnerabilities
- style-checker: check lint and conventions
Combine all three into a single report.

Os três agentes rodam de forma independente, cada um lendo o que precisa, e então o agente principal junta os três relatórios enxutos. Você economiza tempo e contexto.

No lado dos tokens, entenda o mecanismo antes de esperar "X por cento de economia". O que você economiza não é a contagem total de tokens - rodar três agentes ainda custa tokens para os três. O que você economiza são os tokens da sessão principal: cada log de teste, cada rastro de scan de segurança e cada aviso de lint fica dentro do contexto de cada subagent, e só algumas linhas de conclusão voltam. É isso que impede a sessão principal de encher cedo e te deixa manter uma linha de raciocínio mais longa. Esse é o benefício real - e não uma porcentagem fixa.

Orquestração em várias camadas

Um nível acima: a saída de um subagent vira a entrada do próximo. Um fluxo típico de explore -> plan -> implement:

1) subagent "explorer": survey the codebase, return a module map + spots to change.
2) Feed that result to subagent "planner": lay out a step-by-step plan.
3) Feed the plan to subagent "implementer": execute it step by step.

Esse é um padrão de orquestração poderoso, mas você precisa entender uma limitação importante por baixo dele.

A limitação que você precisa conhecer

Os subagents não compartilham contexto diretamente entre si e não "conversam" um com o outro. Eles só devolvem resultados ao agente principal, e é o agente principal que repassa a informação para o próximo subagent. Cada disparo é uma ida e volta de tokens. Então a orquestração em várias camadas tem poder real, mas também tem um custo - não abuse dela. Para entender exatamente como os subagents diferem de Skills/Hooks/MCP, leia o guia que compara Skills, Subagents, Hooks e MCP.

Alguns templates de subagent para usar já

Quatro templates de copiar e colar, ajuste levemente e vá:

1. Revisor somente leitura (absolutamente seguro)

---
name: safe-reviewer
description: Read-only code review that never edits files. Use to inspect before a merge.
tools: Read, Grep, Glob
model: sonnet
---
You only read and comment. Never run write commands. Return findings ranked by severity.

2. Test-runner

---
name: test-runner
description: Run the test suite and summarize failures. Use after editing code.
tools: Bash, Read, Grep
model: haiku
---
Run the project's tests, read the output, list failing tests with a short cause each.

3. Doc-writer

---
name: doc-writer
description: Write/update documentation and docstrings for new code.
tools: Read, Grep, Glob, Edit
model: sonnet
---
Read the code, write clear docs that match the repo's style. Do not change code logic.

4. Explorer

---
name: explorer
description: Survey an unfamiliar codebase, return an architecture map and entry points.
tools: Read, Grep, Glob
model: sonnet
---
Map out the modules, data flow, and the important files. Read only, never edit.

Repare nos quatro templates: todo agente que não precisa escrever não recebe permissão de escrita. Esse é um hábito seguro que vale manter.

Como os subagents diferem de Skills, Hooks e MCP?

Esses quatro blocos de construção se confundem bastante. Um jeito rápido de distingui-los:

Em resumo: subagents dividem o trabalho, Skills ensinam um procedimento, Hooks automatizam eventos e o MCP estende conexões. A comparação completa dos quatro blocos de construção vai mais fundo se você ainda estiver em dúvida sobre qual usar.

Erros comuns e limitações reais

Poucos blogs se dão ao trabalho de escrever esta seção, mas é exatamente ela que te ajuda a usar subagents do jeito certo:

• Delegar demais. Dividir uma tarefa minúscula (renomear uma variável, corrigir uma linha) em um subagent é contraproducente - a ida e volta de tokens e a latência custam mais do que simplesmente fazer você mesma. Subagents são para trabalho "de contexto pesado e resultado leve".
• Uma description vaga significa nenhuma chamada automática. Se a descrição é genérica, o Claude não sabe quando repassar. Escreva a situação específica de uso.
• Esquecer de limitar as tools. Uma revisora que só deveria ler, mas ganhou acesso de escrita, pode editar o arquivo errado. Sempre conceda as permissões mínimas.
• Queimar tokens abrindo agentes demais. Rodar 5-6 agentes em paralelo soa impressionante, mas cada um é a sua própria sessão cobrável. Abra-os com propósito.
• Quando NÃO dividir: quando uma tarefa precisa do contexto completo da conversa atual (por exemplo, você está depurando um fluxo longo em que cada detalhe anterior importa). Um subagent não enxerga o contexto principal, então dividir a tarefa perde justamente o contexto de que você precisa.

Pule a escrita - os 45 agentes prontos do AgentKit

Escrever um bom subagent dá trabalho, ajustando o prompt e testando várias vezes. Se você prefere ter uma biblioteca pronta de agentes especializados em vez de escrever do zero, os 45 agentes prontos do AgentKit são um atalho opcional. É um kit para Claude Code (não o AgentKit da OpenAI - só uma coincidência de nome), que traz 45 agentes = 17 de Engenharia + 28 de Marketing junto com mais de 108 skills. Se você quiser dar uma olhada no catálogo de agentes antes de decidir, leia a visão geral dos 45 agentes prontos do AgentKit. O Engineer Kit custa US$ 99 (o site não menciona cobrança recorrente). Dito isso, escrever alguns agentes que combinam com as convenções do seu próprio repositório ainda é uma habilidade fundamental que vale aprender - o kit só te ajuda a andar mais rápido.

Perguntas frequentes (FAQ)

Os subagents custam dinheiro extra?

Sim, indiretamente. Cada subagent é uma sessão com o seu próprio contexto, então gasta os próprios tokens; rodar vários em paralelo usa mais tokens do que uma única sessão. Em troca, como o contexto principal fica mais enxuto, a execução como um todo ainda pode ser eficiente para trabalho de contexto pesado.

Quantos subagents podem rodar em paralelo?

Você pode abrir vários subagents de uma vez, mas deve limitar à necessidade real (3-4 costuma ser razoável para uma tarefa de revisão). Quanto mais você abre, mais tokens queima e mais difícil fica acompanhar.

Um subagent lembra da conversa principal?

Não. Cada subagent roda em uma janela de contexto isolada e não enxerga o histórico da sessão principal, exceto aquilo que o agente principal repassa de propósito. Essa é a força dele (um contexto limpo), mas também uma limitação para ter em mente.

Como os subagents diferem dos Skills?

Subagents são sub-IAs especializadas que recebem trabalho e rodam de forma independente; Skills são instruções/procedimentos empacotados carregados para o Claude seguir. Um "faz o trabalho por você", o outro "ensina como fazer".

Devo colocar um agente no nível de projeto ou de usuário?

Coloque no nível de projeto (.claude/agents/) para agentes específicos de um projeto que você quer commitar para o time; coloque no nível de usuário (~/.claude/agents/) para agentes que você quer em todos os projetos. Quando os nomes colidem, o nível de projeto vence.

Eu preciso do Claude Code Pro?

Subagents são um recurso do Claude Code; você os usa dentro do plano que já tiver. Para detalhes de planos (Pro a US$ 20/mês, Max e por aí vai), veja o que é o Claude Code.

Conclusão e próximos passos

Subagents transformam o Claude Code de assistente solo em um pequeno time: dividem o trabalho, rodam em paralelo, mantêm o contexto limpo. Comece simples com um code-reviewer somente leitura e depois avance para a orquestração assim que entender tanto o poder quanto os limites. Leia a seguir o que são os Skills do Claude Code para casar subagents com skills, ou a comparação dos quatro blocos de construção para escolher a ferramenta certa. E se você prefere não escrever do zero, experimente o bundle do AgentKit — agora US$ 149 (de US$ 198) com a sua biblioteca de agentes prontos.