Agent Teams no Claude Code: Como Coordenar Times de IAs

Voce ja usou o Claude Code para criar projetos, editar codigo e automatizar tarefas. Mas e se voce pudesse ter varios agentes trabalhando juntos, ao mesmo tempo, cada um com uma especialidade diferente? Isso e o que Agent Teams oferece -- e e uma das features mais ambiciosas que a Anthropic ja lancou.

Agent Teams e uma feature experimental do Claude Code que permite coordenar multiplos agentes de IA como se fossem um time de desenvolvimento real. Um agente lidera, outros executam, e todos se comunicam diretamente entre si. O resultado: projetos que antes levavam horas com um unico agente agora podem ser feitos em minutos com um time coordenado.

Neste guia, voce vai entender como Agent Teams funciona por dentro, como configurar, quais hooks avancados estao disponiveis e -- mais importante -- quando faz sentido usar um time em vez de um agente solo.

1. O que sao Agent Teams (e por que isso muda tudo)

Ate agora, o Claude Code funcionava como um unico agente. Voce conversava com ele, pedia tarefas, ele executava. Poderoso, mas limitado a uma "thread" de raciocinio. Agent Teams quebra essa limitacao ao introduzir um conceito familiar: times.

Um Agent Team e composto por:

• Team Lead: o agente principal que recebe sua instrucao, planeja a execucao e distribui tarefas
• Teammates: agentes especializados que executam tarefas especificas em paralelo
• Comunicacao direta: teammates podem conversar entre si sem precisar passar pelo team lead

Pense num time de desenvolvimento real. Voce tem um tech lead que entende o projeto completo, um dev frontend, um dev backend e alguem de QA. Cada um faz sua parte, mas eles conversam entre si quando precisam alinhar algo. Agent Teams replica essa dinamica com agentes de IA.

Por que isso e diferente de simplesmente abrir varias janelas do Claude Code

A diferenca fundamental e coordenacao. Quando voce abre varias janelas do Claude Code, cada agente opera isolado. Eles nao sabem o que os outros estao fazendo. Com Agent Teams, o team lead mantem visibilidade de tudo, distribui tarefas de forma inteligente e os teammates compartilham contexto. E a diferenca entre ter 5 freelancers que nunca se falam e ter um time integrado.

Alem disso, Agent Teams gerencia conflitos automaticamente. Se dois teammates tentam editar o mesmo arquivo, o sistema coordena as mudancas em vez de criar conflitos. Isso e algo que voce simplesmente nao consegue com agentes independentes.

Status da feature em 2026

Agent Teams e uma feature experimental. A Anthropic lancou como preview para coletar feedback da comunidade antes de estabilizar a API. Na pratica, isso significa que funciona bem o suficiente para uso real, mas a sintaxe de configuracao e os hooks podem mudar entre versoes. Se voce esta disposto a acompanhar as atualizacoes, pode comecar a usar agora. Se prefere estabilidade total, acompanhe o changelog da Anthropic e espere o lancamento estavel.

2. Arquitetura: team lead, teammates e comunicacao

Entender a arquitetura e essencial para usar Agent Teams de forma eficaz. Vamos destrinchar cada componente.

Team Lead

O team lead e o agente que voce interage diretamente. Quando voce digita uma instrucao no Claude Code com Agent Teams ativo, e o team lead que recebe. Ele tem responsabilidades especificas:

• Planejamento: analisa a tarefa e decide como dividir entre teammates
• Delegacao: atribui subtarefas a teammates especificos com instrucoes claras
• Supervisao: monitora o progresso de cada teammate
• Integracao: combina os resultados dos teammates em uma entrega coesa
• Comunicacao com o usuario: reporta status, pede esclarecimentos e entrega o resultado final

O team lead usa o modelo mais potente disponivel (geralmente Opus) porque precisa de capacidade de raciocinio superior para coordenar. Os teammates podem usar modelos mais leves (Sonnet) para execucao, o que otimiza custo sem sacrificar qualidade.

Teammates

Teammates sao agentes especializados. Cada teammate tem:

