Claude Code Agent Teams: Configuração, Dicas e Casos de Uso

Claude Code Agent Teams: Configuração, Dicas e Casos de Uso

Eu torrei um orçamento de $47 em tokens em dezenove minutos. Quatro agentes, todos rodando Opus 4.6, todos trabalhando no mesmo codebase Next.js, todos editando layout.tsx ao mesmo tempo.

O orquestrador não sinalizou o conflito. O agente de front-end sobrescreveu o wrapper de autenticação do agente de back-end. O agente de QA testou uma versão do arquivo que já não existia mais. E o agente de design -- aquele que eu criei para "dar um polimento na UI" -- introduziu uma classe Tailwind que quebrou o grid responsivo que o agente de front-end tinha passado oito minutos construindo.

Dezenove minutos. Quarenta e sete dólares. Um codebase pior do que quando eu comecei.

Isso foi em fevereiro de 2026. Eu tinha acabado de habilitar o Claude Code agent teams pela primeira vez, e cometi todos os erros que a documentação avisa -- além de alguns que ela não menciona. Desde então, rodei agent teams em mais de trinta projetos reais, desde dashboards SaaS até migrações de API e um pipeline de conteúdo que agora alimenta o blog que você está lendo. A funcionalidade saiu de "desastre caro" para a ferramenta mais poderosa no meu fluxo de desenvolvimento.

Este é o guia que eu gostaria que existisse quando comecei. Não a versão de marketing. Não o quickstart de três parágrafos. O panorama completo -- configuração, ajustes, mais de 30 dicas aprendidas na dor, e os seis casos de uso onde agent teams genuinamente superam tudo o que eu já tentei.

O Que Agent Teams Realmente São (e Por Que Sub-Agents Não São Suficientes)

Antes de mexer em qualquer configuração, você precisa de um modelo mental mais preciso do que "múltiplos agentes trabalhando juntos." A distinção entre sub-agents e agent teams é a diferença entre contratar freelancers e montar um esquadrão -- e confundir os dois vai custar dinheiro de verdade.

Sub-agents são instâncias independentes do Claude Code criadas pela sua sessão principal. Cada um recebe sua própria janela de contexto. Cada um executa sua tarefa e reporta de volta ao pai. O detalhe crucial: sub-agents não conseguem conversar entre si. Eles reportam para o orquestrador, ponto final. Se o Agente A descobre que o schema do banco precisa de uma nova coluna, o Agente B não vai saber disso a menos que você transmita essa informação manualmente.

Agent teams adicionam uma camada de comunicação em cima disso. Teammates podem enviar mensagens diretamente uns aos outros. O agente de front-end pode perguntar ao agente de back-end "qual formato o endpoint /users retorna?" e receber uma resposta sem passar pelo orquestrador. Um agente atua como líder da equipe -- coordenando, delegando, sintetizando -- enquanto os teammates trabalham de forma independente mas permanecem conectados através de troca de mensagens.

Aqui vai a analogia que finalmente fez sentido para mim: sub-agents são e-mail. Você envia instruções, eles enviam resultados de volta. Agent teams são Slack. Todo mundo está no mesmo canal, mensagens fluem em tempo real, e o líder do projeto mantém tudo nos trilhos.

As implicações são práticas e imediatas. Sub-agents funcionam perfeitamente para tarefas que são genuinamente independentes -- rodar linting, gerar documentação, montar testes. Sem necessidade de coordenação, sem contexto compartilhado, sem mensagens trocadas. Rápido e barato.

Agent teams brilham quando o trabalho é interdependente. Quando o front-end precisa saber o contrato da API antes de construir as chamadas fetch. Quando o agente de QA precisa da estrutura real dos componentes para escrever testes significativos. Quando uma mudança no schema do banco precisa se propagar pelo entendimento de cada agente sobre o sistema.

Vou mostrar o processo exato de configuração a seguir, mas essa distinção deve guiar cada decisão que você tomar daqui em diante. Se suas tarefas não precisam de coordenação, agent teams são uma forma cara de fazer algo que sub-agents resolvem por uma fração do custo.

A Configuração Completa: Do Zero ao Time Rodando

Agent teams ainda estão marcados como experimentais no Claude Code em março de 2026. Isso significa que você precisa fazer opt-in, e o comportamento da funcionalidade pode mudar entre versões. Aqui está a sequência exata que eu sigo em uma configuração do zero.

