Ao final deste capítulo, você saberá dividir uma tarefa grande entre vários assistentes especializados, cada um com contexto e instruções próprias, e coordenar esse trabalho sem perder o controle. Isso reúne o que vimos sobre git worktrees no capítulo onze, comandos personalizados e hooks no capítulo doze e servidores MCP no capítulo treze em fluxos completos de trabalho.
O que é um subagente
Um subagente é uma instância separada do Claude que a sessão principal aciona para cumprir uma tarefa delimitada. Ele tem a própria janela de contexto, as próprias instruções e o próprio conjunto de ferramentas permitidas. Quando termina, devolve à sessão principal apenas um resumo do resultado, e não tudo o que leu ou executou pelo caminho. Essa é a característica mais importante: o trabalho pesado acontece em um contexto isolado, e a conversa principal recebe só a conclusão.
Você já viu isso acontecer sem perceber. Quando pede algo como descobrir em quais lugares do projeto o campo de prazo é validado, o Claude Code costuma disparar uma busca em um subagente interno. Ele varre dezenas de arquivos, lê trechos, descarta o que não interessa e retorna uma lista curta com arquivos e linhas. Se essa varredura acontecesse na sessão principal, cada arquivo aberto ocuparia espaço na sua janela de contexto e degradaria a qualidade das próximas respostas, como discutimos no capítulo dez. No terminal, você reconhece o momento pela indicação de uma tarefa em andamento com um resumo do que foi delegado.
Criando subagentes personalizados
Além dos subagentes automáticos, você pode definir os seus. Cada um é um arquivo Markdown na pasta .claude/agents do projeto, versionada e compartilhada com o time, ou na pasta .claude/agents da sua pasta de usuário, disponível em todos os projetos. O comando de barra /agents abre um assistente interativo para criar, editar e listar subagentes, mas editar o arquivo diretamente é igualmente válido e permite revisar o conteúdo com calma.
O arquivo tem um cabeçalho com quatro campos e um corpo com as instruções. O campo name é o identificador. O campo description explica quando o subagente deve ser usado e é lido pela sessão principal para decidir se delega automaticamente, então escreva-o como uma regra de acionamento. O campo tools lista as ferramentas permitidas; se for omitido, o subagente herda todas as da sessão. O campo model escolhe o modelo, o que permite usar um modelo mais rápido e barato para tarefas simples. O corpo funciona como um CLAUDE.md exclusivo daquele especialista.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
--- name: revisor-de-codigo description: Revisa alterações recentes em busca de bugs, falhas de segurança e desvios das convenções do projeto. Acione depois de qualquer implementação, antes do commit. tools: Read, Grep, Glob, Bash model: sonnet --- Você é um revisor de código experiente. Analise apenas o diff atual obtido com git diff. Não edite nenhum arquivo. Verifique, nesta ordem: 1. Bugs e casos de borda não tratados. 2. Segredos, dados sensíveis ou comandos perigosos. 3. Desvios das convenções descritas no CLAUDE.md. 4. Testes ausentes para comportamento novo. Responda com uma lista curta separada em Crítico, Importante e Sugestão, citando arquivo e linha em cada item.Observe duas decisões nesse arquivo. As ferramentas permitidas não incluem Edit nem Write, o que já reduz bastante o risco de o revisor mexer no código. Ainda assim, o Bash que está na lista permite escrever em arquivos por vias indiretas, com redirecionamentos ou comandos como sed em modo de edição, então, se você quer uma garantia de fato, restrinja o Bash apenas aos comandos de leitura de que o revisor precisa, como git diff, usando as regras de permissão do capítulo seis. E a saída é padronizada, para que a sessão principal e você consigam agir sobre ela sem interpretar um texto solto.
Quatro especialistas que valem a pena ter
- Revisor de código, como o do exemplo: somente leitura, acionado após cada implementação.
- Especialista em testes: recebe um arquivo ou função e escreve testes seguindo as regras do capítulo nove, com casos de borda listados e proibição de mocks desnecessários. Ele pode editar, mas só arquivos de teste, o que você garante com regras de permissão por padrão de arquivo.
- Investigador de bugs: recebe um stack trace ou passos de reprodução e devolve a causa raiz com evidência, sem corrigir nada. Isso separa diagnóstico de correção, como fizemos no capítulo oito.
- Redator de documentação: lê o código alterado e atualiza o README ou a documentação da API, usando um modelo mais barato, porque a tarefa exige mais consistência do que raciocínio profundo.
Quando delegar vale a pena e quando é excesso
Delegar traz três ganhos. O primeiro é isolar contexto: uma investigação que lê quarenta arquivos não polui a conversa em que você está implementando. O segundo é paralelizar: a sessão principal pode disparar vários subagentes ao mesmo tempo, por exemplo um analisando o backend e outro o frontend. O terceiro é manter o foco: instruções especializadas produzem resultados mais consistentes do que uma sessão genérica tentando lembrar de tudo.
Delegar é excesso quando a tarefa é pequena, como renomear uma variável, porque o custo de iniciar outro contexto supera o ganho. Também é excesso quando a tarefa depende de toda a conversa anterior, já que o subagente começa do zero e conhece apenas o que a sessão principal escrever no pedido. Se você se pega redigindo um pedido enorme para o subagente, provavelmente a sessão principal deveria fazer o trabalho.
Padrões para tarefas longas
Implementador e revisor
Peça à sessão principal que implemente uma etapa e, ao terminar, acione o revisor de código. Uma instrução como implemente a validação do campo, depois use o revisor de código e corrija o que ele marcar como crítico antes de me mostrar cria um ciclo em que o código chega a você já filtrado. Como o revisor tem contexto próprio, ele não é influenciado pelas decisões que o implementador acabou de tomar, o que reduz a cegueira de quem revisa o próprio trabalho.
Sessões paralelas em worktrees
Para tarefas independentes, como uma funcionalidade nova e uma correção de bug, abra um git worktree para cada uma, conforme o capítulo onze, e rode uma sessão do Claude Code em cada pasta. Cada sessão tem seu contexto, seu branch e seus arquivos, sem risco de uma edição atrapalhar a outra. Lembre apenas de que um worktree novo não recebe o que não está versionado, como o arquivo .env e as dependências instaladas, e de que duas sessões rodando ao mesmo tempo disputam a mesma porta e o mesmo banco de dados local, então copie o que faltar e configure portas diferentes em cada uma. Você alterna entre os terminais para revisar diffs enquanto o trabalho avança nos dois lados.
Listas de tarefas acompanhadas
Em tarefas com muitas etapas, peça explicitamente que o Claude Code mantenha uma lista de tarefas e marque cada item ao concluir. Ele exibe a lista no terminal, atualiza o progresso e você enxerga o que já foi feito e o que falta. Combine isso com o plano em Markdown do capítulo dez, e a lista vira o ponto de retomada quando a sessão precisar ser reiniciada com /clear.
Montando um fluxo completo
Os capítulos anteriores fornecem as peças. Imagine um comando personalizado chamado resolver-issue que recebe o número de uma issue como argumento. Ele usa a ferramenta MCP do GitHub para ler a descrição, aciona o investigador de bugs para apontar a causa raiz, pede à sessão principal a correção em etapas pequenas, chama o especialista em testes para criar o teste de regressão, executa a suíte, aciona o revisor de código e, por fim, abre um pull request com o GitHub CLI. Um hook de PostToolUse formata cada arquivo editado, e um hook de Stop avisa quando tudo terminar. Nada disso é novo; a novidade é a orquestração.
Limites que não mudam
Mais agentes não significam menos supervisão. Cada subagente pode errar, e o resumo que ele devolve à sessão principal é uma versão condensada do que aconteceu, não uma prova. Trate a saída de um agente como trataria o relatório de um colega recém-chegado: leia, confira os arquivos e linhas citados e execute os testes você mesmo. Um revisor automático que aprova tudo e um implementador que sempre afirma que a suíte passou merecem a mesma desconfiança que dedicamos aos testes que congelam o comportamento atual.
O custo também se multiplica. Cada subagente consome a própria janela de contexto e os próprios tokens, e um fluxo com cinco especialistas pode custar várias vezes o que custaria uma sessão simples. Use /cost com frequência, escolha modelos mais baratos para tarefas mecânicas e evite delegar por reflexo. Lembre ainda que as regras de permissão do capítulo seis valem para subagentes: uma lista deny no settings.json impede que qualquer agente leia um arquivo .env, mesmo que suas instruções digam o contrário. Para comandos de terminal, porém, a verificação é feita por padrão de texto e pode ser contornada por variações como pipes, aspas ou apelidos, então trate o deny como mais uma camada de proteção, e não como barreira infalível: em trabalhos arriscados, prefira um ambiente isolado e a aprovação manual de cada comando.
Resumo
Subagentes são instâncias isoladas do Claude com contexto, instruções e ferramentas próprias, que devolvem à sessão principal apenas um resumo. O Claude Code já os usa sozinho para buscas amplas, e você cria os seus em arquivos Markdown na pasta .claude/agents, com cabeçalho de name, description, tools e model. Revisor de código, especialista em testes, investigador de bugs e redator de documentação cobrem a maior parte das necessidades. Delegue para isolar contexto, paralelizar e manter o foco, mas não para tarefas pequenas ou que dependem de toda a conversa. Para trabalhos longos, combine implementador e revisor, worktrees paralelos, listas de tarefas acompanhadas e os comandos, hooks e servidores MCP dos capítulos anteriores. E nunca abra mão da revisão humana, da verificação dos resultados e do acompanhamento do custo.