• Um papel definido: "frontend developer", "test engineer", "documentation writer", etc.
• Instrucoes especificas: o que ele deve fazer e como deve fazer
• Acesso a ferramentas: cada teammate pode ter acesso a ferramentas diferentes
• Limite de turns: cada teammate opera com ate 50 tool-use turns por tarefa

O limite de 50 tool-use turns e importante. Isso significa que cada teammate pode ler arquivos, escrever codigo, executar testes e fazer ajustes -- tudo dentro de uma unica tarefa delegada. E suficiente para a maioria das subtarefas, mas tarefas muito grandes precisam ser quebradas pelo team lead.

Comunicacao direta entre teammates

Esta e a feature mais poderosa e menos obvia. Teammates podem se comunicar diretamente, sem passar pelo team lead. Na pratica:

• O teammate de frontend pode perguntar ao teammate de backend "qual o formato do JSON que a API retorna?"
• O teammate de testes pode avisar o teammate de backend "esse endpoint esta retornando 500, voce mudou algo?"
• O teammate de documentacao pode pedir ao teammate de frontend "me passa os props desse componente"

Essa comunicacao lateral reduz drasticamente o tempo de coordenacao. Em vez de tudo ter que subir ate o team lead e descer de volta, os agentes que precisam alinhar algo fazem diretamente. E exatamente como funciona num time humano eficiente.

3. Sub-agents: agentes dentro de agentes

Sub-agents existiam antes de Agent Teams e continuam sendo uma ferramenta poderosa. A diferenca e conceitual: um sub-agent e um agente lancado por outro agente para executar uma tarefa isolada.

Como sub-agents funcionam

Quando o Claude Code (ou um teammate dentro de um Agent Team) encontra uma tarefa que exige foco isolado, ele pode lancar um sub-agent. Esse sub-agent:

• Recebe uma instrucao especifica e um contexto limitado
• Opera com ate 50 tool-use turns
• Tem acesso as mesmas ferramentas do agente pai (ler/escrever arquivos, executar comandos)
• Retorna o resultado ao agente que o lancou
• Nao persiste apos completar a tarefa

Sub-agents sao como funcoes assincronas no mundo da programacao. Voce delega, o sub-agent executa, retorna e desaparece.

Sub-agent vs Teammate

Caracteristica	Sub-agent	Teammate
Persistencia	Temporario (uma tarefa)	Permanente durante a sessao
Comunicacao	Apenas com o agente pai	Com team lead e outros teammates
Contexto compartilhado	Minimo (so o que recebeu)	Amplo (ve o projeto todo)
Tool-use turns	Ate 50	Ate 50 por tarefa delegada
Custo	Menor (contexto limitado)	Maior (contexto completo)
Quando usar	Tarefa pontual e isolada	Tarefas interdependentes e continuas

Exemplo pratico de sub-agent

Voce pede ao Claude Code: "Refatore o sistema de autenticacao e adicione testes." O agente principal pode lancar um sub-agent especificamente para escrever os testes enquanto ele mesmo faz o refactoring. O sub-agent recebe o contexto dos arquivos de auth, escreve os testes, retorna, e o agente principal integra tudo.

4. Hooks avancados para Agent Teams

Hooks sao o mecanismo que permite automatizar comportamentos dos agentes. Agent Teams introduz hooks especificos para coordenacao de times que nao existem no Claude Code solo.

TeammateIdle

Disparado quando um teammate termina sua tarefa e fica ocioso. Util para:

• Redirecionar o teammate para uma nova tarefa automaticamente
• Notificar o team lead que o teammate esta disponivel
• Executar scripts de validacao no trabalho que o teammate acabou de completar

// .claude/hooks/teammate-idle.js
export default {
  event: "TeammateIdle",
  handler: async ({ teammate, completedTask }) => {
    // Rodar lint no codigo que o teammate escreveu
    if (teammate.role === "frontend") {
      await run("npx eslint src/components/ --fix");
    }
    // Notificar que esta disponivel para nova tarefa
    return { status: "available", lastTask: completedTask.summary };
  }
};

TaskCompleted

Disparado quando qualquer tarefa delegada e concluida. Diferente do TeammateIdle, este hook foca na tarefa e nao no agente. Voce pode usar para:

