Subagents no Claude Code: guia prático de uso

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, a ferramenta de codificação agêntica da Anthropic 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 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, 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 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.

Source video