Tutorial de Agent Teams do Claude Code: 15 passos da configuração ao desligamento
Agent Teams dá a cada colega sua própria sessão do Claude Code, uma lista de tarefas compartilhada e conversa direta entre eles. Este tutorial com capturas cobre a flag do settings.json, seu primeiro time, a condução, o desligamento — e os limites que ninguém conta.
A versão curta
- Agent Teams é experimental e vem desligado por padrão: adicione "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" ao bloco env do settings.json e rode o Claude Code v2.1.32 ou mais recente.
- Você precisa pedir com palavras — diga ao Claude "create an agent team" e nomeie os colegas ou o modelo, senão ele gera subagents comuns em silêncio.
- Os colegas nunca herdam seu histórico de conversa — entregue um arquivo de contexto e mantenha cada tarefa pequena o bastante para produzir um único entregável claro.
- Cada colega é uma instância separada do Claude Code com sua própria janela de contexto, então os tokens se multiplicam — rebaixe colegas para Sonnet ou Haiku quando a tarefa permitir e confira /cost após cada execução.
Claude Code Agent Teams (Full Tutorial): The BEST FEATURE of Claude Code is HERE!
Vídeo:AICodeKing13:58
Agent teams — Orchestrate teams of Claude Code sessions
Documentação:code.claude.comDocs
Agent Teams é experimental: espere arestas na retomada de sessões, no status das tarefas e nos tempos de desligamento. Cada comando, chave de configuração e atalho desta página foi verificado contra a documentação oficial antes da publicação.
As capturas vêm da gravação de tela do AICodeKing; os tutoriais de Bart Slodyczka e Simon Scrapes aportaram fatos práticos extras. Todas as fontes estão creditadas e linkadas, e cada passo leva de volta ao momento exato do vídeo.
De um terminal frio a um time desmobilizado
1. Ative o Agent Teams e verifique o ambiente
- 1
Encontre a documentação de agent teams e leia o aviso experimental
Agent Teams vive na seção Build with Claude Code da documentação oficial. A página abre com um banner laranja: o recurso é experimental, vem desligado por padrão e tem limitações conhecidas de retomada de sessão, coordenação de tarefas e desligamento. Leia esse banner antes de mexer em qualquer flag.
A página oficial de agent teams e o banner de recurso experimental.Assistir em 0:20 - 2
Decida entre subagents e agent teams
A documentação traz uma tabela comparativa. Subagents rodam numa única sessão, devolvem resultados ao chamador e custam menos tokens. Colegas são instâncias independentes do Claude Code que se mandam mensagens diretamente e compartilham uma lista de tarefas — colaboração de verdade custa mais tokens. Use subagents quando só o resultado importa; um time, quando os trabalhadores precisam se desafiar.
Subagents vs agent teams, direto da tabela oficial.Assistir em 1:00 - 3
Ative a flag no settings.json
Abra (ou crie) o ~/.claude/settings.json e adicione um bloco env com "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1". Arquivos de configuração de projeto e locais também podem ativá-la, e export de shell funciona — mas um "0" nas configurações de usuário sobrepõe o export. A mudança vale para a sessão em andamento sem reiniciar.
O bloco env que liga o agent teams.Assistir em 2:00 - 4
Atualize o Claude Code, inicie e peça o time em linguagem clara
Rode antes o claude update — times exigem um build recente (2.1.32 ou mais novo); versões antigas ignoram a flag em silêncio. Inicie o Claude, confira o seletor de modelo (o vídeo usa Opus 4.6 no Claude Max) e digite um prompt com as palavras mágicas: "Use the agent teams feature." Sem essa frase, o Claude gera subagents comuns.
Claude Code v2.1.34 recebendo o prompt de agent teams.Assistir em 3:30
2. Gere seu primeiro time
- 5
Veja o lead dividir o trabalho numa lista de tarefas compartilhada
O lead transforma seu prompt em tarefas e depois gera os colegas. A entrada de cada colega mostra a tarefa e "shift+↑ to manage". Repare no marcador de dependência: "Build UI, styling, and user interaction > blocked by #1" — o colega de UI só pode assumir a tarefa quando o de engine terminar; é assim que a lista compartilhada evita trabalho duplicado.
Dois colegas gerados, tarefa #2 bloqueada pela #1.Assistir em 4:30 - 6
Deixe rodar e leia o progresso ao vivo
Os colegas trabalham em paralelo nas próprias sessões. O lead narra o estado — "Both agents are working" — enquanto cada linha de tarefa carrega nome do colega, tempo decorrido e gasto de tokens. Ctrl+o expande uma entrada e ctrl+t mostra ou esconde o painel de colegas a qualquer momento.
Trabalho paralelo com contabilidade de tokens e tempo por tarefa.Assistir em 5:00 - 7
Opcional: fixe o número de colegas e o modelo deles
Você pode especificar exatamente o que quer: "Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate." Atribuir um modelo mais barato por colega é a melhor alavanca de custo — trabalho rotineiro não precisa de Opus. Para tarefas arriscadas, exija também aprovação de plano para que o plano do colega espere seu aval.
O exemplo da documentação para especificar colegas e modelos.Assistir em 6:30
3. Conduza, verifique e itere
- 8
Acompanhe a entrega entre dependências e a revisão do lead
Quando o colega de engine termina, a tarefa #2 é desbloqueada e o dev de UI assume. Depois o lead mesmo lê os arquivos alterados — "Let me shut down the teammates and do a final review of the code to make sure everything integrates properly." Você intervém só se algo parecer errado.
Tarefa #1 completa, #2 desbloqueada, revisão final começando.Assistir em 7:30 - 9
Abra o entregável e verifique você mesmo
A saída do time chega como arquivos comuns no seu projeto — aqui um Campo Minado com três níveis de dificuldade, revelação por flood-fill e primeiro clique seguro. Abra no navegador e use de verdade antes de dispensar o time: os agentes verificam o próprio código, mas o aceite é seu.
O entregável do time: um clone de Campo Minado que funciona.Assistir em 9:00 - 10
Itere dando outro prompt ao mesmo time
A lista de funcionalidades passa, então o vídeo repete: "Add more themes to it. Use team." Em tarefas de código o lead costuma manter os colegas em espera em vez de desmobilizá-los — seu follow-up chega com todo o contexto do que já foi construído. Note a barra de status: accept edits on (shift+tab para alternar).
A lista de funcionalidades entregue e o prompt da segunda rodada.Assistir em 10:00 - 11
Conduza indivíduos pelo painel de colegas
Num time maior (a segunda demo do vídeo roda seis colegas), o painel mostra o nome de cada um, uma palavra de status ao vivo e a contagem de tokens. shift+↑ / shift+↓ seleciona, Enter abre a conversa, e a caixa de mensagem aceita menções @ como "Message @infra-dev…" para falar com um colega sem passar pelo lead.
Seis colegas, contagens de tokens ao vivo e caixa de menção @.Assistir em 13:30 - 12
Desligue os colegas com elegância
Peça ao lead pelo nome — "Ask the ui-dev teammate to shut down" — e o colega aprova, terminando antes a chamada de ferramenta em andamento. Um colega que julgar seu trabalho crítico pode recusar com uma explicação. Quando tudo estiver pronto, "clean up the team" fecha as sessões compartilhadas e os painéis voltam a um.
Os dois colegas se desligam com elegância durante a limpeza.Assistir em 8:00
4. Conheça os limites antes de escalar
- 13
Conheça a regra de contexto antes de escalar
Os colegas carregam CLAUDE.md, servidores MCP e skills automaticamente, mas nunca herdam o histórico de conversa do lead. Passe o contexto explicitamente — o exemplo da documentação gera um revisor de segurança com os arquivos exatos, os focos e o formato de relatório no prompt. E dimensione as tarefas com honestidade: pequena demais desperdiça coordenação, grande demais arrisca esforço perdido, no ponto certo é um único entregável autocontido.
A regra de herança de contexto e a lista de dimensionamento de tarefas.Assistir em 10:15 - 14
Aceite que times não retomam sessão
A limitação que mais surpreende: /resume e /rewind não restauram colegas in-process. Depois de retomar uma sessão, o lead pode tentar falar com colegas que não existem mais — quando acontecer, diga ao lead para gerar colegas novos. Espere também atraso no status das tarefas: se uma tarefa parecer travada, confira se o trabalho realmente ficou pronto e atualize manualmente.
Sem retomada de sessão, mais o aviso sobre status de tarefas.Assistir em 10:30 - 15
Confira as limitações restantes e escolha trabalho de verdade
Mais três regras da documentação: o lead é fixo (não se promove um colega), permissões definidas no spawn se propagam — --dangerously-skip-permissions flui para todo colega, então mude o modo de um revisor depois se ele não deve editar — e painéis divididos exigem tmux ou iTerm2, porque o terminal integrado do VS Code, o Windows Terminal e o Ghostty não são suportados. Depois comece com 3-5 colegas num trabalho que exija colaboração de verdade.
Lead fixo, permissões propagadas, painéis divididos precisam de tmux.Assistir em 11:30