Pular para o conteúdo principal
Equipes de agentes são experimentais e desabilitadas por padrão. Ative-as adicionando CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS ao seu settings.json ou ambiente. Equipes de agentes têm limitações conhecidas em torno de retomada de sessão, coordenação de tarefas e comportamento de encerramento.
Equipes de agentes permitem que você coordene múltiplas instâncias Claude Code trabalhando juntas. Uma sessão atua como o líder da equipe, coordenando o trabalho, atribuindo tarefas e sintetizando resultados. Os companheiros de equipe trabalham independentemente, cada um em sua própria context window, e se comunicam diretamente uns com os outros. Diferentemente de subagents, que são executados dentro de uma única sessão e podem apenas relatar de volta ao agente principal, você também pode interagir com companheiros de equipe individuais diretamente sem passar pelo líder.
Equipes de agentes requerem Claude Code v2.1.32 ou posterior. Verifique sua versão com claude --version.
Esta página cobre:

Quando usar equipes de agentes

Equipes de agentes são mais eficazes para tarefas onde a exploração paralela adiciona valor real. Veja exemplos de casos de uso para cenários completos. Os casos de uso mais fortes são:
  • Pesquisa e revisão: múltiplos companheiros de equipe podem investigar diferentes aspectos de um problema simultaneamente, depois compartilhar e desafiar as descobertas uns dos outros
  • Novos módulos ou recursos: companheiros de equipe podem possuir cada uma uma peça separada sem se atrapalharem
  • Depuração com hipóteses concorrentes: companheiros de equipe testam diferentes teorias em paralelo e convergem para a resposta mais rapidamente
  • Coordenação entre camadas: mudanças que abrangem frontend, backend e testes, cada uma de propriedade de um companheiro de equipe diferente
Equipes de agentes adicionam sobrecarga de coordenação e usam significativamente mais tokens do que uma única sessão. Funcionam melhor quando os companheiros de equipe podem operar independentemente. Para tarefas sequenciais, edições no mesmo arquivo ou trabalho com muitas dependências, uma única sessão ou subagents são mais eficazes.

Comparar com subagents

Tanto equipes de agentes quanto subagents permitem que você paralelizar o trabalho, mas operam de forma diferente. Escolha com base em se seus trabalhadores precisam se comunicar uns com os outros:
Diagrama comparando arquiteturas de subagent e equipe de agentes. Subagents são gerados pelo agente principal, fazem trabalho e relatam resultados de volta. Equipes de agentes coordenam através de uma lista de tarefas compartilhada, com companheiros de equipe se comunicando diretamente uns com os outros.
SubagentsAgent teams
ContextContext window própria; resultados retornam ao chamadorContext window própria; totalmente independente
CommunicationRelatam resultados de volta apenas ao agente principalCompanheiros de equipe se mensageiam diretamente
CoordinationAgente principal gerencia todo o trabalhoLista de tarefas compartilhada com auto-coordenação
Best forTarefas focadas onde apenas o resultado importaTrabalho complexo que requer discussão e colaboração
Token costMenor: resultados resumidos de volta ao contexto principalMaior: cada companheiro de equipe é uma instância Claude separada
Use subagents quando você precisa de trabalhadores rápidos e focados que relatem de volta. Use equipes de agentes quando os companheiros de equipe precisam compartilhar descobertas, desafiar uns aos outros e coordenar por conta própria.

Ativar equipes de agentes

Equipes de agentes são desabilitadas por padrão. Ative-as definindo a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS como 1, seja no seu ambiente de shell ou através de settings.json:
settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Inicie sua primeira equipe de agentes

Após ativar equipes de agentes, diga ao Claude para criar uma equipe de agentes e descreva a tarefa e a estrutura da equipe que você deseja em linguagem natural. Claude cria a equipe, gera companheiros de equipe e coordena o trabalho com base no seu prompt. Este exemplo funciona bem porque os três papéis são independentes e podem explorar o problema sem esperar um pelo outro:
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Create an agent team to explore this from different angles: one
teammate on UX, one on technical architecture, one playing devil's advocate.
A partir daí, Claude cria uma equipe com uma lista de tarefas compartilhada, gera companheiros de equipe para cada perspectiva, faz com que explorem o problema, sintetiza descobertas e tenta limpar a equipe quando terminar. O terminal do líder lista todos os companheiros de equipe e no que estão trabalhando. Use Shift+Down para percorrer os companheiros de equipe e envie mensagens para eles diretamente. Após o último companheiro de equipe, Shift+Down volta para o líder. Se você quiser cada companheiro de equipe em seu próprio painel dividido, veja Escolha um modo de exibição.

