🚀 Versão e flag experimental
Pré-requisito hard: Claude Code v2.1.32+. Verifique com claude --version. Habilite com CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 em settings.json (projeto ou user) ou no env.
📌 Onde colocar a flag
Pode ir em 3 lugares; escolha por escopo.
- •
.claude/settings.json— projeto - •
~/.claude/settings.json— user - •Variável de ambiente — sessão
- •Recomendado: settings.local.json no projeto
⚠️ Erro silencioso
Sem a flag, comandos de team falham sem mensagem clara. Sintoma: 'Claude não cria os agentes'.
🖥️ Modos de display
teammateMode aceita 3 valores. Padrão é auto: usa tmux se já estiver dentro de tmux, senão in-process. Para forçar, use --teammate-mode.
✓ Tmux/iTerm2 (split-pane)
- ✓Cada teammate em pane próprio
- ✓Diagnóstico ao vivo
- ✓Mais natural para demos
- ✓macOS: tmux -CC dentro de iTerm2
✗ VS Code/Win Terminal/Ghostty
- ✗NÃO suportam split
- ✗Use in-process
- ✗Funciona, só não é split
- ✗Cheque
which tmux
🔐 Permissões herdadas e pré-aprovação
Teammates herdam permissões do lead. Sem pré-aprovação, cada um pausa pedindo permissão a cada npm/git. Allowlist no settings é a primeira correção que dobra produtividade.
📌 Allowlist canônica para projetos JS
Padrões de comando que cobrem 90% dos casos.
- •
Bash(npm install) - •
Bash(npm test*) - •
Bash(git status) - •
Bash(git diff*) - •Edit, Write, Read
⚠️ --dangerously-skip-permissions
É pegada: liga em produção e pode rodar rm -rf por engano. Use só em dev isolado.
📚 Treinar o repo com docs locais
Salve a doc oficial em docs/agent-teams-reference.md. O lead consulta localmente, decisões ficam mais rápidas e melhores. Reduz busca web em runtime.
📌 Estrutura recomendada
Pastas que valem a pena criar de cara.
- •
docs/— refs locais - •
prompts/— templates de spawn - •
.claude/agents/— subagent definitions - •
.claude/hooks/— scripts dos hooks
💡 Aponte o CLAUDE.md
Adicione referência aos docs no CLAUDE.md para o lead saber que existem.
🧩 MCP servers e skills herdadas
MCP servers e skills configurados no projeto/user ficam disponíveis a todos os teammates. Configurar 1 vez vale para 5+ teammates. É uma alavanca enorme que muitos esquecem.
⚠️ Subagent definitions são exceção
Quando você usa um subagent definition como tipo de teammate, os campos skills e mcpServers do frontmatter são ignorados — teammates carregam sempre do projeto/user.
💡 Skills úteis para teams
skill-creator, simplify, formato-curso, n8n-* — vale revisar quais skills você tem ativas.
✅ Smoke test: o demo Neuroflow
Use o prompt do vídeo (Backend + Frontend + QA, todos em Sonnet) e observe o ciclo: spawn paralelo → trabalho → QA reprova → retrabalho → QA aprova → entrega.
Spawn
Lead cria 3 teammates
Você vê 3 prompts iniciais nos logs
Trabalho
Cada um no seu território
Backend em src/api, Frontend em src/ui, QA em tests/
QA reprova
3 issues críticos
Mensagens P2P para Backend e Frontend
Retrabalho
Backend e Frontend reagem
Edição direta sem passar pelo lead
QA aprova
Tests verdes
Idle notifications chegam no lead
💡 Se o smoke passa, setup está sólido
Daí em diante, qualquer falha é prompt, não configuração.
📌 Resumo do Módulo
Próximo módulo:
2.2 — Anatomia do prompt de spawn