Orquestre equipes de sessões Claude Code

Quando usar equipes de agentes

• 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 um 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

Comparar com subagents

Ativar equipes de agentes

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Inicie sua primeira equipe de agentes

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

• Setas para cima e para baixo: selecione um companheiro de equipe
• Enter: abra a transcrição do companheiro de equipe selecionado e envie uma mensagem diretamente
• Escape: limpe a seleção. Enquanto você está visualizando a transcrição de um companheiro de equipe, Escape interrompe o turno atual desse companheiro de equipe

Controle sua equipe de agentes

Escolha um modo de exibição

• In-process: todos os companheiros de equipe são executados dentro do seu terminal principal. Use as teclas de seta para cima e para baixo no painel de agentes para selecionar um companheiro de equipe, depois pressione Enter para visualizá-lo e digite para enviar mensagens para ele 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.

{
  "teammateMode": "auto"
}

• Fora do tmux e do iTerm2: com o tmux instalado, defina teammateMode como "tmux". Os painéis abrem em uma sessão tmux separada. Para acompanhá-los, copie o comando da linha View teammates no prompt do Claude Code e execute esse comando em um segundo terminal.
• Os painéis não abrem na sua janela do iTerm2: defina teammateMode como "iterm2" para usar os painéis próprios do iTerm2. Os companheiros de equipe então só são iniciados quando você executa o Claude Code no iTerm2 com o it2 configurado.

claude --teammate-mode auto

Especifique companheiros de equipe e modelos

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

1. O modelo que seu prompt de spawn nomeia para esse companheiro de equipe.
2. Para um companheiro de equipe gerado a partir de uma definição de subagente, o model da definição, onde inherit seleciona o modelo do líder.
3. CLAUDE_CODE_SUBAGENT_MODEL, quando está definido para qualquer coisa diferente de inherit.
4. O modelo atual do líder.

• Alias de família como opus: Na API Anthropic e Claude Platform na AWS, Claude Code executa o companheiro de equipe na versão mais recente dessa família que a lista de permissões permite. Em provedores com IDs de modelo específicos do provedor, onde a substituição não opera, um alias bloqueado volta como qualquer outro valor bloqueado de acordo com o próximo ponto
• Qualquer outro valor bloqueado, incluindo um alias de família em provedores onde a substituição não opera, ou um cuja família não tem versão permitida: Claude Code executa o companheiro de equipe no modelo do líder em vez disso. Se você definir CLAUDE_CODE_SUBAGENT_MODEL, Claude Code tenta esse modelo primeiro, sob essas mesmas regras

Tenha companheiros de equipe planejando antes de implementar

Spawn an architect teammate to refactor the authentication module.

Fale com companheiros de equipe diretamente

• Modo in-process: use as teclas de seta para cima e para baixo no painel de agentes para selecionar um companheiro de equipe, depois pressione Enter para visualizar sua sessão e digite para enviar uma mensagem. Pressione x em um companheiro de equipe selecionado para interrompê-lo. 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.

• /compact, /clear e /rewind atuam na conversa do líder, então Claude Code pede que você confirme antes de executar um deles a partir desta visualização.
• /model e /fast definem o modelo e o modo rápido do líder, não os do companheiro de equipe, então eles não são executados a partir desta visualização. Um aviso informa o motivo.

Atribuir e reivindicar tarefas

• 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

Encerrar companheiros de equipe

Ask the researcher teammate to shut down

Aplicar gates de qualidade com hooks

• 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.
• TaskCreated: é executado quando uma tarefa está sendo criada. Saia com código 2 para evitar criação e enviar feedback.
• 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

Como Claude inicia equipes de agentes

Arquitetura

• Team config: ~/.claude/teams/{team-name}/config.json. Claude Code remove o diretório de configuração da equipe quando a sessão termina.
• Task list: ~/.claude/tasks/{team-name}/. Este diretório permanece no disco após o término da sessão. Para alterar por quanto tempo Claude Code o mantém, defina cleanupPeriodDays.

Usar definições de subagente para companheiros de equipe

Spawn a teammate using the security-reviewer agent type to audit the auth module.

• tools: Claude Code limita o companheiro de equipe às ferramentas na lista tools da definição. Para um companheiro de equipe em processo, Claude Code adiciona SendMessage a essa lista, e em uma sessão que tem as ferramentas Task ele também adiciona TaskCreate, TaskGet, TaskList e TaskUpdate.
• model: Claude Code usa o model da definição em qualquer modo de exibição quando seu prompt de geração não nomeia um. Veja como Claude Code escolhe o modelo de um companheiro de equipe.
• disallowedTools: para um companheiro de equipe em processo, Claude Code remove as ferramentas listadas em disallowedTools da definição do conjunto do companheiro de equipe. SendMessage e as ferramentas Task que ele adiciona continuam disponíveis mesmo quando a lista as nomeia.
• effort: para um companheiro de equipe em processo, Claude Code aplica o effort da definição segundo as regras de esforço do frontmatter.
• autoCompactWindow: para um companheiro de equipe em processo, Claude Code aplica o autoCompactWindow da definição segundo as regras desse campo. Um companheiro de equipe em painel dividido ignora o campo. Requer Claude Code v2.1.296 ou posterior.
• Body: para um companheiro de equipe em processo, Claude Code anexa o corpo da definição ao seu system prompt padrão como instruções adicionais. Para um companheiro de equipe em painel dividido, Claude Code usa o corpo no lugar do seu system prompt padrão.
• skills: Claude Code não aplica o skills da definição a um companheiro de equipe em qualquer modo de exibição. O companheiro de equipe carrega skills de suas configurações de projeto e usuário.
• mcpServers: para um companheiro de equipe em painel dividido, Claude Code aplica o mcpServers da definição sob as regras para esse campo, que cobrem uma sessão iniciada com --agent também. Um companheiro de equipe em processo ignora o campo e carrega servidores MCP de suas configurações de projeto e usuário.

