🎯 Lead, teammate e mailbox
Em uma sessão tradicional do Claude Code, há um único agente conversando com você. Em um agent team, surgem três entidades novas que você precisa conhecer para ler logs, doc e prompts.
🧱 Os 3 papéis
- •Lead — a sessão principal. Cria o time, spawna teammates, sintetiza resultados.
- •Teammate — uma instância Claude Code completa, com contexto próprio. O time pode ter 2 a 10+.
- •Mailbox — o canal de mensagens P2P entre teammates (e entre teammate e lead).
📂 Onde tudo isso vive em disco
- Config do time:
~/.claude/teams/{team-name}/config.json - Lista de tasks:
~/.claude/tasks/{team-name}/ - Não edite à mão: Claude regrava esses arquivos a cada update de estado.
🧠 Por que o paradigma muda
Trabalhar com um único agente é sobre "qual prompt eu mando". Trabalhar com um time é sobre "qual squad eu monto". É design organizacional aplicado à IA.
✓ Mentalidade de time
- ✓Especialização por papel
- ✓Paralelismo real
- ✓Comunicação direta entre pares
- ✓Quality gates ativos (QA reage)
✗ Mentalidade de "1 chat só"
- ✗Generalismo do agente único
- ✗Sequencialização forçada
- ✗Tudo passa pelo "operador humano"
- ✗Validação só no final
🔄 O ciclo lead → spawn → mensagem → síntese
Conhecer o ciclo de execução é o que te permite diagnosticar quando o time trava. Sem ele, você só vê "alguma coisa não está acontecendo".
Lead recebe o prompt
Você descreve goal + roles + deliverables. Lead avalia se vale spawnar um time.
Spawn em paralelo
Lead cria N teammates ao mesmo tempo, cada um com seu próprio prompt de papel.
Trabalho concorrente + mensagens
Cada teammate trabalha no seu território. Quando precisa, manda mensagem direta para outro via mailbox.
Idle notification
Quando termina, teammate notifica o lead automaticamente.
Síntese pelo lead
Lead consolida findings, decide se aceita ou pede retrabalho, devolve o resultado para você.
💡 Dica prática
Quando o time "parece travado", o problema quase sempre é (a) idle notification que não disparou, (b) task com dependência não resolvida, ou (c) teammate esperando mensagem que nunca chegou. Saber o ciclo te dá os 3 lugares para olhar.
📋 Shared task list
A task list compartilhada é a "memória de trabalho" do time. Diferente de uma to-do humana, ela tem semântica: estados, dependências e file locking.
📊 Anatomia de uma task
- •Estados:
pending→in_progress→completed - •Dependências: task pode estar bloqueada por outra; só desbloqueia quando a dependência completa
- •Claim: teammate pode pegar (claim) uma task disponível; lead pode atribuir explicitamente
- •File locking: previne dois teammates pegarem a mesma task simultaneamente
📐 Regra prática de tamanho
A doc oficial recomenda 5 a 6 tasks por teammate:
- • Pequeno o suficiente para entregar deliverable claro
- • Grande o suficiente para o coordenado custar a pena
- • Permite reassign se um teammate empacar
💬 Comunicação direta entre teammates
É a feature que separa "agent team" de "vários subagentes". Sem ela, todo handoff vira gargalo no lead.
📨 Como funciona
- •Lead atribui um nome a cada teammate ao spawnar
- •Qualquer teammate (ou o lead) pode chamar a tool
SendMessagecom o nome do destinatário - •A mensagem é entregue automaticamente — o lead não precisa "fazer poll"
- •"Broadcast" não existe nativamente: para mandar para todos, é uma mensagem por destinatário
💡 Nomes previsíveis
Especifique nomes no prompt do spawn: "spawn a team called Neuroflow with backend_dev, frontend_dev, qa". Assim você consegue mensagear cada um por nome em prompts subsequentes.
🪜 Quando o trabalho realmente paraleliza
Times mal desenhados ficam serializados na prática: 5 agentes mas só 1 trabalhando por vez. Custo alto, ganho zero. A regra é simples: paralelismo só existe quando há independência.
✓ Casos paralelizáveis
- ✓Front + back + tests (cada um seu território)
- ✓PR review com 3 lentes (security, perf, tests)
- ✓Debug com 5 hipóteses concorrentes
- ✓Refactor cross-module sem mesmo arquivo
✗ Casos serializados
- ✗"Pesquisa → escreve → revisa" sequencial
- ✗Vários teammates editando o mesmo arquivo
- ✗Migração que precisa ordem estrita
- ✗Tarefa cabe em um único contexto
⚠️ Sintoma de time serializado
Você abre o tmux/Shift+Down e vê 4 teammates ociosos enquanto 1 trabalha. É a hora de redesenhar tasks ou reduzir o time.
📌 Resumo do Módulo
Próximo módulo:
1.2 — Subagentes vs Teams: contexto, custo e árvore de decisão