Subagentes Claude Code: Quando e Como Executar Equipes de Agentes

Última atualização: June 28, 2026

Um subagente Claude Code é uma sessão Claude separada que o agente principal inicia para um trabalho focado e depois incorpora o resultado ao seu trabalho. Na semana passada, despachei três em paralelo para dividir um refatoramento em esquema, API e testes, e eles terminaram antes que uma única longa sessão teria terminado de planejar. Este post cobre como definir e despachar subagentes, os padrões de orquestração que uso para imitar uma pequena equipe e a linha honesta onde os subagentes custam mais do que economizam.

Resposta rápida: o que é um subagente Claude Code?

Um subagente é uma instância Claude com sua própria janela de contexto, seu próprio prompt de sistema e um conjunto de ferramentas restrito. A sessão principal não perde contexto ao executar um, porque o subagente trabalha em isolamento e retorna apenas um resumo. Pense nisso como delegar uma tarefa a um colega de equipe que nunca interrompe sua tela.

O mecanismo oficial é simples. Você coloca um arquivo markdown em .claude/agents/ com frontmatter YAML, e o Claude Code pode chamá-lo através da ferramenta Task quando uma tarefa corresponde à sua descrição. A documentação de subagentes é a fonte de verdade para os campos, e o repo do Claude Code rastreia as alterações no formato.

Uma definição mínima de subagente se parece com isto:

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Uma vez que esse arquivo existe, eu pergunto ao agente principal "use o subagente migration-writer para adicionar a tabela orders" e ele despacha um trabalhador limitado em escopo em vez de se atrapalhar com isso inline. A linha model: inherit mantém custo e qualidade no mesmo nível da sessão principal; fixar um modelo mais barato como haiku em um subagente pesado em leitura é uma alavanca real quando você executa muitos deles.

Quando você deve recorrer a subagentes em vez de uma sessão?

Recorra a um subagente quando uma tarefa for de longa duração, pesada em contexto ou necessitar de um conjunto de ferramentas que você não quer na sessão principal. Mantenha em uma única sessão quando o trabalho for curto, intimamente acoplado ao que você já está fazendo ou precisar de um diálogo intenso com você.

Eu uso subagentes para trabalhos que, de outra forma, poluíriam meu contexto principal com logs, grandes leituras ou tentativa e erro. Uma auditoria em todo o codebase que usa grep em 200 arquivos é uma candidata perfeita, porque o subagente lê tudo e devolve um resumo de dois parágrafos enquanto minha sessão principal permanece limpa.

Se você é novo em relação ao próprio agente, o guia definitivo do Claude Code cobre os fundamentos antes que você adicione subagentes por cima.

Como despachar subagentes no Claude Code?

O despacho acontece de duas maneiras. O agente principal pode invocar a ferramenta Task por conta própria quando uma tarefa se encaixa na descrição de um subagente, ou você pode nomeá-lo explicitamente em seu prompt. Eu prefiro nomeá-lo, porque o despacho implícito às vezes pula um agente que eu queria.

Alguns padrões que executo regularmente:

• "Use o subagente code-reviewer no diff neste branch e depois aplique suas sugestões."
• "Despache migration-writer para adicionar uma coluna users.email_verified, e despache test-writer para cobri-la. Execute ambos."
• "Inicie o subagente api-docs contra src/routes/ e retorne apenas o esqueleto OpenAPI."

O subagente roda em seu próprio contexto, então ele não pode ver sua conversa em andamento a menos que você passe o detalhe no prompt. Esse isolamento é o ponto. Quando ele termina, você recebe um resultado, não um fluxo de ruído intermediário.

Padrões que uso para fluxos de trabalho tipo equipe

O truque é copiar como uma equipe real divide o trabalho e, em seguida, mapear cada função para um subagente. Aqui estão os padrões aos quais eu continuo voltando.

Pesquisar, depois expandir. Eu despacho um subagente para coletar contexto, leio seu resumo e, em seguida, despacho vários subagentes de implementação contra uma interface compartilhada. Isso espelha um tech lead definindo o escopo do trabalho antes de distribuir os tickets.

Construir atrás de um contrato. Defina a API ou as props do componente primeiro, depois execute um subagente backend e um subagente frontend em paralelo contra esse contrato. Nenhum bloqueia o outro, e conflitos são raros porque eles tocam em arquivos diferentes.

Revisar como uma função separada. Eu mantenho um subagente code-reviewer com apenas ferramentas de leitura. Depois de qualquer mudança não trivial, eu o executo contra o diff. Restringir suas ferramentas significa que ele literalmente não pode editar, o que mantém a revisão honesta.

Para fluxos de trabalho repetíveis como este, combine subagentes com Claude Code skills: um skill codifica os passos e os subagentes fazem o trabalho isolado. E se um subagente precisar de dados externos, conecte-o a um servidor MCP da maneira que o guia de integração MCP do Claude Code descreve.

Um exemplo prático: pedidos e pagamentos