Passo 1: Habilite a Flag Experimental

Abra seu arquivo de configurações do Claude Code. No macOS, ele fica em ~/.claude/settings.json. Adicione a flag experimental de agent teams:

{
  "experimental": {
    "agentTeams": true
  }
}

Você também pode definir a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 se preferir não mexer no arquivo de configurações. Eu uso o arquivo de configurações porque ele persiste entre sessões de terminal sem poluir meu perfil de shell.

Passo 2: Escolha Seu Modo de Exibição

Essa decisão tem um impacto maior no seu fluxo de trabalho do que você imagina. Agent teams suportam dois modos de renderização:

Modo tmux split-pane dá a cada teammate seu próprio painel no terminal. Você vê todos os agentes trabalhando simultaneamente, lado a lado. Você pode clicar em qualquer painel e interagir com aquele agente específico diretamente. Esta é minha configuração preferida para projetos complexos -- o feedback visual é inestimável.

Requisitos: tmux instalado (brew install tmux no macOS), e você deve iniciar o Claude Code de dentro de uma sessão tmux. Comece com tmux new -s dev, depois lance o Claude Code dentro dessa sessão.

Modo in-process roda tudo dentro de uma única janela de terminal. A saída dos teammates aparece inline, e você interage com os agentes através do líder. Menos overhead visual, funciona em qualquer lugar, mas é mais difícil acompanhar o que cada agente está fazendo em tempo real.

Configure isso nas suas configurações:

{
  "teammateMode": "tmux"
}

As opções são "tmux", "in-process", ou "auto" (que usa tmux por padrão se detectar uma sessão tmux, senão usa in-process).

Uma pegadinha que me pegou: o modo split-pane não funciona no terminal integrado do VS Code, no Windows Terminal, nem no Ghostty. Se você está usando um desses, fique com in-process ou mude para um terminal standalone. Eu uso o iTerm2, que também suporta split panes nativamente através de sua Python API -- instale o CLI it2 e habilite a Python API nas configurações do iTerm2.

Passo 3: Defina os Papéis da Equipe Usando Linguagem Natural

É aqui que agent teams divergem dos frameworks de orquestração tradicionais. Você não escreve arquivos de configuração para cada agente. Você descreve sua equipe para o agente líder em português simples.

Aqui está um prompt real que usei para um projeto SaaS recente:

I need a team of 4 agents for this project:

1. Lead (you) - Architecture decisions, task delegation, integration review
2. Frontend specialist - React, TypeScript, Tailwind, component architecture
3. Backend specialist - Node.js, Express, PostgreSQL, API design
4. QA specialist - Testing, validation, integration checks

Rules:
- Frontend and backend must agree on API contracts before building
- QA writes tests only after receiving the actual implementation
- Nobody touches files outside their domain without lead approval

O agente líder cria os teammates com base na sua descrição. Cada teammate recebe sua própria janela de contexto (aproximadamente 200K tokens no Opus 4.6) e sua especialidade atribuída.

Passo 4: Atribua Modelos Estrategicamente

Esta é a maior alavanca de custo que você tem. Nem todo agente precisa do Opus 4.6. Minha atribuição padrão de modelos:

Uma equipe de quatro agentes rodando todos em Opus custa aproximadamente 4x o que uma equipe com modelos mistos custa. A diferença de qualidade para tarefas de execução -- escrever componentes React, construir endpoints CRUD, montar testes -- é insignificante entre Opus e Sonnet. Guarde o Opus para o raciocínio que realmente precisa dele.

Passo 5: Planeje Antes de Executar

Isso é inegociável. Antes que a equipe escreva uma única linha de código, use o modo de planejamento para mapear o trabalho. O modo de planejamento é barato -- é um agente pensando na abordagem. O modo de execução com uma equipe completa é caro -- são quatro agentes consumindo tokens em paralelo.

Meu fluxo de trabalho: ativo o modo de planejamento com o agente líder, obtenho uma decomposição completa de tarefas e um plano de arquitetura, reviso, ajusto, e só então mudo para execução com a equipe completa. Isso cria um checkpoint antes de você comprometer tokens de verdade.

Pense assim: o modo de planejamento é a planta arquitetônica. A execução do agent team é a equipe de construção. Você não mandaria uma equipe para a obra sem plantas. Mesmo princípio, meio diferente.

