Subagents ou Agent Teams no Claude Code: como paralelizar sem criar caos

English summary: A practical guide to choosing Claude Code subagents or experimental agent teams, defining safe write boundaries, controlling coordination cost, and making handoffs, worktrees, verification, and cancellation operational.

Published: August 2026
Reading time: 19 minutes
Keywords: Claude Code, subagents, agent teams, worktrees, multi-agent coordination, handoffs, agentic coding

---

TL;DR

• Use subagents quando houver uma tarefa isolável.
• Use teams somente quando houver coordenação e fronteiras reais.
• Exija artefatos, handoffs, cancelamento e reconciliação verificáveis.

Exemplo concreto: um worker pode escrever seu relatório em um diretório próprio e entregar um contrato para o reconciliador.

Adicionar mais agentes parece uma resposta óbvia quando um trabalho de engenharia demora: se um Claude investiga, outro implementa e um terceiro testa, o time termina antes. Às vezes termina. Outras vezes você paga três vezes para produzir duas hipóteses idênticas, cria um conflito no mesmo arquivo e descobre tarde que ninguém era dono da decisão de merge.

Esse é o problema menos glamouroso da programação com agentes: paralelismo não elimina trabalho; ele troca parte do trabalho de implementação por trabalho de coordenação. Sem uma fronteira de escrita, um contrato de handoff e uma regra de parada, cada novo agente aumenta a área de incerteza.

Minha tese é simples: use subagents para trabalho focado cujo resultado basta ao agente principal; use agent teams apenas quando pessoas-agentes precisam se coordenar de verdade — e trate ownership, verificação e cancelamento como parte do produto, não como detalhes do prompt.

No Claude Code, essa escolha tem implicações concretas de contexto, tokens, ferramentas, isolamento de Git e controle humano. Este texto explica o que cada topologia é, onde ela falha, como começar pequeno e um artefato copiável para operacionalizar uma equipe sem abrir a porteira para escrita concorrente.

O que são subagents e agent teams — e o que não são

Um subagent é um assistente especializado chamado dentro de uma sessão do Claude Code. Ele tem janela de contexto própria, prompt de sistema, ferramentas e permissões definidos para o seu papel; faz o trabalho e devolve um resultado resumido a quem o chamou. Isso é especialmente útil quando busca, logs ou leitura de muitos arquivos poluiriam a conversa principal. A documentação também permite restringir ferramentas, pré-carregar skills, limitar turns e, quando necessário, isolar o subagent em um worktree. Claude Code: subagents

Um agent team é outra topologia: a sessão principal vira líder e coordena várias sessões independentes. Os teammates têm contexto próprio, compartilham uma lista de tarefas e podem trocar mensagens diretamente. A documentação do Claude Code os marca como experimentais e desabilitados por padrão; em 12 de agosto de 2026, exigem CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Claude Code: agent teams

Essa diferença não é cosmética.

Pergunta	Subagents	Agent teams
Quem coordena?	A conversa principal	Líder e teammates via lista compartilhada
Quem conversa com quem?	Worker reporta ao chamador	Teammates podem se comunicar diretamente
Unidade operacional	Trabalho especializado dentro da sessão	Sessões independentes colaborando
Custo de contexto	Menor; resultado volta resumido	Maior; cada teammate tem contexto próprio
Melhor encaixe	Pesquisa, revisão, análise, tarefa auxiliar	Hipóteses concorrentes, revisão multidisciplinar, módulos independentes
Maior risco	Delegação vaga ou resumo insuficiente	Coordenação, conflito de arquivos e custo multiplicado

Nenhum dos dois é sinônimo de “autonomia total”. Um grupo de agentes não substitui uma decisão de produto, uma revisão de segurança ou a responsabilidade de quem faz merge. Tampouco é o caminho certo para toda automação. Um workflow sequencial simples — lint, teste, build, publicação — continua melhor quando a ordem é conhecida, a saída é objetiva e não há decisão aberta a ser tomada.

A própria Anthropic separa workflows, nos quais caminhos são definidos em código, de agents, nos quais o modelo dirige dinamicamente o processo e o uso de tools. A recomendação é começar pelo sistema mais simples que resolve o problema e só elevar complexidade quando ela melhora um resultado mensurável. Building effective agents

As quatro falhas que fazem uma equipe de agentes virar ruído

Antes de desenhar a topologia, vale reconhecer os padrões que parecem produtividade no terminal e viram retrabalho no repositório.

1. Paralelizar dependências

“Um agente cria a API, outro cria a UI e outro escreve os testes” parece uma boa divisão. Mas não é paralela se a UI depende do contrato da API e os testes dependem dos dois. Os três vão inventar interfaces provisórias, e a integração passa a ser uma quarta tarefa não planejada.

Divida por independência verificável, não por nomes de camadas. Três revisores lendo o mesmo diff com lentes diferentes — segurança, performance e cobertura — podem trabalhar em paralelo porque suas saídas são achados, não alterações concorrentes. Já uma feature de autenticação provavelmente precisa de uma sequência: primeiro contrato, depois implementação, depois testes e revisão.