Controle sua equipe de agentes

Diga ao líder o que você quer em linguagem natural. Ele lida com coordenação de equipe, atribuição de tarefas e delegação com base em suas instruções.

Escolha um modo de exibição

Equipes de agentes suportam dois modos de exibição:
  • In-process: todos os companheiros de equipe são executados dentro do seu terminal principal. Use Shift+Down para percorrer os companheiros de equipe e digite para enviar mensagens para eles diretamente. Funciona em qualquer terminal, nenhuma configuração extra necessária.
  • Split panes: cada companheiro de equipe recebe seu próprio painel. Você pode ver a saída de todos de uma vez e clicar em um painel para interagir diretamente. Requer tmux ou iTerm2.
tmux tem limitações conhecidas em certos sistemas operacionais e tradicionalmente funciona melhor no macOS. Usar tmux -CC no iTerm2 é o ponto de entrada sugerido para tmux.
O padrão é "auto", que usa split panes se você já estiver executando dentro de uma sessão tmux, e in-process caso contrário. A configuração "tmux" ativa o modo split-pane e detecta automaticamente se deve usar tmux ou iTerm2 com base no seu terminal. Para substituir, defina teammateMode no seu settings.json:
{
  "teammateMode": "in-process"
}
Para forçar o modo in-process para uma única sessão, passe como um sinalizador:
claude --teammate-mode in-process
O modo split-pane requer tmux ou iTerm2 com o CLI it2. Para instalar manualmente:
  • tmux: instale através do gerenciador de pacotes do seu sistema. Veja o wiki tmux para instruções específicas da plataforma.
  • iTerm2: instale o CLI it2, depois ative a API Python em iTerm2 → Settings → General → Magic → Enable Python API.

Especifique companheiros de equipe e modelos

Claude decide o número de companheiros de equipe a gerar com base em sua tarefa, ou você pode especificar exatamente o que deseja:
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Exigir aprovação de plano para companheiros de equipe

Para tarefas complexas ou arriscadas, você pode exigir que os companheiros de equipe planejem antes de implementar. O companheiro de equipe trabalha em modo de plano somente leitura até que o líder aprove sua abordagem:
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
Quando um companheiro de equipe termina o planejamento, ele envia uma solicitação de aprovação de plano ao líder. O líder revisa o plano e o aprova ou o rejeita com feedback. Se rejeitado, o companheiro de equipe permanece em modo de plano, revisa com base no feedback e resubmete. Uma vez aprovado, o companheiro de equipe sai do modo de plano e começa a implementação. O líder toma decisões de aprovação autonomamente. Para influenciar o julgamento do líder, dê a ele critérios no seu prompt, como “apenas aprove planos que incluam cobertura de testes” ou “rejeite planos que modifiquem o esquema do banco de dados”.

Fale com companheiros de equipe diretamente

Cada companheiro de equipe é uma sessão Claude Code completa e independente. Você pode enviar mensagens para qualquer companheiro de equipe diretamente para dar instruções adicionais, fazer perguntas de acompanhamento ou redirecionar sua abordagem.
  • Modo in-process: use Shift+Down para percorrer os companheiros de equipe, depois digite para enviar uma mensagem. Pressione Enter para visualizar a sessão de um companheiro de equipe, depois Escape para interromper seu turno atual. Pressione Ctrl+T para alternar a lista de tarefas.
  • Modo split-pane: clique em um painel de companheiro de equipe para interagir com sua sessão diretamente. Cada companheiro de equipe tem uma visualização completa de seu próprio terminal.

Atribuir e reivindicar tarefas

A lista de tarefas compartilhada coordena o trabalho em toda a equipe. O líder cria tarefas e os companheiros de equipe as trabalham. As tarefas têm três estados: pendente, em progresso e concluída. As tarefas também podem depender de outras tarefas: uma tarefa pendente com dependências não resolvidas não pode ser reivindicada até que essas dependências sejam concluídas. O líder pode atribuir tarefas explicitamente ou os companheiros de equipe podem auto-reivindicar:
  • Líder atribui: diga ao líder qual tarefa dar a qual companheiro de equipe
  • Auto-reivindicar: após terminar uma tarefa, um companheiro de equipe pega a próxima tarefa não atribuída e desbloqueada por conta própria
A reivindicação de tarefas usa bloqueio de arquivo para evitar condições de corrida quando múltiplos companheiros de equipe tentam reivindicar a mesma tarefa simultaneamente.

Encerrar companheiros de equipe