Mais de 30 Dicas Que Me Economizaram Milhares em Tokens

Venho colecionando essas dicas desde fevereiro. Algumas vêm dos meus próprios erros caros. Outras de padrões que percebi ao longo de dezenas de projetos. Agrupei por categoria porque uma lista corrida de 30 itens é impossível de colocar em prática.

Composição da Equipe

1. Comece com 3 agentes, não 5. O overhead de coordenação entre agentes escala de forma não-linear. Três agentes conseguem se coordenar de forma eficiente. Cinco agentes gastam uma porcentagem significativa dos seus tokens apenas conversando entre si. Eu começo todo projeto com três e só adiciono um quarto se a carga de trabalho claramente exigir.

2. Todo agente precisa de um limite de domínio claro. "Agente de front-end" é claro. "Agente auxiliar" não é. Se você não consegue descrever o domínio de um agente em uma frase, o papel não está bem definido e o agente vai invadir o território de outros agentes.

3. O agente líder deve ser o seu modelo mais caro. O líder toma decisões arquiteturais, resolve conflitos entre teammates, e mantém a visão holística do projeto. Economizar no raciocínio aqui causa erros caros em todo o resto.

4. Combine a capacidade do modelo com a complexidade da tarefa. Escrever testes unitários não requer raciocínio nível Opus. Projetar um schema de banco de dados com relacionamentos complexos, sim. Atribua modelos com base na demanda cognitiva do papel, não com um "tudo recebe o melhor modelo" genérico.

5. Não crie uma equipe para trabalho sequencial. Se a Tarefa B não pode começar até a Tarefa A terminar, você não precisa de dois agentes -- precisa de um agente fazendo duas coisas. Agent teams compensam quando as tarefas podem rodar em paralelo.

Planejamento de Tarefas

6. Limite as tarefas a 5-6 por agente. Descobri que esse é o ponto ideal. Menos de 3 e você está subutilizando o agente. Mais de 7 e o agente perde o controle do próprio progresso, começa a repetir trabalho, ou esquece decisões anteriores.

7. Escreva descrições de tarefas como se estivesse orientando um prestador novo. Inclua o que construir, quais restrições se aplicam, quais arquivos mexer, e quais arquivos evitar. Tarefas ambíguas produzem resultados ambíguos -- e esses resultados custam tokens para corrigir.

8. Defina critérios de sucesso para cada tarefa. "Construir o sistema de auth" é vago. "Construir auth baseado em JWT com refresh tokens, retornando 401 para tokens expirados e suportando acesso baseado em roles para papéis admin/user/viewer" diz ao agente exatamente quando ele terminou.

9. Planeje os pontos de integração antes de dividir o trabalho. O agente líder deve produzir um contrato compartilhado -- schemas de API, modelos de banco, definições de tipos, formatos de eventos -- antes que qualquer teammate comece a construir. Isso elimina a maioria dos problemas de integração.

10. Priorize o pensamento, deixe a construção para depois. Gaste 20% da sua sessão em planejamento e 80% em execução. A maioria das pessoas inverte essa proporção e paga por isso em retrabalho.

Comunicação e Contexto

11. O compartilhamento de contexto é limitado à troca de mensagens. Agentes não compartilham memória nem janelas de contexto. Se o Agente A descobre algo que o Agente B precisa saber, essa informação deve ser enviada explicitamente como mensagem. Nada é automático.

12. Alimente os teammates com contexto crítico logo de cara. Quando você define os papéis da equipe, inclua as decisões arquiteturais chave, a stack de tecnologia e as restrições no prompt inicial. Cada token gasto em contexto inicial economiza dez tokens em comportamento confuso do agente depois.

13. Defina protocolos de comunicação explícitos. Não deixe os agentes trocarem mensagens livremente. Defina pontos de handoff: "Agente de front-end envia expectativas de API ao agente de back-end antes de escrever chamadas fetch." "Agente de back-end compartilha o contrato final de endpoints com o QA antes dos testes serem escritos." Estrutura previne ruído.

14. Use o agente líder como roteador, não como gargalo. O líder deve delegar e revisar, não retransmitir cada mensagem entre teammates. A comunicação direta entre agentes existe por um motivo -- se toda comunicação passa pelo líder, você recriou o modelo de sub-agents mas com mais overhead.

