# Subagents no Claude Code: guia prático de uso

> Published 2026-10-11T13:57:10.210Z on https://www.crazystack.com.br/pt/p/subagents-no-claude-code-guia-pratico-de-uso/
> Source video: https://www.youtube.com/watch?v=LlijA6WDy9o

Subagents no Claude Code são instâncias auxiliares que recebem uma tarefa do agente principal, executam com contexto próprio e devolvem o resultado. Você pode invocá-los por linguagem natural, por menção direta com @ ou pelo terminal com Claude --agent. O ganho real está no isolamento de contexto, não no paralelismo massivo.

## O que são subagents no Claude Code

Subagents no [Claude Code](https://code.claude.com/docs/en/sub-agents), a ferramenta de codificação agêntica da [Anthropic](https://www.anthropic.com) que roda no terminal, são instâncias auxiliares criadas a partir do seu agente principal. Cada subagente recebe uma tarefa delimitada, executa com contexto, ferramentas e modelo próprios e devolve o resultado para o main agent revisar.

O ponto-chave é o que o subagente herda. Dependendo da configuração, ele pode receber parte das skills, MCPs e plugins da sessão, ou começar praticamente do zero. Ele não é uma cópia da conversa: isso é papel do comando /fork, que clona todo o contexto do main agent em um agente de background. O subagente nasce enxuto justamente para não carregar história desnecessária.

Na prática, o fluxo fica assim: você quebra uma tarefa grande em subtarefas, delega cada pedaço a um subagente e valida o output ao voltar para a sessão principal. O autor do vídeo relata ter rodado até 14 subagents em paralelo sem problemas, experiência primeira dele e não uma garantia oficial da Anthropic.

## Quais são as três formas de invocar um subagente

Existem três caminhos principais para fazer o Claude Code instanciar um subagente, e a escolha muda só o gatilho, não o resultado. Todos colocam o agente para rodar e devolvem o controle à sessão principal quando a tarefa termina.

1. **Linguagem natural.** Você simplesmente pede: "inicie um novo subagente que vai trocar a paleta de cores para pastel". Sem configuração prévia, o Claude Code costuma instanciar o agente de propósito geral pré-instalado, o General Purpose, que herda o mesmo modelo da conversa.

2. **Menção explícita com @.** Depois de criar um agente próprio, por exemplo um code-reviewer, você digita @ e o nome dele no prompt. Isso força a instância daquele agente específico, com o contexto e as permissões definidos no arquivo de configuração.

3. **Terminal direto.** Fora da sessão interativa, o comando `claude --agent code-reviewer` abre o Claude Code já rodando dentro daquele agente, com o contexto e as regras dele do início ao fim da sessão.

As três formas aceitam execução em background: você acompanha o que o subagente faz, entra na instância para inspecionar ou volta ao main agent e continua trabalhando enquanto a tarefa corre.

## Como criar e configurar seu próprio subagente

Você configura um subagente criando um arquivo Markdown dentro da pasta `.claude/agents`, seja no projeto seja no diretório global do usuário. Pode escrever o arquivo manualmente ou pedir para o próprio Claude Code gerá-lo; as duas maneiras produzem o mesmo resultado.

O arquivo combina um cabeçalho de metadados com um corpo de system prompt. Os campos que mais importam, segundo o autor, estão no cabeçalho, e não no prompt em si:

### Campos essenciais do arquivo

- **name e description**: identificam o agente e dizem quando ele deve ser usado.

- **model**: define qual modelo o subagente roda, possivelmente diferente do main agent.

- **tools**: restringe as ferramentas disponíveis por padrão, e **disallowedTools** bloqueia acesso explícito, inclusive à ferramenta de skills.

- **isolation**: permite rodar o subagente em uma [worktree](https://git-scm.com/docs/git-worktree) isolada, evitando conflito de arquivos com outros agentes.

### Memória, skills e background

O campo de memória aceita três escopos: user (aprendizados que atravessam projetos), project (aprendizados salvos na auto memory do projeto, que exige a funcionalidade ligada) e local (memória fora do versionamento no Git). Uma memória versionada no repositório é compartilhada com a equipe inteira; a local vale só para você.

Quanto às skills, o padrão é o subagente descobri-las sozinho pela ferramenta de skills quando precisar. Se preferir, pré-carrega no contexto apenas as relevantes, como as de revisão de código para um code-reviewer. O campo background controla se o agente roda em segundo plano, o que na prática faz sentido deixar habilitado. O autor considera max turns (limite de idas e vindas de tool call) dispensável na maioria dos casos.

## Modelos diferentes e modos de permissão fazem diferença

Para o autor, a maior vantagem prática de um subagente é rodar um modelo diferente do principal. Você mantém o main agent em um modelo mais capaz e caro para planejar e quebrar a tarefa, e delega subtarefas simples e bem descritas a um modelo menor, economizando tokens sem perder controle sobre o resultado.

O campo de modo de permissão, documentado na [página oficial de permissões](https://code.claude.com/docs/en/iam), controla o que o subagente pode fazer sem perguntar: o modo padrão, accept edits (autoaceita edições de arquivos), plan (só planeja) e bypass permissions (aceita tudo). A recomendação do vídeo é usar accept edits como padrão e reservar bypass permissions para ambientes isolados, como uma VM ou um dev container, porque rodar muitos agentes com permissão total na sua máquina real é convite a problemas.

## Quando delegar a um subagente e quando evitar

O critério do autor é simples: delegue quando a tarefa é pequena, bem definida e não precisa da história da conversa. O ganho real do subagente está no isolamento de contexto, não no paralelismo massivo, e abusar de agentes paralelos tende a fazer você prestar menos atenção no próprio trabalho.

| Cenário | Vale delegar a um subagente? |
| --- | --- |
| Subtarefa pequena com entry point e critério de aceitação claros | Sim, é o caso ideal |
| Code review independente do código que você escreveu | Sim, o agente chega sem viés de autoria |
| Vinte agentes rodando em paralelo o tempo todo | Não, o ganho é marginal e o risco cresce |
| Tarefa vaga, sem arquivos ou validação definidos | Não, o contexto isolado vira desvantagem |

Um dado interessante do teste do autor: configurar tudo com cuidado ou não configurar absolutamente nada e apenas pedir ao Claude Code produziu resultados bem parecidos. As configurações valem conhecer, mas não justificam engenharia excessiva. A ferramenta resolve organização, não promete ganhos expressivos de performance.

## Perguntas frequentes sobre subagents no Claude Code

- **Subagente e fork são a mesma coisa?** Não. O fork clona toda a conversa e o contexto do main agent em um agente de background. O subagente nasce com contexto reduzido ou próprio, definido na configuração, e existe para executar uma tarefa delimitada.

- **Preciso configurar arquivos para usar subagents?** Não. O Claude Code já traz o agente General Purpose pré-instalado, e basta pedir em linguagem natural. Os arquivos em .Claude/agents só entram quando você quer modelo, ferramentas, permissões ou memória específicos.

- **Vale rodar um modelo mais barato no subagente?** Sim, é um dos principais motivos para configurar um agente próprio. O main agent planeja com um modelo mais capaz e delega subtarefas simples a um modelo menor, economizando tokens.

- **Posso rodar vários subagents em paralelo?** Pode, desde que as tarefas sejam paralelizáveis e bem separadas. O autor chegou a 14 simultâneos sem problemas, mas recomenda moderação: o benefício está no isolamento, não em multiplicar agentes.

- **O subagente herda as skills da sessão?** Por padrão, ele pode descobrir e usar as skills disponíveis pela ferramenta de skills. Você pode pré-carregar apenas as relevantes no contexto ou bloquear o acesso com disallowedTools.

## Do vídeo ao artigo: registre o que você aprendeu

A lição central deste guia é que organizar contexto vale mais que acumular configuração. Se você também explica temas assim em vídeos, com demonstrações no terminal e opinião própria, esse conhecimento merece uma versão escrita que alguém encontre buscado por "subagents no Claude Code". O [Skala Blog](https://skalablog.com) faz exatamente essa ponte: você cola a URL do vídeo do YouTube, a ferramenta transcreve e gera um artigo estruturado, pronto para revisar e publicar.

Para quem prefere cursos guiados, o autor do vídeo mantém formações como o Crazystack Typescript e o Bootcamp do Dev Doido, do Gustavo Dev Doido, com conteúdo de desenvolvimento e IA na plataforma [Crazystack](https://crazystack.com.br).

[Source video](https://www.youtube.com/watch?v=LlijA6WDy9o)