No mês passado, dividi um recurso de pedidos mais pagamentos em três subagentes contra um contrato tipado. O contrato era uma única interface TypeScript para um Order com status, totalCents e paymentId. Eu despachei: um subagente backend para implementar a criação do pedido e as transições de status; um subagente payments para conectar a chamada Stripe e armazenar o paymentId; e um subagente test para cobrir o caminho feliz e o caso limite de reembolso. Os três tocaram em arquivos diferentes, então a fusão foi três operações limpas de copiar-colar em vez de uma sessão de resolução de conflitos. Todo o processo levou 14 minutos; o mesmo trabalho em uma única sessão serial levou 41 na semana anterior, porque o contexto único continuava recarregando os docs do Stripe.

Como orquestrar trabalho paralelo sem perder contexto?

A sessão principal é seu coordenador. Seu trabalho é quebrar o trabalho, distribuir prompts limitados e costurar os resultados de volta. Mantenha o coordenador enxuto e deixe os subagentes fazerem as leituras pesadas.

Uma execução paralela típica para mim se parece com isto:

1. Escrever o contrato e os limites dos arquivos na sessão principal.
2. Despachar dois a quatro subagentes, cada um com uma fatia e uma condição de sucesso clara.
3. Ler cada resumo à medida que ele retorna, não no meio da execução.
4. Mesclar na sessão principal, resolvendo as costuras por conta própria.
5. Executar o subagente test por último contra o resultado integrado.

O paralelismo só compensa quando as fatias são genuinamente independentes. Se dois subagentes editarem schema.prisma, você não dividiu o trabalho, você criou um problema de fusão. Desenhe limites em arquivos e contratos, e depois imponha-os no prompt.

Quando os subagentes adicionam mais sobrecarga do que economizam?

Subagentes adicionam latência, tokens e custo de coordenação. O repasse do resumo perde detalhes, então qualquer coisa que precise de continuidade profunda é um mau ajuste. Seja honesto sobre o tradeoff antes de recorrer a eles.

Eu executei um benchmark em um branch de recurso uma vez: um subagente por microserviço versus uma única sessão percorrendo-os em ordem. Para cinco serviços fracamente acoplados, o paralelo venceu em aproximadamente 40% no tempo de relógio. Para três serviços que compartilhavam um modelo de dados, a sessão única foi mais rápida, porque a fusão e a reexplicação comeram os ganhos paralelos.

A lição: paralelismo recompensa a independência e pune o acoplamento. Se suas fatias compartilham estado, não as paralelize.

Quais são os erros comuns?

• Muitos subagentes. Eu limito uma execução a três a cinco. Além disso, o custo de coordenação supera o ganho paralelo.
• Prompts vagos. "Corrija o auth" falha. "Adicione um endpoint JWT refresh em /auth/refresh, retornando { token }, com um teste" tem sucesso.
• Sem critérios de sucesso. Declare o que significa feito. "Migração aplicada localmente e rollback testado" supera "lidar com o esquema".
• Conjunto de ferramentas errado. Dê a um revisor apenas ferramentas de leitura. Dê a um agente de deploy os comandos exatos que ele precisa, nada mais amplo.
• Ignorar falhas. Se um subagente retornar um erro, leia-o. Tentar novamente cegamente gasta tokens e esconde um problema real.
• Pular a fusão. Subagentes retornam resultados; você ainda é o dono da integração. Alocar tempo real para isso.

O erro mais caro é tratar os subagentes como paralelismo gratuito para qualquer coisa. Eles são trabalhadores limitados por trás de um limite de resumo, e esse limite tem um custo.

Resumo

Os subagentes transformam o Claude Code em algo que parece uma pequena equipe: um coordenador enxuto despachando trabalhadores limitados que cada um carrega seu próprio contexto e relata um resultado. Defina-os em .claude/agents/, despache com a ferramenta Task, e mantenha sua sessão principal limpa ao empurrar leituras pesadas e papéis repetitivos para subagentes.

Use-os quando o trabalho for longo, pesado em contexto ou precisar de um conjunto de ferramentas restrito. Pule-os para tarefas curtas, acopladas e interativas onde o repasse do resumo perde muito. Desenhe limites em arquivos e contratos, limite uma execução a um punhado de agentes e sempre reserve tempo para mesclar os resultados você mesmo.

Um aviso real: subagentes multiplicam o throughput, não o julgamento. Eles construirão alegremente a coisa errada em paralelo através de quatro contextos isolados. O trabalho de coordenação, a definição do contrato e a revisão final ainda caem sobre você, então a alavancagem só aparece quando as fatias são verdadeiramente independentes e os critérios de sucesso são exatos. Se você quiser o fundo mais profundo sobre o protocolo que alimenta grande parte dessa ligação de ferramentas, o explainer MCP é uma boa leitura seguinte, e a documentação do Claude Code cobre configurações que eu não repeti aqui.

Créditos das imagens

• Uma equipe de desenvolvedores trabalhando juntos em computadores em um escritório moderno de tecnologia — foto por Rebrand Cities em Pexels
• Código de programação colorido em um monitor de computador — foto por inna mykytas em Pexels
• Um desenvolvedor escrevendo código em um laptop na frente de múltiplos monitores — foto por Christina Morillo em Pexels
• Dois programadores focados em codificar lado a lado em um escritório moderno — foto por Rebrand Cities em Pexels