🧭 Fundamentos

Lead é a sessão principal que cria o time. Teammate é cada agente independente. Mailbox é o canal de mensagens entre eles.

Sem esse vocabulário você não consegue ler logs, doc oficial nem prompts de spawn. É o "Hello World" do tema.

1 lead por sessão; teammates rodam em paralelo; mailbox entrega mensagens automaticamente; idle notification.

Você deixa de pensar "qual prompt eu mando" e passa a pensar "qual squad eu monto". É design organizacional aplicado a IA.

A maioria dos devs aplica padrões de "1 chat" em times de agentes — e quebra. A mudança mental é o maior unlock.

Especialização > generalismo; paralelismo > sequência; comunicação direta > broadcast.

Lead recebe prompt → cria team → spawna teammates → cada um trabalha → mailbox conecta → idle notification → lead sintetiza.

Ver o ciclo te ajuda a depurar quando algo trava: você sabe exatamente em que estágio o time está.

Auto-delivery; idle = trabalho concluído; lead consolida findings; checkout do trabalho via task list.

Lista de tarefas em ~/.claude/tasks/{team}/ com 3 estados (pending, in_progress, completed) e dependências.

É onde o time mantém estado. Quem entende a task list entende como o lead distribui trabalho.

File locking previne race; pending bloqueada não é claimable; self-claim vs assigned; 5–6 tasks/teammate.

Tool SendMessage permite que teammate A mande mensagem direta para teammate B pelo nome.

É a feature que torna "agent team" diferente de "vários subagents". Sem ela, todo handoff vira gargalo no lead.

Mensagem é unicast (uma para cada destinatário); nomes são definidos no spawn; "broadcast" = N envios.

Trabalho paralelo real só acontece quando os teammates não dependem da saída uns dos outros — ou quando dependem mas via mailbox.

Times mal desenhados ficam serializados na prática: 5 agentes mas só 1 trabalhando por vez. Custo alto, ganho zero.

Independência = território próprio; dependências explícitas via tasks; evite "todos editam o mesmo arquivo".

Subagent roda dentro de uma sessão. Tem contexto próprio, executa a task, devolve resultado para quem chamou — só.

É a forma mais barata e rápida de paralelizar; entender bem evita usar Teams onde subagent já resolve.

Definidos por frontmatter; tools allowlist; não se comunicam entre si; perfeitos para "research + summary".

Teammates são sessões Claude Code completas e independentes que compartilham task list e mailbox.

Permite debate (PR review com 3 lentes), retrabalho (QA → Dev) e cross-layer (front + back + tests).

Contexto independente; comunicação P2P; lead coordena mas não bloqueia; usa muito mais tokens.

Cada teammate = 1 contexto = 1 multiplicador de tokens. 5 teammates = ~5× custo de uma sessão equivalente.

Times grandes parecem "mais inteligentes" mas raramente entregam 5× mais. Saber o custo evita swarms inúteis.

3–5 teammates é o sweet spot; misture modelos (Haiku para QA simples, Sonnet padrão); use subagent quando der.

Subagentes geralmente rodam em sequência (caller espera). Teams rodam concorrentes — o tempo de parede colapsa.

Se o problema é tempo (não custo), Teams ganham. Se é custo (não tempo), subagentes ganham.

Wall-clock vs custo; gargalo = tarefa mais longa; coordenação adiciona overhead.

Subagent: tools controlados por allowlist no frontmatter. Team: teammates herdam permissões do lead no spawn.

Se o lead roda --dangerously-skip-permissions, todo o time também roda. Risco real.

Pré-aprove no settings; modo do teammate pode mudar pós-spawn; nunca dê tools amplas a um QA.

Tarefa simples? Sessão única. Tarefa que polui contexto? Subagent. Tarefas independentes que se conversam? Team.

A maioria dos erros de uso são "Team onde subagent bastava" ou "subagent onde Team era necessário".

3 perguntas: precisa conversar? precisa paralelo real? cabe em 1 contexto? Resposta dita a escolha.

Subagentes definidos em arquivos TOML com name, description, developer_instructions. Codex orquestra spawning, routing e shutdown.

Permite migrar squads entre Claude Code e Codex e usar spawn_agents_on_csv para batch.

Config [agents]: max_threads=6, max_depth=1, job_max_runtime_seconds; nicknames.

Subagentes em .gemini/agents/*.md com YAML frontmatter. Invocação por delegação automática ou @nome.

Modelo "tool exposto ao agente principal" é simples e poderoso; bom para forçar uso (debug determinístico).

Built-ins: codebase_investigator, cli_help, generalist, browser_agent. Sem nesting de subagentes.

Framework Python que modela agentes como "papéis com backstory e goal". Você assembla uma "crew" e dá tasks.

É o jeito mais rápido de prototipar (2–3 dias). Bom mental model para depois portar para Claude Code Teams.

Flows (event-driven, 2025+); papel + goal + backstory; sequencial ou hierárquico; observabilidade limitada.

Microsoft AutoGen (agora AG2) usa GroupChat: múltiplos agentes em uma conversa, selector decide quem fala.

Padrão ideal para "debate" e "dois agentes raciocinando" — exatamente o que Claude Code Teams faz com mailbox.

v0.4 event-driven; pluggable orchestration; AutoGen original em maintenance, AG2 ativo.

Trata workflow de agentes como grafo dirigido: nodes (funções/LLM) + edges (controle) + state (typed dict).

Quando produção exige replay, checkpoint, branching e LangSmith para debug — é a opção mais robusta.

Curva longa (10–14 dias); melhor observabilidade do mercado; ideal para fluxos cíclicos e branching.

Spec open-source da OpenAI que transforma project board (ex: Linear) em painel de controle de agentes.

Aponta para onde o mercado vai: orquestração visual + governança baseada em ticket/issue.

Caso reportado de +500% PRs aterrissados; deterministic, reviewable workflows; Codex MCP server.