Agent teams do Claude Code vs subagentes: quando usar cada um e como montar uma equipe

Agent teams vs subagentes

Os dois executam trabalho em paralelo em janelas de contexto separadas. A diferença é quem coordena: com subagentes, o agente principal gerencia tudo; em uma equipe, os colegas pegam tarefas de uma lista compartilhada e conversam entre si.

Quando usar agent teams (e quando não usar)

• Pesquisa e revisão: os colegas analisam um problema por ângulos diferentes e depois contestam as conclusões uns dos outros.
• Novos módulos ou funcionalidades: cada colega cuida de uma parte, como frontend, backend e testes.
• Depuração com hipóteses concorrentes: vários colegas tentam provar a própria teoria e derrubar as dos outros.
• Não para trabalho sequencial, edições nos mesmos arquivos ou tarefas com muitas dependências: nesses casos, use uma única sessão ou subagentes.
• Não para trabalho rotineiro: o uso de tokens cresce a cada colega ativo.

Como montar um agent team no Claude Code

1. Ative os agent teams

   Defina CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS como 1 no seu ambiente ou no bloco env do settings.json. As equipes precisam de uma sessão interativa; com -p (e com o Agent SDK) o Claude não cria colegas.

   // settings.json: agent teams are experimental and off by default
   {
     "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
   }
   
   // Optional: give each teammate its own split pane (tmux or iTerm2)
   {
     "teammateMode": "auto"
   }

2. Descreva a equipe em linguagem natural

   Diga quantos colegas quer e o que cada um faz. O Claude cria a lista de tarefas compartilhada, inicia os colegas e sintetiza as conclusões quando eles terminam.

   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.

3. Escolha um modo de exibição

   O modo in-process é o padrão e funciona em qualquer terminal: os colegas aparecem em um painel abaixo do prompt; use as setas e Enter para abrir um e mandar mensagem, e Ctrl+T para a lista de tarefas. Os painéis divididos dão a cada colega seu próprio painel e exigem tmux ou iTerm2 com a CLI it2; defina teammateMode como auto ou tmux, ou inicie com claude --teammate-mode auto.

4. Reaproveite papéis que você já definiu

   Peça um colega “usando o tipo de agente security-reviewer” para reaproveitar uma definição de subagente de .claude/agents/, com suas ferramentas, modelo e instruções.

5. Oriente e depois encerre

   Acompanhe os colegas, redirecione-os e diga “espere seus colegas” se o líder começar a fazer o trabalho deles. Para terminar, peça ao líder que encerre um colega pelo nome; os diretórios da equipe são limpos quando a sessão termina.

Fonte: documentação do Claude Code, Agent teams

Boas práticas e limitações

• Comece com 3–5 colegas e cerca de 5–6 tarefas para cada um; três colegas focados costumam render mais que cinco dispersos.
• Dê a cada colega um conjunto diferente de arquivos: dois colegas editando o mesmo arquivo sobrescrevem um ao outro.
• Coloque os detalhes da tarefa no prompt de criação: os colegas carregam o CLAUDE.md, os servidores MCP e as skills, mas não a conversa do líder.
• Use hooks como portões de qualidade: TeammateIdle, TaskCreated e TaskCompleted podem devolver o trabalho com o código de saída 2.
• Limites: uma equipe por sessão, sem equipes aninhadas, o líder não pode mudar, o /resume não traz de volta colegas in-process e o status das tarefas pode atrasar.
• Os painéis divididos não funcionam no terminal integrado do VS Code, no Windows Terminal nem no Ghostty; o modo in-process funciona em qualquer lugar.
• Com os agent teams ativados, um subagente que o Claude nomeia pode ser iniciado como colega; defina a variável como 0 se quiser os subagentes comuns de volta.

Agent teams vs outras formas de rodar o Claude Code em paralelo

Os agent teams dividem uma tarefa que você está acompanhando, dentro de uma única sessão. Para tarefas independentes, rode sessões separadas em git worktrees ou como agentes em segundo plano; para uma comparação completa, leia vários agentes do Claude Code. Para reduzir o custo, veja como reduzir o uso de tokens do Claude Code.

Uma equipe que continua trabalhando depois que a sessão termina

Um agent team vive dentro de uma sessão e para quando você a fecha. O Crewmark transforma sessões do Claude Code, Codex, DeepSeek Harness ou OpenCode em funcionários de IA com papéis, metas e horários de trabalho duradouros: cada um acorda com um heartbeat, pega a próxima issue de um quadro compartilhado e manda mensagem quando precisa de uma decisão.

1. Dê um papel a cada funcionário

   Um engenheiro de software, um revisor, um especialista em SEO: os papéis que você criaria como colegas, mas permanentes.

2. Trabalhe a partir de um único quadro

   As issues substituem a lista de tarefas da sessão e sobrevivem a reinícios, dias e semanas.

3. Deixe o heartbeat iniciar o trabalho

   A cada 15, 30 ou 60 minutos durante o horário de trabalho; veja o que é um funcionário de IA.

Perguntas frequentes sobre agent teams no Claude Code