Monte seu primeiro time de subagentes no Claude Code

Se você usa IA pedindo uma coisa de cada vez, esperando, conferindo e pedindo a próxima, o gargalo continua sendo você. Este guia mostra como sair desse modelo e montar um time: um agente principal (o maestro) que delega pra especialistas.

1. O conceito

Uma conversa única com IA carrega um contexto só. Quanto mais coisa você joga nela, mais lotado esse contexto fica, e o agente vai ficando lento e confuso.

A saída é orquestração: em vez de um assistente que faz tudo, você tem um agente principal que recebe o pedido e despacha pra subagentes especializados. Cada subagente trabalha com contexto limpo e uma função única. No final, o principal junta tudo e te devolve o trabalho pronto.

2. O que é um subagente no Claude Code

Subagente é recurso nativo do Claude Code, não precisa programar nada. É um arquivo markdown que vive na pasta .claude/agents/ do seu projeto, com três coisas:

• name: o nome do subagente
• description: QUANDO ele deve ser usado (essa descrição é o gatilho)
• corpo: as instruções de sistema dele, o papel que ele cumpre

O Claude principal lê essas descrições e invoca o subagente certo sozinho quando a tarefa casa. Cada subagente roda com contexto próprio, separado do resto.

3. Passo a passo: seu primeiro time

Crie a pasta no seu projeto:

mkdir -p .claude/agents

Agora crie 3 arquivos dentro dela. O esqueleto é sempre o mesmo:

.claude/agents/pesquisador.md

---
name: pesquisador
description: Use quando a tarefa exigir levantar informações, comparar opções ou reunir dados antes de produzir qualquer coisa.
---

Você é um pesquisador. Sua única função é levantar informações
confiáveis sobre o tema pedido e entregar um resumo organizado
com os pontos principais. Você não escreve o texto final,
só entrega a matéria-prima.

.claude/agents/redator.md

---
name: redator
description: Use quando a tarefa for escrever um texto, e-mail, post ou documento a partir de um briefing ou de uma pesquisa pronta.
---

Você é um redator. Sua única função é transformar o material
recebido em texto claro e direto, no tom pedido. Você não
pesquisa e não revisa, só escreve.

.claude/agents/revisor.md

---
name: revisor
description: Use quando um texto pronto precisar de revisão de erros, clareza e consistência antes de ser entregue.
---

Você é um revisor. Sua única função é apontar e corrigir erros
de português, frases confusas e inconsistências no texto
recebido. Você devolve a versão final limpa.

4. Como pedir

Aqui está o pulo do gato: não converse com cada subagente. Faça UM pedido composto ao Claude e deixe ele despachar:

Pesquisa as 5 principais objeções de clientes sobre [seu produto],
escreve um e-mail de resposta pra cada uma e revisa tudo
antes de me entregar.

O agente principal aciona o pesquisador, passa o resultado pro redator, manda pro revisor e te devolve o pacote pronto. Como um gerente de verdade faria.

5. Regras de ouro

1. Função única por subagente. Um faz uma coisa. Se você quer que ele faça duas, são dois subagentes.
2. A descrição diz QUANDO usar. É ela que dispara a delegação, então capriche: descreva a situação, não só o cargo.
3. Comece com 3 e cresça. Pesquisador, redator e revisor cobrem muita coisa. Só adicione especialista novo quando sentir falta.

6. Aviso honesto

Subagente não faz milagre com pedido vago. Se você pedir "escreve um texto bom", o time inteiro vai produzir coisa genérica. O contexto do seu negócio (público, tom, oferta, exemplos) continua sendo obrigação sua. Time bom com briefing ruim entrega trabalho ruim, só que mais rápido.

Crédito

Subagentes são um recurso nativo do Claude Code, criado pela Anthropic. A documentação oficial está em docs.anthropic.com.