🌿 Git Worktrees — Paralelismo Seguro
Rodar dois agentes Claude na mesma pasta é uma receita para conflito. Quando o Agente A modifica src/auth.ts e o Agente B também modifica o mesmo arquivo ao mesmo tempo, um sobrescreve o outro — silenciosamente. Git Worktrees resolvem isso de forma estrutural, criando cópias paralelas e eficientes do projeto, cada uma em sua própria branch.
🌿 Como Worktrees Funcionam
Cada worktree é um diretório separado no disco, com sua própria cópia do working tree, mas compartilhando o mesmo repositório git. Isso é mais eficiente que clonar — arquivos não modificados são links, não cópias.
- • Cada worktree tem sua própria branch ativa
- • Mudanças em um worktree não afetam os outros
- • Todos compartilham o mesmo histórico git
- • Mesclagem normal via pull request ou git merge
# Criar worktrees para duas features paralelas
$ claude-worktree feature-auth
> Criando worktree em ../projeto-feature-auth (branch: feature-auth)
> Workspace pronto. Claude Code iniciado.
# Em outro terminal
$ claude-worktree feature-payments
> Criando worktree em ../projeto-feature-payments (branch: feature-payments)
> Workspace pronto. Claude Code iniciado.
# Verificar worktrees ativos
$ git worktree list
/home/user/projeto abc1234 [main]
/home/user/projeto-feature-auth def5678 [feature-auth]
/home/user/projeto-feature-payments ghi9012 [feature-payments]
# Ao finalizar, mesclar de volta
$ git merge feature-auth
$ git merge feature-payments
$ git worktree remove ../projeto-feature-auth
💡 Dica Prática
Abra cada worktree em uma aba ou janela separada do terminal. Use nomes descritivos que refletem a tarefa do agente — claude-worktree refactor-api é mais claro que claude-worktree wt1. Você pode ver claramente o que cada agente está fazendo pelo nome do diretório.
✓ O que FAZER
- ✓ Criar um worktree por feature ou tarefa independente
- ✓ Usar nomes descritivos que identificam a tarefa
- ✓ Remover worktrees após mesclagem para manter limpo
- ✓ Usar para features que não dependem uma da outra
✗ O que NÃO fazer
- ✗ Rodar dois agentes na mesma pasta sem worktrees
- ✗ Criar worktrees para tarefas que dependem uma da outra
- ✗ Deixar dezenas de worktrees abandonados acumulando
- ✗ Confundir worktrees com múltiplos clones do repositório
🤝 Equipes de Agentes — Coordenação Total
Subagentes rodam em paralelo, mas não se falam. Cada um vive no seu silo — começa com contexto novo, executa sua parte, e não tem ideia do que os outros estão fazendo. Equipes de agentes quebram esse isolamento. Os membros compartilham uma lista de tarefas, se comunicam diretamente e coordenam o trabalho em tempo real.
🤝 Subagentes vs Equipes de Agentes
Subagentes (Hack anterior)
- →Rodam em paralelo, contexto isolado
- →Sem comunicação entre si
- →Mais rápido e mais barato
- →Bom para tarefas independentes
Equipes de Agentes
- →Lista de tarefas compartilhada
- →Comunicação direta entre membros
- →Mais lento e mais caro
- →Saída muito mais coesa
# Você fala com o agente coordenador
Você: Crie uma equipe para construir o módulo de pagamentos.
Agente A: API do Stripe. Agente B: UI de checkout. Agente C: testes.
[Agente Coordenador]
Claude: Equipe criada. Distribuindo tarefas...
→ Agente A: implementar endpoints /payment/create e /payment/confirm
→ Agente B: aguardando contrato de API do Agente A antes de prosseguir
→ Agente C: escrevendo testes de integração conforme API é definida
# Você pode falar diretamente com qualquer agente
Você: @AgentB use o design system existente para o checkout.
[Agente B recebe a instrução diretamente]
Agente B: Entendido. Usando componentes de /src/design-system/...
📊 Quando Vale o Custo Extra
- Projetos grandes com interdependências: Onde partes diferentes precisam se alinhar constantemente
- Saída coesa exigida: Documentação, sistemas com UI + API + testes integrados
- Revisão cruzada: Agentes podem revisar o trabalho um do outro antes de entregar
- Atribuição dinâmica: Membros podem reatribuir tarefas conforme blockers aparecem
💡 Dica Prática
Reserve equipes de agentes para projetos onde a coesão importa mais que a velocidade. Para tarefas independentes que você pode mesclar depois, subagentes com worktrees são mais eficientes. Use a pergunta: "esses agentes precisam se falar para produzir um resultado bom?" Se sim, use equipes. Se não, use subagentes.
✅ Resumo do Módulo 3.1
Próximo Módulo:
3.2 — 🏗️ Automação e Infraestrutura: /loop, VPS e controle remoto pelo celular