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.

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.

A escada incremental: não comece por uma equipe

Muitas equipes introduzem agent teams porque uma tarefa parece grande. O caminho de menor risco é subir uma escada e parar assim que o ganho aparece.

Trabalho único. Execute uma tarefa manualmente com uma definição de pronto clara. Descubra entradas, saídas, comandos e decisões humanas.
Contrato. Registre invariantes no CLAUDE.md: caminhos sensíveis, testes, reversão e aprovações.
Skill. Empacote um playbook repetitivo: revisão de autenticação, triagem de falha, preparação de release. Uma skill reduz reexplicação, não cria mais autonomia por mágica.
Subagent. Delegue uma função com contexto isolado e tools mínimas. Comece por leitura ou revisão. Meça se o resumo poupa contexto e produz achados melhores.
Hooks e MCP. Adicione gates a ações perigosas e dados externos apenas quando o caso exigir. Integração é superfície de ataque; cada tool precisa de descrição e permissão.
Autonomia limitada. Permita mudanças em um worktree ou diretório explicitamente dono, com limites de turnos e validação exigida.
Agent team. Só agora, quando há subtarefas independentes que precisam discutir, contestar hipóteses ou coordenar um plano compartilhado.
Evals. Construa um conjunto de tarefas reais, critérios e traces. Meça taxa de conclusão correta, regressões, custo, tempo e necessidade de intervenção humana.

Essa sequência acompanha a orientação da Anthropic de preferir composição simples e aumentar complexidade apenas quando ela demonstra ganho. Também evita o erro de usar “mais agentes” para mascarar um contrato ainda desconhecido.

Artefato copiável: contrato de equipe com escrita exclusiva e handoff obrigatório

O arquivo abaixo é um CLAUDE.md de projeto. Ele não liga agent teams sozinho; ele torna uma equipe eventual mais segura ao declarar o que o líder deve fazer antes de delegar. Ajuste os caminhos e comandos para seu repositório.

# Multi-agent working agreement

## Before spawning workers

- State the goal, acceptance criteria, and integration owner.
- Create one task per independently verifiable deliverable.
- Give every writing task one exclusive `write_scope`.
- Treat `package.json`, lockfiles, migrations, CI, and public API contracts as
  shared: only the integration owner may edit them.

## Worker task template

Each task must include:

- `owner`: teammate or subagent name
- `mode`: observe | propose | apply
- `write_scope`: exact directories or files; empty for observe
- `inputs`: issue, spec, or source files
- `done_when`: observable acceptance criteria
- `verify`: exact commands and expected result
- `handoff_to`: integration owner

## Handoff format

Reply with exactly these fields:

1. `status`: done | blocked | cancelled
2. `changed`: files changed, or `none`
3. `evidence`: commands run and their result
4. `risk`: remaining uncertainty or `none known`
5. `next`: one recommended action for the handoff owner

## Cancellation

- Stop tool use immediately when asked to cancel.
- Do not mark the task done after cancellation.
- Report the handoff format above, including the current diff and commands not run.
- The integration owner decides whether to keep, revert, or move partial work.

## Verification gate

- A task is not done until its `verify` commands have run successfully.
- A failed or skipped check changes `status` to `blocked`, never `done`.
- Only the integration owner resolves cross-scope conflicts and merges changes.

Ele funciona porque transforma termos vagos em campos testáveis. “Ownership” deixa de ser boa intenção quando write_scope aponta para um caminho. “Validado” deixa de ser frase quando evidence traz o comando e seu resultado. “Cancelado” deixa de ser sumiço quando o handoff revela o estado parcial.

Para testar o contrato sem risco, rode primeiro uma equipe somente de revisão: um agente procura falhas de segurança, outro procura regressões de comportamento e outro lista lacunas de testes. Todos em observe, sem escopo de escrita. Só depois delegue uma correção pequena a um único dono.

Worktrees: isolamento útil, não licença para esquecer integração

Quando dois workers realmente precisam editar, worktrees evitam que um checkout físico seja modificado por vários processos. Um subagent pode receber isolation: worktree, o que o executa em uma cópia isolada do repositório. Segundo a documentação, o worktree é criado a partir do branch padrão por default, não necessariamente do HEAD da sessão pai; isso precisa entrar no seu plano de integração. Isolamento de subagents com worktrees