15. Mantenha as mensagens entre agentes concisas. Um agente enviando toda sua saída de código para outro agente desperdiça tokens nos dois lados. Mensagens devem conter decisões, contratos e definições de interface -- não implementações completas.

Gerenciamento de Arquivos e Conflitos

16. Nunca deixe dois agentes editarem o mesmo arquivo simultaneamente. Esse é o erro que me custou $47 em dezenove minutos. Conflitos de arquivo em agent teams são silenciosos -- não existe diálogo de merge conflict. Um agente simplesmente sobrescreve o trabalho do outro. Atribua propriedade de arquivos explicitamente.

17. Crie um mapa de propriedade de arquivos. Antes da execução começar, o agente líder deve produzir um mapeamento claro: "Agente de front-end é dono de tudo em /src/components e /src/hooks. Agente de back-end é dono de /src/api e /src/db. QA é dono de /tests." Áreas cinzentas causam colisões.

18. Use um diretório compartilhado de tipos ou contratos. Eu crio um diretório /src/shared ou /src/contracts que tanto o agente de front-end quanto o de back-end leem, mas apenas o agente líder escreve. Isso evita divergência de contratos.

19. Se um agente precisa modificar o arquivo de outro agente, passe pelo líder. O líder revisa a mudança, confirma que não conflita, e ou faz a alteração ele mesmo ou aprova explicitamente o agente solicitante a prosseguir. Isso adiciona alguns segundos de latência mas evita minutos de debugging.

Controle de Custos

20. Monitore o uso de tokens ativamente, não passivamente. Não espere até a sessão terminar para checar sua conta. O Claude Code mostra o consumo de tokens em tempo real. Se um agente está queimando tokens mais rápido do que o esperado, algo está errado -- provavelmente está preso em um loop ou gerando output excessivo.

21. Encerre agentes ociosos imediatamente. Um agente que terminou suas tarefas mas ainda está rodando continua consumindo recursos. O orquestrador cuida da limpeza, mas já vi agentes ficarem ociosos por minutos antes de serem terminados. Encerramento manual é mais rápido e mais barato.

22. Use sub-agents para tarefas independentes, teams para interdependentes. Não canso de repetir isso. Rodar quatro agentes coordenados para fazer quatro tarefas independentes é como marcar uma reunião que poderia ter sido quatro e-mails. Use sub-agents para trabalho isolado. Reserve agent teams para trabalho que genuinamente requer coordenação.

23. Agrupe tarefas relacionadas. Em vez de criar um novo agente para cada tarefa pequena, agrupe tarefas relacionadas sob um agente. Um agente cuidando de "construir todos os três endpoints de API para gerenciamento de usuários" é mais eficiente do que três agentes cada um construindo um endpoint.

24. Faça uma estimativa de custo antes de se comprometer. Conta rápida: uma equipe de 3 agentes rodando por 30 minutos no Opus 4.6 consome aproximadamente 200K-300K tokens. No preço atual, isso dá $15-25. Em uma equipe com modelos mistos (um Opus, dois Sonnet), a mesma sessão custa $6-10. Conheça seus números antes de começar.

Monitoramento e Direcionamento

25. Faça check-in a cada 10-15 minutos. Agent teams não são do tipo "configure e esqueça". Eu reviso o progresso em intervalos regulares, detecto desvios cedo e ajusto atribuições de tarefas se um agente está bloqueado enquanto outro está ocioso.

26. Você pode interagir com qualquer teammate diretamente. No modo tmux split-pane, clique no painel de um agente e dê instruções diretas. Você não está limitado a falar pelo líder. Quando percebo que um agente específico está indo na direção errada, intervenho diretamente em vez de retransmitir a correção pelo orquestrador.

27. Use hooks para eventos do ciclo de vida. O Claude Code suporta hooks que disparam quando teammates ficam ociosos, completam tarefas ou encontram erros. Eu conectei esses hooks a notificações no Slack para receber um ping quando um agente termina ou trava -- sem precisar ficar olhando o terminal o tempo todo.

28. Fique atento a loops infinitos. Ocasionalmente, dois agentes entram em um padrão de pingue-pongue -- Agente A faz uma pergunta ao Agente B, Agente B responde com outra pergunta, e eles ficam em loop. Se você ver o consumo de tokens disparando sem progresso visível, intervenha imediatamente.

Ciclo de Vida e Limpeza