Para encerrar graciosamente a sessão de um companheiro de equipe:
Ask the researcher teammate to shut down
O líder envia uma solicitação de encerramento. O companheiro de equipe pode aprovar, saindo graciosamente, ou rejeitar com uma explicação.

Limpar a equipe

Quando você terminar, peça ao líder para limpar:
Clean up the team
Isso remove os recursos compartilhados da equipe. Quando o líder executa a limpeza, ele verifica se há companheiros de equipe ativos e falha se algum ainda estiver em execução, então encerre-os primeiro.
Sempre use o líder para limpar. Os companheiros de equipe não devem executar limpeza porque seu contexto de equipe pode não ser resolvido corretamente, deixando potencialmente recursos em um estado inconsistente.

Aplicar gates de qualidade com hooks

Use hooks para aplicar regras quando os companheiros de equipe terminam o trabalho ou as tarefas são concluídas:
  • TeammateIdle: é executado quando um companheiro de equipe está prestes a ficar ocioso. Saia com código 2 para enviar feedback e manter o companheiro de equipe trabalhando.
  • TaskCompleted: é executado quando uma tarefa está sendo marcada como concluída. Saia com código 2 para evitar conclusão e enviar feedback.

Como funcionam as equipes de agentes

Esta seção cobre a arquitetura e a mecânica por trás das equipes de agentes. Se você quiser começar a usá-las, veja Controle sua equipe de agentes acima.

Como Claude inicia equipes de agentes

Existem duas maneiras pelas quais as equipes de agentes começam:
  • Você solicita uma equipe: dê ao Claude uma tarefa que se beneficie do trabalho paralelo e peça explicitamente uma equipe de agentes. Claude cria uma com base em suas instruções.
  • Claude propõe uma equipe: se Claude determinar que sua tarefa se beneficiaria do trabalho paralelo, pode sugerir criar uma equipe. Você confirma antes que ele proceda.
Em ambos os casos, você permanece no controle. Claude não criará uma equipe sem sua aprovação.

Arquitetura

Uma equipe de agentes consiste em:
ComponentePapel
Team leadA sessão Claude Code principal que cria a equipe, gera companheiros de equipe e coordena o trabalho
TeammatesInstâncias Claude Code separadas que cada uma trabalha em tarefas atribuídas
Task listLista compartilhada de itens de trabalho que os companheiros de equipe reivindicam e completam
MailboxSistema de mensagens para comunicação entre agentes
Veja Escolha um modo de exibição para opções de configuração de exibição. As mensagens dos companheiros de equipe chegam ao líder automaticamente. O sistema gerencia dependências de tarefas automaticamente. Quando um companheiro de equipe completa uma tarefa da qual outras tarefas dependem, as tarefas bloqueadas são desbloqueadas sem intervenção manual. Equipes e tarefas são armazenadas localmente:
  • Team config: ~/.claude/teams/{team-name}/config.json
  • Task list: ~/.claude/tasks/{team-name}/
A configuração da equipe contém um array members com o nome de cada companheiro de equipe, ID do agente e tipo de agente. Os companheiros de equipe podem ler este arquivo para descobrir outros membros da equipe.

Permissões

Os companheiros de equipe começam com as configurações de permissão do líder. Se o líder for executado com --dangerously-skip-permissions, todos os companheiros de equipe também. Após gerar, você pode alterar modos de companheiros de equipe individuais, mas não pode definir modos por companheiro de equipe no tempo de geração.

Context e comunicação

Cada companheiro de equipe tem sua própria context window. Quando gerado, um companheiro de equipe carrega o mesmo contexto de projeto que uma sessão regular: CLAUDE.md, MCP servers e skills. Ele também recebe o prompt de geração do líder. O histórico de conversa do líder não é transferido. Como os companheiros de equipe compartilham informações:
  • Entrega automática de mensagens: quando os companheiros de equipe enviam mensagens, elas são entregues automaticamente aos destinatários. O líder não precisa fazer polling para atualizações.
  • Notificações de ociosidade: quando um companheiro de equipe termina e para, ele notifica automaticamente o líder.
  • Lista de tarefas compartilhada: todos os agentes podem ver o status da tarefa e reivindicar trabalho disponível.
Mensagens de companheiros de equipe:
  • message: envie uma mensagem para um companheiro de equipe específico
  • broadcast: envie para todos os companheiros de equipe simultaneamente. Use com moderação, pois os custos escalam com o tamanho da equipe.

Uso de tokens