• Validar a qualidade do output automaticamente
• Disparar testes relacionados a tarefa completada
• Atualizar um log de progresso do projeto
• Enviar notificacoes (webhook, Slack, etc.)

// .claude/hooks/task-completed.js
export default {
  event: "TaskCompleted",
  handler: async ({ task, teammate, result }) => {
    // Rodar testes apos qualquer tarefa de codigo
    if (task.type === "code") {
      const testResult = await run("npm test -- --related " + task.files.join(" "));
      return { testsPass: testResult.exitCode === 0 };
    }
  }
};

PreToolUse defer

O hook PreToolUse ja existia, mas Agent Teams adiciona a opcao defer. Quando um teammate tenta usar uma ferramenta e o hook retorna defer, a acao e pausada e encaminhada ao team lead para aprovacao. Isso cria um sistema de permissao hierarquica:

• Teammates podem ler arquivos e escrever codigo livremente
• Mas operacoes destrutivas (deletar arquivos, executar scripts de deploy) precisam de aprovacao do team lead
• O team lead pode aprovar ou negar, e o teammate continua a partir daquele ponto

// .claude/hooks/pre-tool-use.js
export default {
  event: "PreToolUse",
  handler: async ({ tool, teammate, args }) => {
    // Operacoes de delete precisam de aprovacao do team lead
    if (tool === "bash" && args.command.includes("rm ")) {
      return { action: "defer", reason: "Operacao destrutiva requer aprovacao" };
    }
    // Deploy precisa de aprovacao
    if (tool === "bash" && args.command.includes("deploy")) {
      return { action: "defer", reason: "Deploy requer aprovacao do lead" };
    }
    return { action: "allow" };
  }
};

Agent hooks que leem arquivos e buscam codigo

Hooks podem usar as mesmas ferramentas que os agentes: ler arquivos, buscar padroes no codigo e tomar decisoes baseadas no contexto do projeto. Um hook pode, por exemplo, ler o package.json antes de permitir que um teammate instale uma dependencia, verificando se ela ja existe ou se conflita com algo.

// Hook que valida dependencias antes de instalar
export default {
  event: "PreToolUse",
  handler: async ({ tool, args, readFile }) => {
    if (tool === "bash" && args.command.startsWith("npm install")) {
      const pkg = JSON.parse(await readFile("package.json"));
      const dep = args.command.split("npm install ")[1];
      if (pkg.dependencies[dep]) {
        return { action: "block", reason: dep + " ja esta instalado" };
      }
    }
    return { action: "allow" };
  }
};

5. Claude Code Review: revisao de PRs em paralelo

Claude Code Review e uma feature que usa a infraestrutura de Agent Teams para revisar pull requests. Em vez de um unico agente ler todo o PR, multiplos agentes revisam diferentes partes simultaneamente.

Como funciona

Quando voce submete um PR para review pelo Claude Code, o sistema:

1. Analisa o diff completo do PR
2. Divide os arquivos alterados em grupos logicos (frontend, backend, testes, config)
3. Atribui cada grupo a um agente reviewer especializado
4. Cada reviewer analisa seu grupo em paralelo
5. Um agente coordenador consolida os reviews em um unico feedback

O resultado e uma revisao mais rapida e mais profunda. Enquanto um unico agente pode perder detalhes num PR grande, multiplos agentes especializados capturam problemas que seriam ignorados numa revisao superficial.

Na pratica

PRs que antes levavam 15-20 minutos de revisao por um unico agente agora completam em 3-5 minutos com revisao paralela. E a qualidade e superior porque cada reviewer foca em sua area de expertise.

6. O comando /powerup: licoes interativas

O /powerup e um comando do Claude Code que oferece licoes interativas sobre features avancadas. Para Agent Teams, ele e especialmente util porque a feature e nova e as melhores praticas ainda estao sendo estabelecidas.

Como usar

Cada licao dura 5-10 minutos e inclui exercicios praticos. Voce nao apenas le sobre a feature -- voce usa ela num ambiente guiado. E a forma mais rapida de pegar fluencia em features novas sem precisar ler documentacao extensa.