29. Agentes param automaticamente quando sua fila de tarefas esvazia. O orquestrador gerencia o encerramento, mas o timing nem sempre é imediato. Se você terminou a sessão, diga explicitamente ao agente líder para encerrar.

30. Uma equipe por sessão. Um agente líder só pode gerenciar uma equipe por vez. Se você precisa de uma composição de equipe diferente para um projeto diferente, inicie uma nova sessão.

31. Teammates não podem criar suas próprias equipes. A hierarquia é plana: um líder, múltiplos teammates. Sem sub-equipes, sem orquestração recursiva. Se seu projeto precisa desse nível de aninhamento, provavelmente é melhor trabalhar com múltiplas sessões independentes.

32. Limpe processos de agentes após crashes. Se uma sessão crashar no meio de uma equipe, processos órfãos de agentes podem ficar rodando. Verifique processos obsoletos e termine-os manualmente. Isso evita tanto desperdício de recursos quanto potenciais conflitos quando você iniciar uma nova sessão.

33. Documente o que funcionou. Depois de cada sessão de equipe, eu gasto dois minutos anotando quais atribuições de modelo, tamanhos de equipe e padrões de comunicação funcionaram melhor para aquele tipo de projeto. Essa biblioteca de templates agora me permite montar equipes otimizadas em menos de três minutos.

Seis Casos de Uso Onde Agent Teams Arrasam Comparado a Agentes Solo

Teoria é bom. O que realmente importa é saber quando usar essa ferramenta. Depois de mais de trinta projetos, esses seis cenários consistentemente justificam o overhead de coordenação.

1. Desenvolvimento Full-Stack

Este é o caso de uso canônico, e ele realmente entrega. Três agentes -- líder de arquitetura, especialista em front-end, especialista em back-end -- trabalhando em paralelo no mesmo codebase. O líder produz o contrato de API primeiro, ambos os agentes de implementação constroem contra esse contrato simultaneamente, e problemas de integração surgem através de mensagens entre agentes ao invés de debugging pós-fato.

Em um projeto recente -- um dashboard multi-tenant com acesso baseado em roles e atualizações em tempo real via WebSocket -- a equipe de agentes entregou em 35 minutos o que teria levado a um agente solo quase 90 minutos. Não porque os agentes digitam mais rápido, mas porque o agente de front-end estava construindo componentes enquanto o agente de back-end estava construindo endpoints. Execução paralela de verdade em trabalho interdependente.

O ponto-chave: o padrão contrato-primeiro que descrevi na dica #9 é obrigatório aqui. Sem um contrato de API compartilhado, os agentes constroem com base em suposições que divergem imediatamente.

2. Code Review com Lentes Especializadas

Esse caso de uso me surpreendeu com o quão bem funciona. Atribua três agentes para revisar o mesmo PR, cada um com um foco diferente: vulnerabilidades de segurança, gargalos de performance e lacunas na cobertura de testes. Cada agente examina o código pela sua lente especializada e produz um relatório focado. O agente líder sintetiza os três relatórios em uma única revisão.

O resultado é mais minucioso do que qualquer revisão em passagem única, e o foco especializado significa que cada agente pega coisas que um generalista deixaria passar. Um agente focado em segurança sinalizou um vetor de SQL injection em uma query parametrizada que parecia correta à primeira vista -- o escape de parâmetros não tratava inputs de array. Um agente focado em performance pegou uma query N+1 escondida atrás de uma abstração ORM. Nenhuma das duas descobertas teria surgido em uma revisão padrão.

O custo para um code review com três agentes fica em torno de $3-5 em tokens. Para PRs críticos, é uma pechincha.

3. Debugging com Hipóteses Concorrentes

Quando um bug tem múltiplas causas raiz possíveis, a abordagem tradicional é sequencial: investigar hipótese A, se não for essa, tentar hipótese B. Agent teams permitem que você investigue todas as hipóteses simultaneamente.

Eu tive um problema em produção onde os tempos de resposta da API disparavam de 200ms para 3 segundos a cada poucas horas. Três causas possíveis: exaustão do pool de conexões do banco, memory leak em um background worker, ou um serviço externo fazendo throttling. Atribuí cada hipótese a um agente diferente e deixei eles investigarem em paralelo. Vinte minutos depois, o Agente C encontrou o throttling externo -- um rate limit em uma API de geocodificação que ninguém tinha documentado. Os outros dois agentes não encontraram evidências para suas hipóteses, o que foi igualmente valioso porque eliminou dois dias de potencial busca no escuro.

