Equipas de Agentes do Claude Code

Problema: Uma refatoração complexa abrange a API, migrações de base de dados, cobertura de testes e documentação. Uma sessão do Claude Code percorre o trabalho de forma linear. Os subagentes podem distribuir tarefas, mas só comunicam com o agente principal. Não trocam notas entre si, não se questionam mutuamente, nem coordenam diretamente. No momento em que os teus trabalhadores de IA precisam de colaborar a sério, os subagentes chegam ao limite.

Solução rápida: Ativa as Equipas de Agentes e descreve a equipa que queres num único prompt:

# Add to your environment or settings.json
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Depois diz ao Claude:

Create an agent team to refactor the payment module. Spawn three teammates:
one for the API layer, one for the database migrations, one for test coverage.
Have them coordinate through the shared task list.

Um líder de equipa é criado, três companheiros entram nos seus próprios escopos, e partilham uma lista de tarefas e uma caixa de mensagens. Cada um gere a sua área. Sem colisões. Sem silêncios.

Nota sobre terminologia: A funcionalidade aqui é as Equipas de Agentes integradas no Claude Code, um sistema experimental lançado pela Anthropic. Se quiseres uma configuração de construtor-validador feita por ti com a ferramenta Task, isso está na orquestração de equipas com cadeias construtor-validador. Ambas chegam ao trabalho multi-agente. Por baixo, funcionam de forma completamente diferente.

Essa distinção é o ponto central desta página. Se um agente principal pode coordenar especialistas e recolher as suas respostas, começa com Fundamentos de Agentes e Padrões de Agentes. Lê esta página quando os companheiros precisam de comunicar entre si, questionar-se mutuamente e coordenar sem encaminhar cada mensagem de volta para um tópico principal.

O Que São Realmente as Equipas de Agentes

As Equipas de Agentes é um modo experimental que corre várias sessões do Claude Code no mesmo projeto, em conjunto. Uma sessão torna-se o líder. O líder distribui tarefas, mantém o trabalho alinhado e consolida os resultados. Cada outro companheiro corre na sua própria janela de contexto e pode enviar mensagens a qualquer outro companheiro diretamente.

A diferença em relação aos subagentes está na comunicação. Um subagente vive dentro de uma sessão principal e só pode enviar a sua resposta de volta a esse pai. Descobertas a meio da tarefa ficam presas. A coordenação entre dois subagentes passa sempre pelo agente principal. As Equipas de Agentes eliminam esse salto. Os companheiros enviam mensagens diretos uns aos outros, retiram tarefas de uma lista partilhada e debatem problemas em tempo real. Podes entrar na sessão de qualquer companheiro sem pedir autorização ao líder.

Uma imagem útil: os subagentes são freelancers a quem envias trabalhos separados. Uma Equipa de Agentes é uma equipa na mesma sala, cada um na sua parte, mantendo-se sincronizados por conversação. É a diferença entre uma fila de trabalhos e uma equipa a sério.

Porque É Que Isso Importa Agora

A Anthropic lançou as Equipas de Agentes como experimental juntamente com o lançamento do Opus 4.6, e marca um passo real à frente no trabalho agêntico. Developers independentes tinham estado a montar configurações semelhantes durante meses usando projetos como OpenClaw e scripts de orquestração feitos à mão. O Claude Code agora tem o padrão integrado.

Três razões pelas quais isso importa:

1. Integrado é melhor que colado. As listas de tarefas partilhadas, a caixa de mensagens e o ciclo de vida dos companheiros fazem parte do Claude Code em si. Nada externo. Nada frágil.

2. O multi-agente está a crescer. Developers que ganhem experiência com equipas de agentes agora vão ter uma vantagem séria à medida que as ferramentas continuam a evoluir. A diferença entre "usa o Claude Code" e "corre equipas no Claude Code" está prestes a crescer.

3. Projetos complexos precisam de comunicação, não apenas de divisão. Dividir tarefas dá-te trabalho paralelo. As Equipas de Agentes dão-te trabalho paralelo mais coordenação ao vivo, onde os companheiros trocam contexto, questionam decisões e chegam a respostas mais fortes juntos.

Quando Usar Equipas de Agentes

Correr uma equipa custa tokens reais e adiciona sobrecarga de coordenação em cima de uma sessão única. O encaixe é mais forte quando cada companheiro pode ter uma fatia distinta do trabalho mas ainda beneficia da conversa de grupo.

Casos de Uso Fortes

• Pesquisa e revisão: Diferentes companheiros investigam diferentes ângulos de um problema, depois comparam notas e identificam falhas nas descobertas uns dos outros
• Novos módulos ou funcionalidades: Cada companheiro fica com um componente sem sobreposição de ficheiros
• Depuração com hipóteses concorrentes: Cada companheiro testa uma teoria diferente em paralelo e tenta ativamente refutar as outras
• Coordenação entre camadas: Uma mudança que abrange frontend, backend e testes, com um companheiro por camada
• Debate e consenso: Vários companheiros argumentam posições opostas sobre uma decisão arquitetural e convergem para a mais forte
• Inventário ou classificação em larga escala: Os companheiros dividem um conjunto de dados grande e processam as suas fatias de forma independente

