O que são subagentes no Claude Code?
Subagentes no Claude Code são assistentes especializados para quem a conversa principal delega uma tarefa. Cada um trabalha com contexto próprio, instruções próprias e um conjunto definido de ferramentas, e devolve só o resultado. Assim a conversa principal fica limpa e várias tarefas independentes podem andar em paralelo.
Pense na conversa principal como um coordenador. Em vez de ler sozinho dezenas de arquivos para responder uma pergunta, ele entrega essa investigação a um subagente, que faz a busca, filtra o que importa e volta com um resumo. Os detalhes da investigação ficam no contexto do subagente, sem lotar a conversa onde você está trabalhando.
A documentação oficial da Anthropic descreve o recurso em https://code.claude.com/docs/en/sub-agents. Na prática, ele serve para três coisas: manter a conversa principal enxuta, dar a uma tarefa instruções especializadas e restringir o que cada assistente pode fazer, como permitir que um revisor leia arquivos sem poder alterá-los. Os três benefícios aparecem com mais clareza em projetos grandes, com muitos arquivos e tarefas paralelas.
- Contexto próprio: o subagente não carrega toda a conversa principal.
- Instruções próprias: cada um tem um papel definido, como revisor ou investigador.
- Ferramentas limitadas: você decide se ele pode ler, editar ou executar comandos.
- Retorno resumido: a conversa principal recebe a conclusão, não todo o caminho.
Como os subagentes funcionam por baixo dos panos
Quando você faz um pedido, o Claude Code pode decidir delegar com base na descrição de cada subagente disponível, ou você pode pedir explicitamente que um especialista assuma a tarefa. O subagente recebe a instrução, trabalha no próprio contexto com as ferramentas permitidas e, ao terminar, devolve um relatório para a conversa principal.
Tarefas independentes podem rodar ao mesmo tempo. Investigar como o cadastro de clientes está estruturado e analisar as regras de atendimento, por exemplo, não dependem uma da outra. Já tarefas encadeadas, em que a segunda precisa do resultado da primeira, devem seguir em sequência. Quem reúne as conclusões e decide o próximo passo continua sendo a conversa principal.
- Delegação automática: acontece quando a descrição do subagente combina com a tarefa.
- Delegação explícita: você pede pelo nome que um subagente assuma o trabalho.
- Paralelo: tarefas independentes rodam ao mesmo tempo.
- Sequência: tarefas que dependem uma da outra rodam em ordem.
- Síntese: a conversa principal reconcilia os relatórios antes de alterar o projeto.
Passo a passo para criar um subagente
O caminho mais simples é usar o comando /agents dentro do Claude Code, que abre a criação e a gestão de subagentes. Você também pode pedir ao próprio Claude Code que crie um para você. O subagente fica salvo como um arquivo de texto com um cabeçalho de configuração e as instruções logo abaixo.
Subagentes de projeto ficam na pasta .claude/agents/ do repositório e podem ser compartilhados com quem trabalha no mesmo projeto. Subagentes pessoais ficam na pasta de configuração do seu usuário e valem para todos os seus projetos. O campo mais importante é a descrição, porque é por ela que o Claude Code decide quando delegar.
- 1. Abra o Claude Code no projeto e rode o comando /agents.
- 2. Escolha se o subagente é do projeto (.claude/agents/) ou pessoal.
- 3. Escreva um nome e uma descrição clara de quando ele deve ser usado.
- 4. Libere só as ferramentas necessárias, como leitura sem edição para um revisor.
- 5. Teste com uma pergunta verificável e confira se o relatório aponta arquivos e evidências.
Subagente, conversa principal ou skill: qual usar
Subagentes não são a resposta para tudo. Muitas vezes a própria conversa principal resolve mais rápido, e em outros casos uma skill, que é um pacote de instruções que o Claude carrega quando a tarefa pede, é o recurso certo. Comparar os três nos mesmos critérios ajuda a escolher. A comparação abaixo resume quando cada um faz mais sentido.
A regra geral: se a tarefa é curta e você precisa acompanhar cada passo, fique na conversa principal. Se você repete sempre o mesmo procedimento, transforme em skill. Se a tarefa gera muito material intermediário ou pode rodar em paralelo com outras, delegue a um subagente. Na dúvida, comece pela conversa principal e delegue só quando o contexto começar a pesar.
- Tarefa curta e interativa — conversa principal: ideal; subagente: coordenação desnecessária.
- Investigação que lê muitos arquivos — conversa principal: enche o contexto; subagente: devolve só o resumo.
- Procedimento repetido sempre igual — skill: instruções reutilizáveis; subagente: útil se também precisar de contexto separado.
- Restrição de ferramentas — subagente: permite limitar o que ele pode fazer; conversa principal: usa as permissões da sessão.
- Várias frentes ao mesmo tempo — subagentes em paralelo; conversa principal: faz uma de cada vez.
Exemplo prático: delegação numa automação de WhatsApp
Imagine um projeto de atendimento no WhatsApp em que o agente precisa consultar o cadastro do cliente antes de responder, mas ainda não está claro quais informações existem. Um pedido possível ao Claude Code seria: delegue a um subagente a leitura do cadastro e a outro a análise das regras de atendimento, peça evidências e não altere arquivos.
O primeiro relatório deve listar os campos existentes; o segundo, quais dúvidas admitem resposta automática e quais exigem uma pessoa. Com os dois em mãos, você confere se cada informação que o atendimento precisa existe no cadastro e só então pede a implementação, prevendo também o caso de cliente não encontrado.
Repare que a delegação aqui não substitui a decisão: os subagentes levantam fatos, e a conversa principal, junto com você, decide o que construir. Esse padrão de investigar em paralelo, conferir e só então implementar serve para qualquer automação de negócio, de um painel de vendas a uma integração com CRM, e reduz o risco de construir em cima de uma suposição errada.
- Subagente 1: mapear os campos do cadastro, com o arquivo de origem.
- Subagente 2: classificar dúvidas em automáticas e com encaminhamento humano.
- Conversa principal: cruzar os relatórios e apontar lacunas.
- Implementação: só depois da conferência, incluindo o caso de cliente não encontrado.
Erros comuns ao usar subagentes
O erro mais caro é delegar tudo. Cada subagente começa do zero, precisa ler de novo o que for relevante e consome uso da sua conta. Dividir uma tarefa simples em três subagentes costuma sair mais lento e mais caro do que resolver direto na conversa principal. Em projetos pequenos, essa conta raramente fecha a favor da delegação.
Outro erro é aceitar o relatório sem conferir. Um subagente pode concluir que algo foi feito ou que um arquivo não existe com base numa busca incompleta. Peça sempre evidência, como o caminho do arquivo e o trecho encontrado, e evite colocar dois subagentes para editar o mesmo trecho ao mesmo tempo.
- Delegar tarefas simples que a conversa principal resolveria mais rápido.
- Escrever descrições vagas, que fazem o subagente ser chamado na hora errada.
- Liberar ferramentas de edição para quem só deveria ler.
- Aceitar conclusões sem evidência, como arquivo e trecho encontrados.
- Colocar dois subagentes editando o mesmo arquivo em paralelo.
Team Agents no Claude Code Para Produzir 5x Mais!
Na ZX LAB, usamos o Claude Code todos os dias e delegamos a subagentes tarefas como varrer arquivos, investigar integrações e revisar código antes de uma mudança ir ao ar. A lição prática é que delegar não dispensa conferir: um relatório bem escrito não prova que a ação foi feita. Rafael Castro, fundador da ZX LAB, ensina esse uso aos mais de 15 mil alunos da escola.