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.

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