Para modelos de prompts e mais de 10 cenários trabalhados cobrindo marketing, pesquisa e trabalhos fora do desenvolvimento, vê os Casos de Uso e Modelos de Prompts de Equipas de Agentes.

Quando as Equipas Valem o Custo

As Equipas de Agentes não são apenas "mais agentes." São uma camada de coordenação, e essa camada só vale a pena pagar quando a colaboração em si muda o resultado.

As equipas geralmente valem a pena quando:

• cada companheiro pode ter uma área distinta
• descobertas numa área vão mudar o que outro companheiro deve fazer
• comparar pontos de vista faz parte do trabalho
• o trabalho seria significativamente mais lento ou mais fraco se encaminhado apenas por um tópico principal

As equipas geralmente não valem a pena quando:

• um agente podia terminar o trabalho sem problemas
• o trabalho é maioritariamente sequencial
• todos estariam a editar os mesmos ficheiros
• só precisas de vários resultados independentes e um resumo

Esse último caso é onde os subagentes ainda ganham. Se os trabalhadores não precisam de comunicar, não pagues por um sistema construído em torno da comunicação.

Quando Saltar

Trabalho sequencial, edições no mesmo ficheiro, ou qualquer coisa com dependências apertadas: uma sessão única ou um padrão de subagentes custa menos e corre de forma mais limpa. Se os trabalhadores não precisam de comunicar, a camada de coordenação é puro desperdício. Para edições paralelas que são genuinamente independentes, /batch é mais simples e gere o isolamento de worktree por ti. Os fluxos assíncronos cobrem execuções paralelas básicas sem a camada de colaboração por cima. Para armadilhas comuns e como evitá-las, vê as nossas melhores práticas de equipas de agentes.

Subagentes vs Equipas de Agentes: Escolher a Ferramenta Certa

Ambos paralelizam o trabalho. Operam em camadas diferentes. A pergunta que decide: os teus trabalhadores precisam realmente de comunicar entre si?

Os subagentes são ideais quando precisas de trabalhadores rápidos e específicos que devolvem um resultado. As equipas são ideais quando esses trabalhadores precisam de partilhar contexto, questionar-se uns aos outros e coordenar por conta própria. Em projetos grandes, usa ambos: planeia primeiro para definir papéis e limites, depois corre uma equipa para a execução.

Sobre como os subagentes são encaminhados inicialmente, vê as melhores práticas de subagentes.

Passo a Passo: A Tua Primeira Equipa

Na prática, os companheiros aparecem em 20 a 30 segundos e começam a produzir resultados dentro do primeiro minuto. Uma execução com 3 companheiros consome aproximadamente 3 a 4 vezes os tokens de uma sessão única a fazer o mesmo trabalho em sequência. Em tarefas complexas, a poupança de tempo paga isso facilmente.

Passo 1: Ativar

Define a variável de ambiente no teu shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Ou adiciona ao teu settings.json para que persista entre sessões:

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

Passo 2: Descreve o Trabalho e a Equipa

Usa linguagem simples. Sê específico sobre quem faz o quê:

Create an agent team to review our authentication system. Spawn three teammates:
- Security reviewer: audit for vulnerabilities, check token handling
- Performance analyst: profile response times, identify bottlenecks
- Test coverage checker: verify edge cases, find untested paths
Have them share findings and coordinate through the task list.

O Que Colocar no Briefing da Equipa

O primeiro prompt de equipa importa mais do que a maioria das pessoas pensa. Um briefing vago cria colaboração vaga.

Um briefing forte inclui:

• o objetivo geral
• os papéis dos companheiros
• limites de ficheiros ou sistemas
• o que os companheiros devem coordenar
• o que conta como terminado

Exemplo:

Create an agent team to ship the billing refactor.

Team:
- API teammate: own route handlers and webhook flow
- Data teammate: own schema, migrations, and backfills
- Test teammate: own integration coverage and failure cases

Coordination points:
- align on the event model before code changes
- flag any contract mismatch immediately
- do not edit the same file without discussing it first

Done means:
- migrations apply cleanly
- webhook flow still passes
- billing test suite is green

Esse prompt dá à equipa papéis, limites, pontos de comunicação e uma linha de chegada. Sem isso, "coordenar" geralmente significa apenas "falar muito."

Passo 3: Observa a Equipa Formar-se e Guia Quando Necessário

O Claude transforma a tua sessão no líder, cria os companheiros e coloca tarefas na lista partilhada. O Claude também pode sugerir uma equipa por conta própria se achar que o teu pedido se encaixa. De qualquer forma, o controlo é teu.