Equipes de agentes usam significativamente mais tokens do que uma única sessão. Cada companheiro de equipe tem sua própria context window, e o uso de tokens escala com o número de companheiros de equipe ativos. Para pesquisa, revisão e trabalho de novos recursos, os tokens extras geralmente valem a pena. Para tarefas rotineiras, uma única sessão é mais econômica. Veja custos de token de equipe de agentes para orientação de uso.

Exemplos de casos de uso

Estes exemplos mostram como as equipes de agentes lidam com tarefas onde a exploração paralela adiciona valor.

Executar uma revisão de código paralela

Um único revisor tende a gravitar em torno de um tipo de problema por vez. Dividir critérios de revisão em domínios independentes significa que segurança, desempenho e cobertura de testes recebem atenção completa simultaneamente. O prompt atribui a cada companheiro de equipe uma lente distinta para que não se sobreponham:
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.
Cada revisor trabalha a partir do mesmo PR, mas aplica um filtro diferente. O líder sintetiza descobertas em todos os três após terminarem.

Investigar com hipóteses concorrentes

Quando a causa raiz é incerta, um único agente tende a encontrar uma explicação plausível e parar de procurar. O prompt combate isso tornando os companheiros de equipe explicitamente adversários: o trabalho de cada um não é apenas investigar sua própria teoria, mas desafiar as dos outros.
Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.
A estrutura de debate é o mecanismo-chave aqui. A investigação sequencial sofre de ancoragem: uma vez que uma teoria é explorada, a investigação subsequente é enviesada em relação a ela. Com múltiplos investigadores independentes tentando ativamente desprovar uns aos outros, a teoria que sobrevive é muito mais provável de ser a causa raiz real.

Melhores práticas

Dê aos companheiros de equipe contexto suficiente

Os companheiros de equipe carregam contexto de projeto automaticamente, incluindo CLAUDE.md, MCP servers e skills, mas não herdam o histórico de conversa do líder. Veja Context e comunicação para detalhes. Inclua detalhes específicos da tarefa no prompt de geração:
Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Escolha um tamanho de equipe apropriado

Não há limite rígido no número de companheiros de equipe, mas restrições práticas se aplicam:
  • Custos de token escalam linearmente: cada companheiro de equipe tem sua própria context window e consome tokens independentemente. Veja custos de token de equipe de agentes para detalhes.
  • Sobrecarga de coordenação aumenta: mais companheiros de equipe significa mais comunicação, coordenação de tarefas e potencial para conflitos
  • Retornos decrescentes: além de um certo ponto, companheiros de equipe adicionais não aceleram o trabalho proporcionalmente
Comece com 3-5 companheiros de equipe para a maioria dos fluxos de trabalho. Isso equilibra o trabalho paralelo com coordenação gerenciável. Os exemplos neste guia usam 3-5 companheiros de equipe porque esse intervalo funciona bem em diferentes tipos de tarefas. Ter 5-6 tasks por companheiro de equipe mantém todos produtivos sem alternância de contexto excessiva. Se você tiver 15 tarefas independentes, 3 companheiros de equipe é um bom ponto de partida. Escale apenas quando o trabalho genuinamente se beneficiar de ter companheiros de equipe trabalhando simultaneamente. Três companheiros de equipe focados frequentemente superam cinco dispersos.

Dimensione tarefas apropriadamente

  • Muito pequeno: sobrecarga de coordenação excede o benefício
  • Muito grande: companheiros de equipe trabalham muito tempo sem check-ins, aumentando o risco de esforço desperdiçado
  • Bem dimensionado: unidades auto-contidas que produzem um entregável claro, como uma função, um arquivo de teste ou uma revisão
O líder divide o trabalho em tarefas e as atribui aos companheiros de equipe automaticamente. Se não estiver criando tarefas suficientes, peça a ele para dividir o trabalho em pedaços menores. Ter 5-6 tarefas por companheiro de equipe mantém todos produtivos e permite que o líder reatribua trabalho se alguém ficar preso.

Espere os companheiros de equipe terminarem

Às vezes, o líder começa a implementar tarefas em vez de esperar pelos companheiros de equipe. Se você notar isso:
Wait for your teammates to complete their tasks before proceeding

Comece com pesquisa e revisão

Se você é novo em equipes de agentes, comece com tarefas que têm limites claros e não requerem escrever código: revisar um PR, pesquisar uma biblioteca ou investigar um bug. Essas tarefas mostram o valor da exploração paralela sem os desafios de coordenação que vêm com a implementação paralela.

Evite conflitos de arquivo

Dois companheiros de equipe editando o mesmo arquivo leva a sobrescrita. Divida o trabalho para que cada companheiro de equipe possua um conjunto diferente de arquivos.