Há três decisões que não podem ser automáticas:

Base. De qual commit ou branch cada worktree parte? Se o objetivo depende de uma alteração ainda não integrada, criar do branch padrão gera falso sucesso contra código velho.
Integração. Quem compara e aplica os diffs? Escolha um único dono. Ele verifica conflitos textuais e também compatibilidade de contrato.
Descarte. Que worktree temporário tem mudanças que devem sobreviver ao encerramento? Cancelamento e término precisam chamar essa decisão pelo nome.

Uma topologia saudável para feature média costuma ser: líder em modo de coordenação; dois ou três reviewers read-only em paralelo; um implementador com worktree e escopo exclusivo; líder ou humano como integrador; depois teste end-to-end. Não entregue o mesmo componente para três implementadores e espere que o Git escolha o design certo.

Como escolher a topologia certa

Use a tabela como decisão inicial, não como substituta da leitura do trabalho.

Situação	Topologia inicial	Por quê	Gate antes de aumentar autonomia
Localizar arquivos e explicar uma área	Conversa principal ou subagent read-only	A saída é um resumo	Conferir referências a arquivos
Revisar um PR por lentes independentes	2–3 subagents ou team de review	Achados são paralelizáveis	Consolidar duplicatas e severidade
Depurar causa raiz com hipóteses concorrentes	Agent team pequeno	Teammates podem contestar evidências	Reproduzir a hipótese vencedora
Implementar uma alteração em um pacote isolado	Um subagent em worktree	Há um dono e uma fronteira clara	Testes do pacote e diff revisado
Alterar schema, autenticação ou cobrança	Sequência com humano integrador	Alto impacto e dependências fortes	Review, testes e aprovação explícita
Pipeline previsível de build e release	Workflow, não equipe	Ordem e regras já são conhecidas	Logs e artefatos de CI

Agent teams tendem a vencer quando a comunicação entre workers muda a qualidade da resposta: investigação científica com hipóteses rivais, revisão de um desenho por perspectivas conflitantes, ou módulos realmente separáveis. A documentação recomenda começar, em geral, com três a cinco teammates e aumentar apenas se o trabalho se beneficiar de simultaneidade; mais participantes elevam tokens, coordenação e conflitos. Boas práticas para agent teams

Subagents tendem a vencer quando só o resultado precisa voltar. Eles são mais fáceis de encerrar, auditar e encaixar em uma sessão já orientada por uma pessoa. Em muitas tarefas, o melhor “multi-agent system” é um agente principal que chama um investigador read-only e, depois, executa um patch pequeno com testes.

Segurança, ownership e verificação: o tripé que não pode ser delegado

Segurança começa antes do prompt. Remova acesso em vez de pedir que o agente “tenha cuidado”. Use tokens de curta duração e com escopo mínimo; separe credenciais de leitura e escrita; não disponibilize segredos em logs, prompts ou arquivos de handoff; exija confirmação humana para ações irreversíveis, externas ou financeiras.

Ownership é a regra que impede responsabilidade diluída. Cada mudança deve ter um dono de implementação e um dono de integração. Podem ser a mesma pessoa em uma tarefa pequena; em alteração sensível, não deveriam ser. O líder da equipe é responsável por desfazer sobreposição, mas não deve fingir que mensagens entre teammates são uma transação consistente.

Verificação é a evidência que fecha o loop. Para código, combine o menor conjunto que prova o requisito: teste focal, lint ou typecheck relevante, build quando apropriado, teste de integração e inspeção do diff. Para investigação, a evidência pode ser reprodução, query versionada, log com intervalo temporal ou links para código. A pergunta não é “o agente trabalhou bastante?”. É “qual observação independente sustenta a conclusão?”.

Instrumente a avaliação antes de ampliar a autonomia. A Anthropic recomenda avaliações que acompanhem tarefas multi-turn e mudanças de estado, porque agentes chamam tools, adaptam-se aos resultados intermediários e podem falhar em caminhos que um teste de resposta única não vê. Demystifying evals for AI agents