👥 O que sao Agent Teams (multi-agent)
Agent Teams e a funcionalidade experimental do Claude Code que permite multiplos agentes Claude trabalhando simultaneamente em subtarefas diferentes do mesmo projeto. Em vez de um unico agente sequencial, voce tem um time de agentes especializados operando em paralelo.
🎯 Conceito Principal
Agent Teams transforma o Claude Code de um agente solo em um coordenador de time. O agente principal (orchestrator) recebe a tarefa, divide em subtarefas e delega para subagentes que trabalham em paralelo, cada um em seu proprio worktree git isolado.
- • Orchestrator: O agente principal que recebe sua tarefa, planeja a divisao e coordena os subagentes. Ele nao edita codigo diretamente
- • Subagentes: Agentes independentes que recebem subtarefas especificas e trabalham em paralelo, cada um com sua propria sessao
- • Isolamento: Cada subagente trabalha em um git worktree separado, evitando conflitos de edicao simultanea
- • Merge final: Apos todos os subagentes completarem, o orchestrator faz o merge das mudancas e resolve conflitos
💻 Exemplo de Uso
💡 Dica Pratica
Agent Teams funciona melhor quando as subtarefas sao independentes entre si. Se o subagente A precisa do resultado do subagente B para comecar, o paralelismo nao ajuda. Pense em tarefas que possam ser executadas ao mesmo tempo sem dependencias.
Exemplos ideais: implementar frontend e backend simultaneamente, escrever testes enquanto outro agente escreve codigo, migrar diferentes modulos em paralelo.
⚙️ Habilitando Agent Teams
Agent Teams e uma feature experimental que precisa ser habilitada explicitamente via variavel de ambiente. Como e experimental, pode mudar entre versoes, mas ja e estavel o suficiente para uso em projetos reais.
🎯 Conceito Principal
A ativacao e feita configurando a variavel de ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Isso habilita a ferramenta interna dispatch_agent que o orchestrator usa para criar e gerenciar subagentes.
-
•
Variavel de ambiente:
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1no seu shell ou .bashrc -
•
Verificacao: Apos ativar, rode
/statuse confirme que "Agent Teams" aparece como habilitado - • Requisitos: Git instalado (para worktrees), espaco em disco (cada worktree e uma copia), e limite de API suficiente para chamadas paralelas
- • Custo: Agent Teams consome mais tokens porque multiplos agentes trabalham simultaneamente. Monitore com /cost
💻 Como Habilitar
💡 Dica Pratica
Ative Agent Teams apenas quando for usa-lo. Em tarefas simples, o overhead de coordenacao e worktrees nao compensa. Use para tarefas grandes e paralelizaveis. Para o dia a dia, o modo normal e mais eficiente.
Certifique-se de que seu repositorio esta em um estado limpo (sem mudancas nao commitadas) antes de iniciar Agent Teams. Worktrees funcionam melhor a partir de um estado git limpo.
📤 Subagentes e delegacao de tarefas
Com Agent Teams habilitado, o Claude pode usar a ferramenta dispatch_agent para criar subagentes com tarefas especificas. Cada subagente recebe instrucoes claras, trabalha independentemente e reporta o resultado ao orchestrator.
🎯 Conceito Principal
A delegacao segue o padrao de task decomposition: o orchestrator divide a tarefa grande em subtarefas menores, cria um subagente para cada uma com instrucoes especificas, e aguarda os resultados para combinar tudo.
- • Instrucoes claras: Cada subagente recebe um prompt especifico com escopo bem definido: o que fazer, onde fazer e o que nao tocar
- • Contexto compartilhado: O CLAUDE.md do projeto e acessivel a todos os subagentes, mantendo consistencia de estilo e convencoes
- • Execucao paralela: Os subagentes trabalham ao mesmo tempo, cada um em seu worktree. O orchestrator monitora o progresso
- • Report de resultado: Cada subagente reporta: o que foi feito, quais arquivos foram modificados e se os testes passam
💻 Exemplo de Delegacao
💡 Dica Pratica
A qualidade da delegacao depende da clareza das instrucoes. Seja especifico: em vez de "implemente o backend", diga "implemente os endpoints GET /products, POST /products, PUT /products/:id e DELETE /products/:id em src/routes/products.ts seguindo o padrao de src/routes/users.ts".
Evite dependencias circulares entre subagentes. Se o subagente de testes precisa do codigo do subagente de API, eles nao podem rodar em paralelo. Nesse caso, use execucao sequencial.
🔄 Loop agentico autonomo
O loop agentico e quando o Claude Code opera em modo autonomo por periodos estendidos, tomando decisoes, executando acoes e se auto-corrigindo sem intervencao humana. Com Agent Teams, esse loop se multiplica - cada subagente tem seu proprio loop autonomo.
🎯 Conceito Principal
O loop agentico segue o ciclo: Observe → Think → Act → Verify → Repeat. O Claude observa o estado atual, pensa na proxima acao, executa, verifica o resultado e decide se precisa continuar. Esse loop roda ate a tarefa estar completa ou um limite ser atingido.
- • Observe: Le arquivos, roda testes, verifica estado do git para entender a situacao atual
- • Think: Planeja a proxima acao baseado no que observou e no objetivo da tarefa
- • Act: Edita arquivos, roda comandos, cria testes - executa a acao planejada
- • Verify: Roda testes, build e linting para confirmar que a acao teve o efeito esperado
💻 Loop em Acao
💡 Dica Pratica
O loop agentico e mais eficaz quando voce define criterios claros de conclusao: "Para quando todos os endpoints tiverem validacao E todos os testes passarem." Sem criterios claros, o loop pode ficar indefinido ou parar cedo demais.
Use /cost apos loops longos. Um loop de 20+ iteracoes pode consumir muitos tokens. Configure limites: "Se o custo ultrapassar $2, pare e me avise."
🌳 Worktrees isolados (git worktree)
A base tecnica de Agent Teams sao os git worktrees: cada subagente trabalha em uma copia isolada do repositorio, evitando conflitos quando multiplos agentes editam arquivos ao mesmo tempo. Entender worktrees e fundamental para usar Agent Teams efetivamente.
🎯 Conceito Principal
Um git worktree e um diretorio de trabalho adicional vinculado ao mesmo repositorio git. Cada worktree pode estar em uma branch diferente e ter modificacoes independentes. O Claude cria worktrees temporarios para cada subagente e os remove apos o merge.
- • Isolamento completo: Cada subagente edita arquivos em seu proprio worktree sem afetar os outros. Sem conflitos de edicao
- • Branches separadas: Cada worktree opera em sua propria branch, facilitando o merge posterior
- • Mesmo .git: Todos os worktrees compartilham o mesmo repositorio git, economizando espaco e mantendo a historia unificada
- • Cleanup automatico: Apos o merge, o Claude remove os worktrees temporarios automaticamente
💻 Como Funciona
💡 Dica Pratica
Worktrees consomem espaco em disco (cada um e basicamente uma copia do seu projeto, menos o .git). Em projetos grandes (>1GB), monitore o espaco disponivel antes de criar multiplos worktrees.
Voce tambem pode usar worktrees manualmente (sem Agent Teams) para trabalhar em multiplas tarefas simultaneamente: git worktree add ../feature-x feature/x.
🧭 Quando usar e quando evitar
Agent Teams e loop agentico sao ferramentas poderosas, mas nao sao para toda tarefa. Saber quando usar e tao importante quanto saber como usar. O overhead de coordenacao, custo de tokens e risco de conflitos tornam essa decisao critica.
🎯 Conceito Principal
O framework de decisao e simples: se a tarefa pode ser feita por um unico agente em menos de 30 minutos, nao use Agent Teams. O overhead de coordenacao so compensa quando ha paralelismo real e a tarefa e grande o suficiente.
- • Use quando: Tarefa tem 3+ subtarefas independentes, levaria >1h para um agente solo, envolve areas diferentes do codebase (frontend + backend + testes)
- • Evite quando: Tarefa e sequencial (cada passo depende do anterior), envolve poucos arquivos (<5), ou requer decisoes de design que precisam de supervisao humana
- • Custo: Agent Teams consome 2-4x mais tokens que um agente solo. Justifica-se quando o speedup de tempo compensa o custo extra
- • Risco: Mais agentes = mais chances de conflito no merge. Minimize designando areas de arquivo nao-sobrepostas para cada subagente
✓ Bons candidatos para Agent Teams
- ✓ Implementar feature full-stack (API + UI + testes)
- ✓ Migracao de 20+ arquivos com areas independentes
- ✓ Gerar testes para multiplos modulos simultaneamente
- ✓ Refatoracao + documentacao + testes em paralelo
✗ Evite Agent Teams para
- ✗ Bug fix em um unico arquivo
- ✗ Tarefas com alta dependencia entre subtarefas
- ✗ Decisoes de arquitetura que precisam de supervisao
- ✗ Projetos muito pequenos (<10 arquivos)
💡 Dica Pratica
Comece com Agent Teams em tarefas de baixo risco (geracao de testes, documentacao) antes de usa-lo para implementacao de features criticas. Isso permite que voce entenda o comportamento e os limites da ferramenta sem arriscar o codigo de producao.
Regra pratica: se voce nao confia no resultado de um unico agente para a tarefa, nao confie no resultado de multiplos agentes. Agent Teams amplifica capacidade, mas tambem amplifica erros.
🏋️ Exercicio Pratico
Configurar Agent Teams e executar tarefa multi-agente
Habilitar Agent Teams
Configure a variavel de ambiente e verifique:
Confirme que Agent Teams aparece como habilitado.
Definir tarefa paralelizavel
Escolha uma tarefa que tenha subtarefas independentes:
Monitorar execucao
Observe os subagentes trabalhando e monitore o custo:
Anote o tempo total e o custo. Compare com quanto levaria com um agente solo.
Verificar resultado e merge
Confirme que tudo foi mergeado corretamente e os testes passam:
Todos os testes devem passar e os commits dos subagentes devem estar no historico.
✅ Criterios de Sucesso
📋 Resumo do Modulo
Proximo Passo:
Trilha 4 - Prompts: Engenharia de Prompt para Claude Code