4. Fluxos de Escrita e Edição

Esse se mapeia diretamente ao pipeline de conteúdo que uso para este blog. Três agentes com papéis distintos: pesquisador (reúne fontes, dados, informações atuais), escritor (produz o rascunho seguindo a voz da marca e estrutura), e editor (revisa qualidade, precisão, consistência e SEO).

O pesquisador termina primeiro e passa suas descobertas para o escritor. O escritor produz o rascunho e entrega ao editor. O editor revisa e envia notas de revisão de volta. Esse fluxo sequencial-com-comunicação produz resultados notavelmente melhores do que um único agente tentando pesquisar, escrever e auto-editar simultaneamente -- porque cada agente foca em uma tarefa cognitiva sem troca de contexto.

5. Pesquisa e Exploração em Paralelo

Quando você precisa avaliar múltiplas ferramentas, abordagens ou arquiteturas antes de tomar uma decisão, agent teams permitem que você explore todos os caminhos simultaneamente. Usei isso quando estava avaliando três abordagens diferentes de gerenciamento de estado para um projeto React -- um agente testou Zustand, um testou Jotai, um testou a API nativa React Context. Cada agente construiu uma pequena prova de conceito, documentou os trade-offs e reportou ao líder.

A regra fundamental para tarefas de pesquisa: mantenha os agentes em modo somente leitura durante a fase de exploração. Deixe-os ler código, rodar benchmarks e escrever protótipos descartáveis -- mas não deixe eles modificarem o codebase principal até que o líder tenha revisado as descobertas e escolhido uma direção. Caso contrário, você acaba com três abordagens diferentes meio implementadas no seu código de produção.

6. Paridade de Features Cross-Platform

Se você está entregando a mesma feature em múltiplas plataformas -- iOS e Android, web e mobile, ou até diferentes microsserviços que precisam de comportamento sincronizado -- agent teams mantêm a paridade fazendo cada agente de plataforma compartilhar seus detalhes de implementação com os outros. Quando o agente de Android implementa um utilitário de formatação de datas, ele envia uma mensagem ao agente de iOS com a string de formato exata para que ambas as plataformas produzam output idêntico.

Eu só usei isso duas vezes, mas nas duas vezes detectou divergências que teriam se tornado bugs visíveis para o usuário. O overhead de coordenação é alto para esse padrão, então só recomendo para features onde inconsistência entre plataformas seria um problema sério -- fluxos de pagamento, serialização de dados, qualquer coisa onde "comportamento ligeiramente diferente no iOS vs Android" significa um ticket de suporte.

As Fases do Fluxo de Trabalho: Como Uma Sessão Realmente Se Desenrola

Para quem quer a visão ponta a ponta, aqui está como uma sessão típica de agent team flui do início ao fim. Vou usar um exemplo real -- construindo uma ferramenta interna para rastrear o status do pipeline de conteúdo.

Fase 1 -- Inicialização. Abro uma sessão tmux, inicio o Claude Code e verifico se a flag experimental de agents está ativa. Descrevo o projeto ao agente líder em detalhes: a stack (Next.js 15, Prisma, PostgreSQL), os requisitos (dashboard mostrando status de conteúdo, atribuições de autores, datas de publicação), e as restrições (deve integrar com o sistema de auth existente, não deve modificar o schema compartilhado do banco).

Fase 2 -- Criação da Equipe. Digo ao agente líder qual equipe preciso. Neste caso: um agente de front-end para a UI do dashboard, um agente de back-end para a camada de API e queries do banco, e um agente de QA. O líder cria três teammates, cada um aparecendo em seu próprio painel tmux. Posso ver todos os quatro agentes simultaneamente.

Fase 3 -- Planejamento de Tarefas. Antes de qualquer um escrever código, o agente líder produz um plano de tarefas. Ele descreve cada entregável, atribui tarefas a agentes específicos, define o contrato de API entre front-end e back-end, e estabelece os critérios de teste de integração. Reviso esse plano, ajusto duas atribuições de tarefas que não faziam sentido, e aprovo.