O /powerup se atualiza automaticamente quando novas features sao lancadas. Depois de cada atualizacao do Claude Code, vale rodar /powerup para ver se ha licoes novas.

7. Plugins com executaveis em bin/

Plugins sao uma forma de estender o Claude Code com ferramentas customizadas. No contexto de Agent Teams, plugins ganham uma dimensao extra: voce pode criar ferramentas que somente teammates especificos tem acesso.

Estrutura de um plugin

Um plugin do Claude Code e simplesmente um executavel na pasta .claude/bin/ do seu projeto. Pode ser um script bash, um binario compilado, um script Python -- qualquer coisa que rode no terminal.

# Estrutura de plugins
.claude/
  bin/
    lint-check          # Script bash que roda linting
    db-migrate          # Script Python que aplica migrations
    deploy-staging      # Script que faz deploy para staging
    generate-api-docs   # Script que gera documentacao da API

Cada arquivo na pasta bin/ se torna uma ferramenta que o Claude Code (e seus teammates) podem chamar. O nome do arquivo e o nome da ferramenta.

Restringindo acesso por teammate

Com Agent Teams, voce pode configurar quais teammates tem acesso a quais plugins. O teammate de frontend nao precisa (e nao deve) ter acesso ao db-migrate. O teammate de documentacao nao precisa de acesso ao deploy-staging.

# .claude/teams.yaml
team:
  lead:
    model: opus
    tools: [all]
  teammates:
    frontend:
      model: sonnet
      tools: [lint-check, read, write, bash]
    backend:
      model: sonnet
      tools: [lint-check, db-migrate, read, write, bash]
    qa:
      model: sonnet
      tools: [lint-check, read, bash]
    docs:
      model: haiku
      tools: [generate-api-docs, read, write]

Essa configuracao cria separacao de responsabilidades. Cada teammate tem acesso apenas ao que precisa, reduzindo risco de operacoes nao intencionais e economizando tokens (ferramentas nao disponibilizadas nao consomem contexto).

8. Workflows multi-agente na pratica

Teoria e importante, mas voce quer saber como isso funciona no mundo real. Aqui estao workflows concretos que times estao usando com Agent Teams.

Workflow 1: Feature completa (frontend + backend + testes)

Voce pede: "Implemente o sistema de notificacoes push, com API backend, componente frontend e testes completos."

1. Team lead analisa o pedido e cria um plano com 3 subtarefas
2. Teammate backend cria os endpoints de API, modelo de dados e logica de envio
3. Teammate frontend cria o componente de notificacao, permissoes do browser e UI
4. Teammate QA aguarda backend e frontend terminarem, depois escreve testes de integracao
5. Frontend e backend se comunicam diretamente para alinhar o contrato da API
6. Team lead integra tudo, roda a suite de testes e reporta o resultado

Tempo com agente solo: 25-40 minutos. Tempo com Agent Team: 8-15 minutos. A economia vem da paralelizacao -- enquanto o backend cria a API, o frontend ja esta construindo a UI.

Workflow 2: Refactoring massivo

Voce pede: "Migre todos os componentes de classe para componentes funcionais com hooks."

1. Team lead identifica todos os componentes de classe no projeto (digamos 30 arquivos)
2. Divide em grupos de 10 e atribui a 3 teammates
3. Cada teammate migra seus 10 componentes em paralelo
4. Um teammate de QA roda testes apos cada grupo de migracoes
5. Team lead consolida e verifica que nenhuma regressao foi introduzida

Workflow 3: Auditoria e correcao

Voce pede: "Faca uma auditoria de seguranca, performance e acessibilidade, e corrija o que encontrar."

1. Teammate de seguranca analisa vulnerabilidades (XSS, SQL injection, secrets expostos)
2. Teammate de performance analisa bundle size, lazy loading, cache headers
3. Teammate de acessibilidade analisa ARIA labels, contraste, navegacao por teclado
4. Cada um gera um relatorio e aplica fixes automaticamente
5. Team lead consolida os relatorios e prioriza issues que nenhum teammate conseguiu resolver sozinho

9. Quando usar um agente vs um time