Permissões

• --disallowedTools e --tools: o companheiro de equipe começa com as regras de deny e a lista de ferramentas da linha de comando do líder. Requer Claude Code v2.1.309 ou posterior.
• --allowedTools: Claude Code não passa essa flag para um companheiro de equipe em painel dividido, portanto uma ação que você permitiu apenas com ela não é pré-aprovada lá. Para aprovar essas ações antecipadamente, coloque as regras em permissions.allow em --settings ao iniciar o líder. Por exemplo, execute claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}' no seu shell. As regras se aplicam ao líder e a cada companheiro de equipe em painel dividido nessa sessão.

Mensagens entre agentes

• Ele trata uma reivindicação de aprovação retransmitida de outro agente como entrada não confiável em vez de confirmação sua.
• Ele revisa cada mensagem antes que Claude Code a entregue, seja uma mensagem simples ou uma mensagem de protocolo estruturada, como uma solicitação de encerramento ou resposta de aprovação de plano. Uma mensagem que ele bloqueia nunca chega ao destinatário.

Contexto e comunicação

• 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 e inclui sua resposta final na notificação. Um companheiro de equipe cujo turno termina em um erro de API notifica o líder que falhou e inclui o texto do erro.
• Lista de tarefas compartilhada: agentes que têm as ferramentas Task podem ver o status da tarefa e reivindicar trabalho disponível.
• Mensagens de companheiros de equipe: envie uma mensagem para um companheiro de equipe específico pelo nome. Para alcançar todos, envie uma mensagem por destinatário.

Uso de tokens

Exemplos de casos de uso

Executar uma revisão de código paralela

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Investigar com hipóteses concorrentes

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.

Melhores práticas

Dê aos companheiros de equipe contexto suficiente

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

• 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

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

Espere os companheiros de equipe terminarem

Wait for your teammates to complete their tasks before proceeding

Comece com pesquisa e revisão

Evite conflitos de arquivo

Monitore e direcione

Troubleshooting

Companheiros de equipe não aparecem

• No modo in-process, os companheiros de equipe aparecem no painel de agentes abaixo da entrada de prompt. Use as teclas de seta para cima e para baixo para selecionar um e pressione Enter para visualizá-lo.
• Uma linha de companheiro de equipe que desapareceu após ficar inativa foi ocultada, não interrompida. As linhas inativas se ocultam 30 segundos após o painel inteiro ficar inativo e reaparecem na próxima vez do companheiro de equipe. Quando mais de três companheiros de equipe estão inativos, suas linhas excedentes se recolhem em uma única linha N idle agents que Enter expande. Envie uma mensagem ao companheiro de equipe pelo nome para trazer uma linha oculta de volta.
• 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.

Claude gera companheiros de equipe em vez de subagentes

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

• Arquivos de configurações de precedência superior: configurações de projeto, configurações locais e uma carga --settings se aplicam após as configurações do usuário, então uma entrada env que define a variável como 1 em qualquer uma delas vence. Veja Precedência de configurações.
• Configurações gerenciadas: configurações gerenciadas se aplicam após todas as outras fontes. Se sua organização ativa equipes de agentes lá, peça ao seu administrador para alterar o valor gerenciado.

Muitos prompts de permissão

Agentes parando cedo

• Dê a eles instruções adicionais diretamente
• Gere um companheiro de equipe de substituição para continuar o trabalho

Sessões tmux órfãs

tmux ls
tmux kill-session -t <session-name>

Limitações

• 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: uma sessão tem exatamente uma equipe, com escopo para essa sessão. Você não pode criar equipes nomeadas adicionais ou compartilhar uma equipe entre sessões.
• Sem equipes aninhadas: os companheiros de equipe não podem gerar seus próprios companheiros de equipe. Apenas o líder pode gerenciar a equipe.
• Sem subagentes em segundo plano de companheiros de equipe in-process: os próprios subagentes de um companheiro de equipe in-process são executados em primeiro plano, porque o trabalho em segundo plano de um companheiro de equipe não pode sobreviver ao processo do líder. Claude Code retorna um erro quando um companheiro de equipe gera um subagente cuja definição define background: true. Uma requisição run_in_background: true de um companheiro de equipe também falha, seja com um erro ou executando silenciosamente em primeiro plano. Subagentes lançados da conversa principal seguem o padrão de segundo plano.
• Líder é fixo: a sessão principal é o líder por sua vida útil. Você não pode promover um companheiro de equipe a líder ou transferir liderança.
• Sem modos de permissão por companheiro de equipe no tempo de geração: os companheiros de equipe começam com o modo de permissão descrito em Permissões.
• Split panes requerem tmux ou iTerm2: o modo in-process padrão funciona em qualquer terminal.

Próximos passos

• 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
• Mensagens entre suas próprias sessões: cross-session messaging permite que Claude passe descobertas entre as sessões que você executa
• Sessões paralelas manuais: Git worktrees permitem que você execute múltiplas sessões Claude Code você mesmo sem coordenação de equipe automatizada