Fase 4 -- Execução Paralela. Os agentes começam a trabalhar. O front-end começa a construir os componentes do dashboard. O back-end cria o schema Prisma e as rotas de API. Posso acompanhar o progresso de ambos os agentes em tempo real pelos painéis tmux. Quando o agente de front-end precisa de esclarecimento sobre o formato de resposta do endpoint /content, ele envia mensagem diretamente ao agente de back-end.

Fase 5 -- Monitoramento e Direcionamento. Cerca de doze minutos depois, percebo o agente de front-end construindo um componente complexo de filtros que não estava na spec. Clico no painel dele e redireciono: "Pule os filtros avançados por enquanto. Foque no quadro de status e na visão de autores." O agente se ajusta imediatamente.

Fase 6 -- Integração e QA. Uma vez que ambos os agentes de implementação sinalizam conclusão, o agente de QA é ativado. Ele lê os componentes de front-end e os endpoints de back-end, escreve testes de integração e os executa. Duas falhas: um descasamento de formatação de data e um error boundary faltando. O agente de QA reporta esses problemas aos agentes relevantes, que os corrigem em menos de dois minutos.

Fase 7 -- Resumo e Limpeza. O agente líder compila um resumo: o que foi construído, quais testes passam, o que está pendente. Reviso o output, confirmo que tudo funciona e fecho a sessão. Tempo total: 28 minutos. Custo total em tokens com a configuração de modelos mistos: aproximadamente $8.

A sequência toda pareceu menos "usando uma ferramenta" e mais gerenciando uma pequena equipe de dev. O que, em um sentido significativo, é exatamente o que é.

Os Trade-Offs Honestos Que Ninguém Comenta

Eu estaria fazendo um desserviço se pintasse agent teams como universalmente superiores. Não são. Aqui está o que aprendi sobre suas limitações reais depois de meses de uso diário.

O custo escala linearmente, mas o valor não. Três agentes custam três vezes mais que um. Mas nem sempre entregam três vezes o valor. Para projetos de complexidade moderada -- a maioria dos apps CRUD, a maioria das ferramentas single-page, a maioria dos scripts -- um agente solo é mais rápido, mais barato, e produz output mais fácil de debugar porque um único cérebro escreveu tudo.

Troca de mensagens não é compartilhamento gratuito de contexto. Agentes podem enviar mensagens uns aos outros, mas essas mensagens consomem tokens tanto no lado de envio quanto no de recebimento. Comunicação pesada entre agentes pode custar mais do que a codificação em si. Já vi sessões onde 30% do uso total de tokens foi em mensagens entre agentes.

O orquestrador é um ponto único de falha. Se o agente líder fica confuso sobre o estado do projeto -- e isso acontece -- a equipe inteira desvia. A janela de contexto do líder é finita, e rastrear o status do trabalho de cinco teammates em dezenas de tarefas pode sobrecarregar até o Opus 4.6. É por isso que limito as equipes a 3-4 agentes e as tarefas a 5-6 por agente.

Debugar output de equipe é mais difícil do que debugar output solo. Quando algo quebra no output de um agente solo, você sabe quem escreveu. Quando algo quebra no output de uma equipe, você precisa rastrear qual agente produziu o código problemático, que contexto ele tinha quando tomou aquela decisão, e se a mensagem de outro agente influenciou a escolha. O raio de impacto de um erro é maior.

A funcionalidade ainda é experimental. Retomada de sessão não é confiável. O encerramento de teammates nem sempre acontece de forma limpa. A indexação de painéis tmux pode quebrar se sua configuração usa índices base não-padrão. Essas são arestas brutas, e vale a pena tolerá-las para projetos complexos -- mas significam que agent teams ainda não são ferramental nível produção. São uma funcionalidade avançada para pessoas dispostas a lidar com a fricção.

Aqui vai minha posição honesta depois de três meses: agent teams são a escolha certa para talvez 15-20% dos projetos em que trabalho. Mas para esses 15-20%, são dramaticamente melhores do que a alternativa. A habilidade está em saber quais 15-20%.

Se você preferir que alguém construa e configure esse tipo de fluxo de trabalho multi-agente para o seu projeto, eu aceito projetos customizados de automação com IA. Você pode ver o que eu já construí em fiverr.com/s/EgxYmWD.

Como Eu Começaria Se Estivesse Configurando Isso Hoje

Se eu pudesse voltar a fevereiro e me dar um passo a passo de cinco etapas, é isso que eu entregaria.