Monitore e direcione

Verifique o progresso dos companheiros de equipe, redirecione abordagens que não estão funcionando e sintetize descobertas conforme chegam. Deixar uma equipe executar sem supervisão por muito tempo aumenta o risco de esforço desperdiçado.

Troubleshooting

Companheiros de equipe não aparecem

Se os companheiros de equipe não aparecerem depois que você pedir ao Claude para criar uma equipe:
  • No modo in-process, os companheiros de equipe podem já estar em execução, mas não visíveis. Pressione Shift+Down para percorrer os companheiros de equipe ativos.
  • Verifique se a tarefa que você deu ao Claude era complexa o suficiente para justificar uma equipe. Claude decide se deve gerar companheiros de equipe com base na tarefa.
  • Se você explicitamente solicitou split panes, certifique-se de que tmux está instalado e disponível no seu PATH:
    which tmux
    
  • Para iTerm2, verifique se o CLI it2 está instalado e a API Python está ativada nas preferências do iTerm2.

Muitos prompts de permissão

Solicitações de permissão de companheiros de equipe surgem para o líder, o que pode criar atrito. Pré-aprove operações comuns nas suas configurações de permissão antes de gerar companheiros de equipe para reduzir interrupções.

Companheiros de equipe parando em erros

Os companheiros de equipe podem parar após encontrar erros em vez de se recuperar. Verifique sua saída usando Shift+Down no modo in-process ou clicando no painel no modo split, depois:
  • Dê a eles instruções adicionais diretamente
  • Gere um companheiro de equipe de substituição para continuar o trabalho

Líder encerra antes do trabalho estar pronto

O líder pode decidir que a equipe terminou antes de todas as tarefas estarem realmente completas. Se isso acontecer, diga a ele para continuar. Você também pode dizer ao líder para esperar os companheiros de equipe terminarem antes de prosseguir se ele começar a fazer trabalho em vez de delegar.

Sessões tmux órfãs

Se uma sessão tmux persistir após a equipe terminar, pode não ter sido totalmente limpa. Liste as sessões e mate a criada pela equipe:
tmux ls
tmux kill-session -t <session-name>

Limitações

Equipes de agentes são experimentais. Limitações atuais a serem observadas:
  • Sem retomada de sessão com companheiros de equipe in-process: /resume e /rewind não restauram companheiros de equipe in-process. Após retomar uma sessão, o líder pode tentar enviar mensagens para companheiros de equipe que não existem mais. Se isso acontecer, diga ao líder para gerar novos companheiros de equipe.
  • Status da tarefa pode ficar atrasado: os companheiros de equipe às vezes falham em marcar tarefas como concluídas, o que bloqueia tarefas dependentes. Se uma tarefa parecer presa, verifique se o trabalho está realmente pronto e atualize o status da tarefa manualmente ou diga ao líder para dar um empurrão ao companheiro de equipe.
  • Encerramento pode ser lento: os companheiros de equipe terminam sua solicitação atual ou chamada de ferramenta antes de encerrar, o que pode levar tempo.
  • Uma equipe por sessão: um líder pode gerenciar apenas uma equipe por vez. Limpe a equipe atual antes de iniciar uma nova.
  • Sem equipes aninhadas: os companheiros de equipe não podem gerar suas próprias equipes ou companheiros de equipe. Apenas o líder pode gerenciar a equipe.
  • Líder é fixo: a sessão que cria a equipe é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.
  • Permissões definidas no tempo de geração: todos os companheiros de equipe começam com o modo de permissão do líder. Você pode alterar modos de companheiros de equipe individuais após gerar, mas não pode definir modos por companheiro de equipe no tempo de geração.
  • Split panes requerem tmux ou iTerm2: o modo in-process padrão funciona em qualquer terminal. O modo split-pane não é suportado no terminal integrado do VS Code, Windows Terminal ou Ghostty.
CLAUDE.md funciona normalmente: os companheiros de equipe leem arquivos CLAUDE.md de seu diretório de trabalho. Use isso para fornecer orientação específica do projeto a todos os companheiros de equipe.

Próximos passos

Explore abordagens relacionadas para trabalho paralelo e delegação:
  • Delegação leve: subagents geram agentes auxiliares para pesquisa ou verificação dentro de sua sessão, melhor para tarefas que não precisam de coordenação entre agentes
  • Sessões paralelas manuais: Git worktrees permitem que você execute múltiplas sessões Claude Code você mesmo sem coordenação de equipe automatizada
  • Comparar abordagens: veja a comparação subagent vs agent team para um detalhamento lado a lado