Nem tudo precisa de um Agent Team. Saber quando usar cada abordagem e tao importante quanto saber como configurar.

Use um agente solo quando:

• A tarefa e sequencial: cada passo depende do anterior. Um agente faz melhor que um time parado esperando
• O escopo e pequeno: criar uma funcao, corrigir um bug, editar um arquivo. Um time e overkill
• Voce precisa de interacao constante: decisoes criativas, brainstorming, ajustes iterativos. Um agente solo responde mais rapido
• O custo importa: agente solo usa menos tokens. Se voce esta otimizando custo, fique no solo
• O projeto e novo: quando voce ainda esta explorando e nao sabe exatamente o que quer, um agente solo e mais flexivel

Use um Agent Team quando:

• A tarefa e paralelizavel: frontend + backend + testes podem ser feitos ao mesmo tempo
• O escopo e grande: refactoring de muitos arquivos, feature completa com multiplas camadas
• Especialidades diferentes sao necessarias: a tarefa exige conhecimento de areas distintas que um unico prompt nao cobre bem
• Tempo e mais importante que custo: voce precisa da entrega rapida e aceita pagar mais tokens
• Revisao e necessaria: ter um agente revisando o trabalho de outro aumenta a qualidade

Cenario	Recomendacao	Motivo
Corrigir um bug especifico	Agente solo	Tarefa sequencial e focada
Criar CRUD completo	Agent Team (2-3)	Backend + frontend + testes em paralelo
Refatorar 50+ arquivos	Agent Team (3-4)	Paralelizacao massiva
Escrever um README	Agente solo	Tarefa unica e sequencial
Auditoria multi-area	Agent Team (3+)	Especialidades diferentes em paralelo
Prototipar uma ideia	Agente solo	Iteracao rapida e exploracao
Code review de PR grande	Claude Code Review	Revisao paralela por especializacao

10. Como configurar seu primeiro Agent Team

Vamos ao pratico. Configurar um Agent Team exige criar um arquivo de configuracao no seu projeto e definir os papeis de cada teammate.

Passo 1: criar o arquivo de configuracao

Na raiz do seu projeto, crie o arquivo .claude/teams.yaml:

# .claude/teams.yaml
team:
  name: "meu-time"
  lead:
    model: opus
    instructions: |
      Voce e o tech lead deste projeto.
      Planeje tarefas, delegue e integre resultados.
      Sempre rode testes antes de reportar conclusao.

  teammates:
    frontend:
      model: sonnet
      instructions: |
        Voce e o dev frontend. Trabalha com React e TypeScript.
        Siga os padroes do projeto em src/components.
        Sempre use TypeScript strict mode.

    backend:
      model: sonnet
      instructions: |
        Voce e o dev backend. Trabalha com Node.js e PostgreSQL.
        Siga os padroes de API em src/api.
        Valide inputs e trate erros adequadamente.

    qa:
      model: sonnet
      instructions: |
        Voce e o QA engineer. Escreve e roda testes.
        Use Jest para unidades e Playwright para E2E.
        Nao aprove nada com cobertura abaixo de 80%.

Passo 2: ativar Agent Teams

Passo 3: usar normalmente

Com o time ativo, voce interage normalmente com o Claude Code. A diferenca e que o team lead vai automaticamente delegar tarefas quando fizer sentido. Voce nao precisa microgerenciar -- o lead decide quando paralelizar e quando fazer ele mesmo.

Note como frontend e backend se comunicaram diretamente sobre o formato do timestamp sem que o lead precisasse intermediar. Isso e a magia da comunicacao lateral.

Dicas de configuracao

• Comece com 2-3 teammates: nao crie um time de 10 agentes. Comece simples, adicione conforme necessidade
• Seja especifico nas instrucoes: quanto mais claro o papel de cada teammate, melhor a coordenacao
• Use hooks desde o inicio: configure pelo menos o PreToolUse com defer para operacoes destrutivas
• Monitore o custo: use /cost para acompanhar o consumo. Agent Teams consome 2-4x mais que agente solo
• Itere: ajuste as instrucoes dos teammates conforme voce ve o que funciona e o que nao funciona