Primeira sessão: agente solo, só modo de planejamento. Não toque em agent teams. Construa seu plano de projeto com uma única instância do Claude Code. Acerte a arquitetura, defina os contratos de API, mapeie a estrutura de arquivos. Isso custa quase nada e produz a planta que sua equipe vai executar.

Segunda sessão: dois agentes, uma tarefa pequena. Crie um líder e um teammate. Dê a eles uma parte contida e de baixo risco do projeto -- uma única feature com limites claros. Observe como a comunicação flui. Aprenda a interface tmux. Familiarize-se com o ritmo.

Terceira sessão: três agentes, trabalho real. Agora você sabe o suficiente para ser eficiente. Líder no Opus, dois teammates no Sonnet, limites de domínio claros, contratos compartilhados, 5-6 tarefas por agente. Essa é sua configuração de produção para 90% dos projetos dignos de equipe.

Toda sessão depois disso: refine seus templates. Documente quais atribuições de modelo, tamanhos de equipe e padrões de comunicação funcionam para cada tipo de projeto. Depois de dez sessões, você terá uma biblioteca de templates de equipe que torna a configuração quase instantânea.

A única coisa que eu mudaria: eu teria começado lendo a documentação oficial da Anthropic sobre agent teams em code.claude.com/docs/en/agent-teams ao invés de aprender por tentativa e erro. A documentação é genuinamente boa -- só não existia quando eu comecei a experimentar.

A maior mudança no meu pensamento ao longo desses três meses não é sobre a tecnologia. É sobre o papel. Quando uso agent teams, paro de ser um desenvolvedor que usa IA e passo a ser um tech lead que gerencia desenvolvedores de IA. As habilidades que importam mudam: escrita clara de requisitos, decomposição de tarefas, monitoramento de progresso, planejamento de integração. As mesmas habilidades que fazem um bom gerente de engenharia fazem um bom operador de agent teams.

Seu terminal não é mais um editor de texto. É uma sala de comando. E os agentes estão esperando ordens.

Perguntas Frequentes

Como eu habilito o Claude Code agent teams?

Adicione "agentTeams": true à seção "experimental" do ~/.claude/settings.json, ou defina a variável de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Você precisa de uma assinatura Claude Pro ou Max com acesso ao Opus 4.6 para o papel de agente líder.

Quantos agentes devo usar em uma equipe do Claude Code?

Comece com 3 teammates para a maioria dos projetos -- um líder, dois especialistas. Três agentes equilibram throughput paralelo com overhead de coordenação. Equipes de 5 ou mais gastam uma quantidade desproporcional de tokens em mensagens entre agentes. Para um detalhamento mais aprofundado, veja as dicas de Composição da Equipe acima.

Agent teams do Claude Code custam mais do que sub-agents?

Sim. Uma equipe de 3 agentes usa aproximadamente 3-4x os tokens de uma sessão única fazendo o mesmo trabalho. Você pode reduzir custos atribuindo modelos mais baratos (Sonnet 4.5 ou Haiku) a teammates focados em execução enquanto mantém o Opus no líder. Agent teams só são custo-efetivas quando a complexidade do projeto genuinamente demanda coordenação em tempo real.

Teammates do Claude Code podem editar o mesmo arquivo?

Podem, mas absolutamente não devem. Agent teams não possuem detecção de merge conflict -- um agente silenciosamente sobrescreve as alterações do outro. Atribua propriedade explícita de arquivos a cada agente antes da execução começar, e direcione qualquer alteração de arquivo cross-domain pelo agente líder.

Qual é a diferença entre agent teams e sub-agents no Claude Code?

Sub-agents são trabalhadores isolados que reportam resultados de volta à sessão pai -- sem comunicação entre agentes. Agent teams adicionam troca direta de mensagens entre teammates, habilitando coordenação em tempo real para tarefas interdependentes. Use sub-agents para trabalho paralelo independente, agent teams para trabalho colaborativo que requer contexto compartilhado.

Vamos Trabalhar Juntos

Quer construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura de tecnologia? Adoraria ajudar.

• Fiverr (builds customizados e integrações): fiverr.com/s/EgxYmWD
• Portfolio: mejba.me
• Ramlit Limited (soluções enterprise): ramlit.com
• ColorPark (design e branding): colorpark.io
• xCyberSecurity (serviços de segurança): xcybersecurity.io