Usa atalhos de teclado para observar e guiar: Shift+Cima/Baixo para escolher um companheiro, Ctrl+T para a lista de tarefas, Enter para entrar numa sessão, Escape para interromper.

Passo 4: Limpar

Quando o trabalho terminar, encerra a equipa:

Ask all teammates to shut down, then clean up the team.

Faz sempre a limpeza pelo líder. Os companheiros terminam primeiro porque o líder não vai limpar enquanto algum companheiro ainda estiver ativo.

Para detalhes sobre modos de visualização, modo delegado, aprovação de planos, hooks, atribuição de tarefas e custos de tokens, vê os Controlos Avançados de Equipas de Agentes.

Arquitetura: Como as Peças Se Encaixam

Quatro componentes formam uma equipa:

A equipa e a sua configuração ficam no disco localmente:

• Configuração da equipa: ~/.claude/teams/{team-name}/config.json
• Lista de tarefas: ~/.claude/tasks/{team-name}/

Cada companheiro tem a sua própria janela de contexto. No momento da criação, um companheiro carrega o mesmo contexto de projeto que qualquer sessão normal do Claude Code carregaria: o teu CLAUDE.md, servidores MCP e skills. Também lê o prompt de criação do líder. O que não herda é o histórico de conversa do líder.

A comunicação baseia-se em entrega automática de mensagens, notificações de inatividade, a lista de tarefas partilhada, mensagens diretas (apenas para um companheiro) e transmissões (para todos de uma vez, usadas com cuidado porque o custo escala com o tamanho da equipa).

Os companheiros herdam as definições de permissão do líder no momento da criação. Podes alterar o modo de um companheiro específico após a criação, não no momento da criação.

Para tirar mais partido do CLAUDE.md numa configuração de equipa, orientar o comportamento da equipa e manter os custos de tokens razoáveis, vê os Controlos Avançados de Equipas de Agentes.

Aprofundar

Esta é a página central. Três guias complementares vão mais fundo em partes específicas:

• Controlos Avançados: Modos de visualização, modo delegado, aprovação de planos, hooks de portão de qualidade, atribuição de tarefas, gestão de custos de tokens e otimização do CLAUDE.md para equipas
• Casos de Uso e Modelos de Prompts: Mais de 10 cenários reais com prompts prontos para revisão de código, depuração, funcionalidades full-stack, decisões de arquitetura, campanhas de marketing e um percurso progressivo para começar
• Melhores Práticas e Resolução de Problemas: Práticas testadas em combate, comportamento do modo plano, guia de resolução de problemas, limitações atuais e correções recentes do v2.1.33 ao v2.1.45
• Fluxo de Trabalho End-to-End: O pipeline completo de 7 passos desde a ideia inicial até à produção: planeamento, cadeias de contratos, execução por ondas e validação pós-construção

Se queres que o trabalho interativo pareça ainda mais rápido enquanto uma equipa está a correr, vê o Fast Mode para respostas 2.5x mais rápidas no Opus 4.6.

Coordenação à Escala

À medida que as tuas equipas ficam maiores, a pergunta difícil muda de "consigo paralelizar isto?" para "como é que realmente giro a orquestração?" Três padrões têm peso à escala:

1. Modelos de prompts de criação reutilizáveis. Mantém uma pequena biblioteca de formas de prompt para as tuas formações mais comuns (equipa de revisão, equipa de construção, equipa de pesquisa). Cada uma define papéis, limites de ficheiros e critérios de conclusão para que nada precise de ser reconstruído a cada sessão. Para o fluxo de trabalho em que esses modelos se encaixam, vê o guia de fluxo de trabalho end-to-end.

2. Predefinições de permissão. Pré-aprova as tuas operações mais comuns nas definições de permissão antes de criares a equipa. Caso contrário, uma equipa nova afoga-se em pedidos de aprovação nos primeiros dez minutos.

3. CLAUDE.md como contexto de execução partilhado. Um CLAUDE.md bem definido com limites de módulos, comandos de verificação e contexto operacional reduz o custo de exploração por companheiro. Três companheiros a ler um CLAUDE.md claro é muito mais barato do que três companheiros a explorar o codebase de forma independente.

O Espectro Multi-Agente

As Equipas de Agentes ficam numa extremidade de um conjunto de padrões multi-agente dentro do Claude Code. Saber onde cada um se encaixa ajuda-te a escolher:

Combina conforme necessário. Corre uma equipa para a fase de exploração colaborativa, depois muda para pares construtor-validador quando chegares à implementação e precisares de portões de qualidade rígidos. Sessões de equipa longas vivem e morrem pelas mesmas estratégias de contexto que qualquer fluxo de trabalho multi-agente usa.

A experiência com equipas de agentes agora acumula-se à medida que as ferramentas multi-agente crescem. Começa com uma tarefa de revisão esta semana. O custo é pequeno, e a forma como pensas sobre trabalho complexo vai mudar assim que vires os companheiros a coordenar de verdade.