Imagine que você é um empreiteiro geral tocando uma obra. Você não assenta cada tijolo: chama o eletricista, o encanador, o pintor — cada um faz a parte dele e te entrega o serviço pronto. No Claude Code funciona igual. Você conversa com o maestro (o chat principal). Quando aparece um trabalho pesado, o maestro dispara subagentes: especialistas que fazem o serviço numa janela separada e devolvem só o resumo. Esse é o desenho que você precisa gravar.
↑ O fluxo do subagente: um dispara, muitos trabalham em paralelo, um resumo volta.
Conteúdo detalhado
🎼 O maestro e o especialista
O chat com que você conversa é o orquestrador — o maestro. Ele entende o pedido, decide o que precisa ser feito e, quando a tarefa é grande, delega a um especialista. Você nunca para de falar com o maestro: ele é o seu ponto de contato do início ao fim.
🏗️ A analogia do empreiteiro geral
O empreiteiro geral não assenta tijolo, não passa fio, não pinta parede. Ele coordena. Cada especialista chega, faz a parte dele com perícia e entrega. O empreiteiro junta tudo e te dá a obra pronta. O maestro do Claude Code é esse empreiteiro:
- •Maestro = o chat principal. Entende, planeja, delega, junta.
- •Subagente = o especialista. Recebe uma tarefa única e foca só nela.
- •Você = o dono da obra. Fala só com o maestro, vê o resultado.
O maestro é o agente principal — quem conduz a conversa e distribui o trabalho. O subagente é um trabalhador que ele aciona sob demanda para uma tarefa específica.
Sem esse modelo na cabeça, você tenta "conversar" com o subagente ou espera que ele lembre da conversa toda. Entender quem coordena e quem executa evita 90% da confusão inicial.
Orquestrador × executor · delegação sob demanda · ponto de contato único (você ↔ maestro).
🔁 O ciclo: tarefa → janela própria → relatório
O coração do subagente é o contexto separado. Quando o maestro delega, o subagente abre uma janela própria — uma sessão limpa, isolada da sua conversa. Ele faz o trabalho ali, gera toda a bagunça que precisar, e devolve apenas um relatório. O maestro lê esse relatório e te comunica de volta. A sua janela nunca vê a sujeira.
A tarefa é despachada
O maestro identifica um trabalho pesado.
Ele escreve um briefing claro e entrega ao subagente: "leia estes 40 arquivos e me diga onde o login quebra".
O subagente trabalha na janela dele
Sessão própria, isolada, descartável.
Ele abre arquivos, roda buscas, acumula centenas de linhas de leitura — tudo dentro do contexto dele, que some quando termina.
O relatório volta limpo
O maestro comunica a você.
O subagente devolve a conclusão: "o bug está no auth.js, linha 88". O maestro repassa isso a você — sem os 40 arquivos no caminho.
📊 Por que a janela própria importa
O subagente pode "queimar" 200 mil tokens lendo arquivos e isso não ocupa um único token da sua sessão. Você fica com a conclusão; a leitura bruta ficou na janela descartável dele. É proteção de contexto — o tema do próximo módulo.
🎭 A demo das 5 personas
O exemplo clássico: você pede ao maestro para revisar um livro sob cinco olhares diferentes. Em vez de fazer cinco leituras em sequência, ele abre cinco subagentes em paralelo — cada um com uma lente própria. Rodam ao mesmo tempo, cada um na sua janela. E você pode entrar em cada sessão e ver exatamente o prompt que o maestro mandou para aquele especialista.
Linda, 58
Professora aposentada · iniciante em IA
"Isto faz sentido para quem nunca ouviu falar do assunto? Onde travei?"
Engenheiro de software
Olhar técnico
"Os exemplos de código estão corretos? Falta rigor em algum ponto?"
Dono de negócio
Olhar de retorno
"Qual o valor prático? Isto me ajuda a ganhar ou economizar dinheiro?"
David, 52
COO de Fortune 500 · olhar de escala
"Isto funciona com 5.000 funcionários? Onde quebra na operação grande?"
Editor / publisher
Olhar editorial
"O texto flui? O argumento se sustenta do começo ao fim?"
Cinco em paralelo
Cinco lentes, ao mesmo tempo, cada uma na sua janela. O maestro junta os cinco relatórios.
💡 Você pode espiar cada sessão
Cada subagente roda numa sessão visível. Dá para abrir a do "COO" e ler o briefing exato que o maestro escreveu para ela. Isso desmistifica o subagente: não é mágica, é um chat focado que alguém abriu para uma tarefa.
🚫 O que o subagente NÃO é
Aqui mora a confusão mais comum. O subagente não é o chat principal e você não conversa diretamente com ele. Ele não responde a você — ele responde ao maestro. Pensar nele como "outro chat onde eu digito" é o erro que faz tudo parecer quebrado.
✓ O que o subagente É
- ✓Um trabalhador focado, acionado pelo maestro
- ✓Dono de uma janela de contexto separada
- ✓Quem devolve um relatório e some
- ✓Subordinado ao maestro, não a você
✗ O que o subagente NÃO é
- ✗Não é o seu chat principal
- ✗Não é alguém com quem você digita direto
- ✗Não guarda a memória da sua conversa
- ✗Não responde a você — responde ao maestro
⚠️ O erro que trava iniciantes
Tentar "responder" um subagente como se fosse uma janela de chat. Ele não está esperando o seu input — ele já recebeu o briefing do maestro e está executando. Se você quer mudar algo, você fala com o maestro, e o maestro ajusta ou dispara um novo subagente.
🔗 Relação 1-para-1 com o maestro
Cada subagente fala só com o maestro. Os subagentes não conversam entre si. É um modelo de estrela: o maestro no centro, cada especialista ligado a ele por um fio direto, e nenhum fio entre os especialistas. Isso mantém tudo previsível — sem "telefone sem fio" entre trabalhadores.
✓ Como o fluxo acontece
- ✓Subagente → maestro (relatório)
- ✓Maestro → subagente (briefing)
- ✓O maestro junta os relatórios de todos
✗ O que não rola
- ✗Subagente A → subagente B
- ✗Dois subagentes "negociando" uma resposta
- ✗Um subagente lendo a janela do outro
🚀 Primeiro contato — invoque um built-in
Você não precisa criar nada para começar. O Claude Code já vem com subagentes built-in
(como o general-purpose, que pesquisa e lê arquivos). Para acionar um, basta
linguagem natural: você descreve o serviço e o maestro decide delegar. Sem comando
especial, sem sintaxe difícil.
você > Pesquise a ferramenta "ripgrep" e me traga só
um resumo de 5 bullets, sem encher meu contexto.
# o maestro decide delegar a um subagente built-in,
# que abre a janela dele, faz a pesquisa pesada,
# e devolve ao maestro só os 5 bullets pedidos.
maestro > Pronto — 5 pontos sobre o ripgrep:
1) busca recursiva ultrarrápida em texto …💡 A frase que aciona
Duas pistas fazem o maestro delegar: "me traga só um resumo" (a saída é pequena) e "sem encher meu contexto" (a leitura é grande e descartável). Esse é exatamente o caso de ouro para um subagente — e o tema da "pergunta que decide", lá no módulo 1.5.
Exemplo real: um subagente em arquivo
Um subagente custom é só um arquivo .md: um cabeçalho de configuração
(frontmatter) e um corpo com as instruções. Você vai dissecar cada campo nas trilhas
seguintes — por ora, leia este code-reviewer.md mínimo só para ver a cara da coisa.
--- # frontmatter: a CONFIGURAÇÃO do subagente
name: code-reviewer # minúsculas e hífens
description: Revisa o diff atual em busca de bugs,
falhas de segurança e testes faltando. Use após
qualquer mudança de código. # isto é o GATILHO
tools: Read, Grep, Glob # só leitura: não edita nada
model: sonnet # bom o bastante para revisar
---
# corpo: o CÉREBRO do subagente
You are a senior code reviewer.
When invoked:
1. Run git diff to see what changed.
2. Read the changed files and understand the intent.
3. Review for correctness, security and missing tests.
Flag: bugs, security holes, and missing tests.
Be concise. Do not rewrite the code — only report.⚙️ O frontmatter (config)
- name — como o maestro chama o agente.
- description — o gatilho: faz o maestro saber quando usar.
- tools — o que ele pode fazer (aqui, só ler).
- model — qual modelo roda a tarefa.
🧠 O corpo (cérebro)
- Papel — "you are a senior code reviewer".
- Passos — o que fazer, numerado.
- Saída — o que reportar.
- Limites — o que NÃO fazer (não reescrever).
Prompts prontos (copie e cole)
Dois prompts para você acionar um subagente built-in agora mesmo, sem configurar nada. Repare no padrão: pedir o resumo e proteger o contexto.
Abra um subagente pra pesquisar a ferramenta X e me
traga só um resumo de 5 bullets. Não cole o conteúdo
bruto aqui — só a conclusão.Use o general-purpose pra ler estes arquivos e me
resumir o que importa, sem encher meu contexto.
Devolva no máximo 1 parágrafo + os caminhos relevantes.Tela simulada: 5 subagentes em paralelo
É assim que a demo das 5 personas aparece no terminal: o maestro disparou cinco subagentes e você os vê rodando lado a lado, cada um com seu modelo e seu progresso. Embaixo, a status line mostra quanto do seu contexto está em uso — e ele quase não mexe, porque o trabalho pesado está nas janelas deles.
↑ Recriação ilustrativa do terminal (não é screenshot real). Note os 5 subagentes a todo vapor enquanto o seu contexto mal sai do lugar.
Exercício
Liste 3 tarefas do seu dia que dariam bons subagentes. Para cada uma, justifique com a pergunta que decide: "isso vai despejar coisa que eu nunca vou reler?"
Como fazer
- Pense em coisas que você faz no computador e que leem muito, geram muita saída, ou se repetem.
- Escreva a tarefa em uma linha (ex.: "vasculhar 30 PDFs atrás de uma cláusula").
- Responda, para cada uma, à pergunta que decide — e diga qual critério ela atende.
✅ Critério de verificação — como saber que acertou
Cada tarefa que você listou deve atender a pelo menos um destes três sinais:
- →Lê muitos arquivos (a leitura bruta não precisa ficar no seu contexto).
- →Gera muita saída que você nunca vai reler por inteiro (só quer a conclusão).
- →É repetível ou paralela (dá para rodar várias vezes, ou várias de uma vez).
Se uma tarefa é uma edição rápida ou exige a conversa inteira, ela não é candidata — e perceber isso também conta como acerto.
Exemplo resolvido
Tarefa: "ler 30 PDFs de contrato e achar onde aparece a cláusula de rescisão". Bom subagente? Sim — lê muitos arquivos e gera muita saída que eu não vou reler; quero só o "achei na página X de cada contrato". Atende 2 dos 3 sinais.
✅ Resumo do módulo
Próximo módulo:
1.2 — O verdadeiro motivo: contexto limpo. Por que proteger contexto é o motivo nº 1 dos subagentes.