Uma pergunta útil é: “Se este worker terminar sem receber uma nova mensagem por vinte minutos, ele ainda consegue produzir um artefato correto?” Se a resposta for não, há uma dependência; modele-a como tal na lista de tarefas.

2. Fronteiras de escrita imaginárias

“Cada agente pega uma parte” não é fronteira. Uma fronteira é um objeto que pode ser inspecionado: diretório, pacote, arquivo, contrato de API ou documento de decisão. Sem isso, dois agentes editam package.json, uma migration ou o mesmo componente “só para ajustar uma coisa”.

O dano não é só conflito de Git. Mudanças que aplicam limpas ainda podem contradizer regras de negócio, duplicar um endpoint ou introduzir duas abstrações para o mesmo problema. git diff não detecta essa colisão semântica.

Para trabalho de escrita, declare antes de começar:

• um único dono por caminho gravável;
• arquivos compartilhados que são somente leitura para teammates;
• quem pode editar contrato, schema, lockfile e configuração de CI;
• o branch ou worktree de cada implementação;
• a pessoa ou sessão que integra o resultado.

Um worktree resolve isolamento físico de checkout; ele não resolve ownership. É possível ter três worktrees e três interpretações incompatíveis do mesmo requisito.

3. Handoff como “me avise quando terminar”

Um agente que diz “feito” entrega quase nenhuma informação útil. O próximo precisa redescobrir objetivo, escopo, hipótese, arquivos mexidos, comandos rodados e risco restante. Isso é o imposto de handoff.

Todo handoff precisa ter formato. No mínimo: entrega, evidência, limites, próximos passos e decisão pendente. Se uma tarefa alterou estado, inclua também a localização exata da mudança e como revertê-la. Isso transforma uma conversa em interface operacional.

Não espere uma documentação bonita no fim. Exija um handoff curto ao encerrar cada unidade de trabalho. Quanto mais cedo o contrato aparece, menor o custo de descobrir que dois workers assumiram coisas diferentes.

4. Cancelamento tratado como desaparecimento

Interromper um teammate não desfaz o que ele leu, escreveu ou concluiu. Ele pode ter deixado um worktree com alterações, uma tarefa marcada como em progresso e uma hipótese parcialmente comunicada. E um agente cancelado pode ter parado justamente antes da verificação.

No Claude Code, é possível interromper um teammate ativo pela interface e pedir encerramento gracioso por nome; a documentação alerta que agent teams têm limitações conhecidas de retomada, coordenação e shutdown. Controle e encerramento de teammates Não use cancelamento como sinal de sucesso nem como limpeza automática de responsabilidade.

O protocolo correto é: parar novas ações, registrar o estado, inspecionar o diff, decidir entre preservar ou descartar de modo explícito e só então redistribuir a tarefa. Se houver um ambiente remoto, revogar ou expirar a credencial temporária também faz parte do cancelamento.

O harness: o sistema ao redor do modelo é que torna o paralelo seguro

O modelo não sabe, por si, quais arquivos são sensíveis, qual comando é aceitável ou o que prova que uma mudança funciona. O harness é o conjunto de contexto, tools, permissões, ambiente e verificação que transforma uma resposta em trabalho controlado.

Em Claude Code, comece pelo CLAUDE.md do projeto. Ele deve conter invariantes que não podem depender da memória de uma conversa: comandos de validação, áreas proibidas, regras de testes, convenções e pontos de parada humana. Em seguida, dê a cada subagent ou teammate apenas as tools necessárias. Um revisor não precisa de Write; um migrador não precisa de credencial de produção; um pesquisador não deve ter a chave para publicar nada.

Use três níveis de permissão, não uma permissão ampla com aviso em linguagem natural:

Nível	Capacidades	Casos típicos
Observar	Ler, buscar, executar checks sem efeitos	Exploração, revisão, triagem de incidente
Propor	Criar plano, patch ou diff em worktree isolado	Feature, correção, refactor
Aplicar	Editar checkout designado ou ambiente autorizado	Integração controlada, manutenção aprovada

O ponto de transição entre propor e aplicar é uma decisão humana ou um gate automatizado robusto. Não deixe o mesmo agente inventar o requisito, editar a superfície crítica e declarar que validou tudo.

Hooks são úteis para tornar essa política executável. Em vez de escrever “nunca toque em produção” no prompt, um PreToolUse pode negar a ferramenta antes de ela rodar. A referência oficial permite decisões de bloqueio e negação no ciclo de ferramentas. Claude Code hooks

Também há observabilidade. Guarde uma trilha por tarefa: prompt de delegação, dono, caminhos permitidos, mensagens de handoff, comandos de verificação, exit codes e diff final. Não é burocracia: em um sistema não determinístico, essa trilha é como você explica por que uma alteração existe e como reproduzir o julgamento.