Como dividir uma tarefa grande entre agentes de IA sem que eles editem o mesmo arquivo?

Tem um momento específico em que a mágica do paralelismo vira dor de cabeça: dois agentes salvam o mesmo arquivo e o trabalho de um simplesmente apaga o do outro

Fala aí, beleza? Disparar vários agentes ao mesmo tempo hoje é trivial, é um comando e pronto

Agora dividir a tarefa de um jeito que eles não se atropelem, isso ninguém planeja antes

E é justamente aí que o tempo economizado com paralelismo volta em forma de merge conflict em série 🙂

Este post é sobre a decisão que vem ANTES de sair paralelizando: qual eixo de isolamento você vai usar

Por que agentes paralelos colidem no mesmo arquivo

O sintoma:

Você abre duas frentes, volta meia hora depois e encontra edição sobrescrita, função que sumiu, import duplicado

Depois vem a fila de conflito pra resolver na mão, e o ganho de rodar em paralelo evapora

A causa:

Subagente do Claude Code roda em janela de contexto separada, e o agente principal recebe só a saída final, não o raciocínio interno (documentação de subagentes)

Ou seja: contexto isolado é ótimo pra não poluir a conversa principal, mas significa que nenhum deles sabe o que o outro escreveu

Subagentes também não conversam entre si, eles reportam de volta pra conversa principal

E a própria Anthropic escreve, com todas as letras, que dois subagentes editando o mesmo arquivo em paralelo é receita de conflito: mudança fortemente acoplada deve ficar em uma só janela de contexto

Aí tem o caso do agent teams, que serve justamente pra trabalho que exige comunicação entre agentes

Só que ele não isola os integrantes em worktrees, então a partição dos arquivos é obrigação SUA

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Como prevenir:

A prevenção é chata de aceitar mas funciona: nem toda tarefa quer ser paralela

A documentação recomenda sessão única ou subagentes para tarefa sequencial, edição no mesmo arquivo e trabalho cheio de dependência

Se o seu caso é esse, o melhor caminho é quebrar a tarefa grande em entregas e tocar em uma sessão só, sem fanfarra

O que você precisa antes de paralelizar

Antes de qualquer comando, se liga na lista mínima:

• Repositório em Git, porque o isolamento por cópia nasce do git worktree add, que cria a working tree ligada e um subdiretório privado em $GIT_DIR/worktrees; dentro da worktree existe um arquivo .git apontando pra esse diretório, e o $GIT_COMMON_DIR aponta de volta pro .git principal (docs do git worktree)
• Claude Code em versão que traz a flag --worktree
• Pasta de subagentes definida: .claude/agents/ pra ficar no projeto e versionar, ou ~/.claude/agents/ pra valer em todos os projetos; a varredura é recursiva e a identidade do subagente vem só do campo name
• A variável CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, se você for usar times de agentes

Um aviso pra você não perder tempo: a partir da v2.1.198 o /agents não abre mais o assistente interativo de criação

Ele apenas imprime um lembrete pedindo que você peça ao Claude ou edite .claude/agents/ direto

Então se você viu tutorial antigo mandando "roda /agents e cria pelo menu", é isso, mudou

Passo a passo: as três formas de isolar o trabalho

São três eixos, e eles se combinam. Bora do mais simples pro mais completão

1. Recortar por arquivo antes de disparar

O recorte é a forma mais barata de isolamento: cada agente é dono de um conjunto de arquivos, e ninguém encosta no conjunto do vizinho

Em agent teams isso deixa de ser boa prática e vira obrigação, já que os integrantes não ganham worktree

Escreva o recorte no prompt de forma explícita, arquivo por arquivo, pasta por pasta

Erro comum deste passo: dois recortes lindos que, no meio do caminho, tocam o MESMO arquivo de config compartilhado

Todo mundo lembra de dividir as features e esquece do arquivo de rotas, do schema, do arquivo de tipos

2. Cópia isolada do repositório (worktree)

Esse é o eixo que resolve o problema de raiz: cada sessão trabalha na própria cópia

claude --worktree meu_worktree

O nome é opcional, e a flag tem forma curta:

claude -w

A worktree nasce em .claude/worktrees/<nome>/ na raiz do repositório, em uma branch nova chamada worktree-<nome>

Se você omitir o nome, o próprio Claude gera um (no formato de exemplo bright-running-fox)

E aqui está o pulo do gato: rodar o comando de novo, com outro nome, em outro terminal, abre uma segunda sessão isolada

Cada sessão na sua própria worktree, e edição de uma NUNCA toca os arquivos da outra

Quem gosta de organizar os terminais tem a flag --tmux, que abre a sessão isolada dentro de uma sessão Tmux própria

Dá pra tornar o isolamento permanente também: você pode pedir ao Claude pra usar worktrees para os agentes, ou fixar isso no frontmatter do subagente personalizado

---
name: refatorador
isolation: worktree
---

E tem um comportamento que vale conhecer: sessão em background começa no diretório de trabalho, migra pra uma worktree isolada sob .claude/worktrees/ antes de editar arquivos, e a partir daí edição e comando que alcancem o checkout principal ficam bloqueados pra ela e pros subagentes que ela criar

Erro comum deste passo: tentar criar worktree de uma branch que já está com checkout em outra worktree

O Git recusa por padrão, isso é proteção, não bug. A flag --force sobrescreve, e é exatamente aí que a galera se fere

3. Uma etapa única de merge no fim

Paralelizar sem etapa de integração é só adiar o conflito, beleza?

Pra acompanhar as sessões em background existe a visão geral:

claude agents

Ela mostra todas as sessões, o estado de cada uma e quais estão esperando resposta

Na hora de encerrar, o comportamento depende de ter trabalho pendente: sem mudança não commitada, sem arquivo novo e sem commit novo, a worktree e a branch são removidas automaticamente

Tendo qualquer um desses, o Claude pergunta se você quer manter ou remover

O Claude Code ainda reconhece o caso já integrado pelo estado do Git: quando a branch remota pra qual a worktree enviou não existe mais e todo commit dela já está na branch padrão

Limpeza na mão é o comando de sempre:

git worktree remove .claude/worktrees/meu_worktree

Com mudança não commitada ou arquivo não rastreado, precisa do --force

Existe também uma varredura periódica que remove worktrees criadas pra subagentes e sessões em background: ela respeita a configuração cleanupPeriodDays, pula worktree que ainda guarda trabalho (arquivo alterado ou não rastreado, commit não enviado) e nunca remove worktree criada com --worktree

Erro comum deste passo: encerrar tudo sem integrar e depois não achar o trabalho

Integre antes de fechar o terminal, sempre

Qual isolamento escolher para cada tipo de tarefa

Mapa de decisão rápido, pra você não precisar decorar:

Se você já brincou de rodar vários agentes em paralelo no OpenCode, o raciocínio é o mesmo: muda a ferramenta, não muda a física do conflito

E tem um caso pra fechar essa seção que eu acho insano: o experimento do compilador C da Anthropic

A coordenação entre os agentes paralelos foi feita por trava em arquivo dentro do próprio repositório: o agente cria um arquivo de texto em current_tasks/ pra travar a tarefa

Se dois tentam a mesma, a sincronização do Git força o segundo a escolher outra; depois ele puxa do upstream, mescla, envia e remove a trava

A escala? 16 agentes, cerca de 2.000 sessões de Claude Code, US$ 20.000 em custo de API e um compilador de 100.000 linhas que compila o Linux 6.9 em x86, ARM e RISC-V

E se liga nisso: mesmo com cada agente clonando uma cópia local do repositório, os conflitos de merge foram FREQUENTES, resolvidos pelo próprio Claude

Isolar não elimina o merge, isolar só te dá o direito de fazer o merge uma vez, no fim, em vez de brigar o tempo todo

O que aprendi rodando dois fluxos paralelos no mesmo projeto

Eu levei essa ideia pro teste mais direto possível: rodei o mesmo projeto (uma loja com catálogo, carrinho, checkout, pedidos e painel admin) em dois frameworks diferentes ao mesmo tempo, Superpowers e GSD, com o mesmo prompt, pra ver até onde cada um leva

A primeira decisão foi de isolamento e nem envolvia agente: duas pastas separadas e um terminal pra cada uma

Parece bobo, mas é o mesmo princípio da worktree em versão manual, cada frente com o seu diretório e zero chance de uma pisar na outra

No fluxo do Superpowers tem uma etapa de git worktree, abrindo branch por funcionalidade antes do ciclo de planejar, escrever com teste, revisar e entregar

O Superpowers é focado em disciplina, funciona como um guardião que força você e o modelo a seguir o processo correto

Já o GSD é focado em contexto: ele levanta dúvida e monta uma base de informação escrita pro projeto, em vez de depender da memória do modelo entre sessões

No GSD eu respondi uma sequência de perguntas de definição antes de UMA linha de código: propósito, nicho, login obrigatório, quem acessa o admin, ciclo de vida do pedido, controle de estoque

As perguntas iniciais dos dois foram parecidas, mas o GSD levantou coisa que o Superpowers não perguntou, tipo controle de estoque no produto e regra de acesso ao admin

No planejamento do GSD eu escolhi dividir o trabalho em MENOS fases, pra não alongar demais a execução e não distorcer a comparação

E deixei os planos rodarem em paralelo

Duas coisas me chamaram atenção na prática

A primeira: o GSD é mais chato na configuração inicial do que aparenta, mesmo o Superpowers tendo mais peças visíveis

A segunda: o GSD saiu mais custoso em tokens por exigir várias sessões, enquanto o TDD do Superpowers ajuda a economizar por reduzir erro

Eu rodei no modo que aprova as ações automaticamente no GSD, e acho que esse modo faz sentido quando você já tem domínio; em projeto mais sério eu prefiro o modo iterativo

E como não estava com permissões totais liberadas, tive que confirmar cada edição de arquivo na mão dos dois lados, o que dá bem a dimensão de quanto trabalho paralelo você consegue realmente supervisionar

Resposta pra dúvida que sempre aparece: sim, os dois podem coexistir no mesmo trabalho

Minha conclusão foi que não existe vencedor único: o Superpowers serve melhor a projeto mais enxuto e rápido, apoiado em disciplina e TDD, e o GSD serve a projeto maior, com dinheiro envolvido, várias sessões e requisito pesado de qualidade e regra de negócio, onde vale planejar antes de sair lançando

No vídeo acima eu mostro os dois rodando lado a lado no mesmo projeto, as perguntas que cada um faz, o plano que cada um monta e onde a coisa aperta 😀

Conclusão

Isolamento não é detalhe de execução, é decisão de arquitetura que você toma ANTES de disparar

Recapitulando os três eixos: recorte por arquivo (obrigatório em agent teams), cópia isolada do repositório com claude --worktree e uma etapa única de merge no fim, com claude agents pra acompanhar e git worktree remove pra limpar

E lembra da regra que corta caminho: mudança acoplada, sequencial ou no mesmo arquivo rende mais em sessão única ou com subagentes, sem paralelismo nenhum

O próximo passo concreto é pequeno: escolha um recorte com duas frentes que NÃO se cruzam, rode claude --worktree em dois terminais e integre com uma etapa única de merge

Se isso funcionar limpo, aí sim você escala pra times e workflows

Faça o teste e me conta como foi, até o próximo post!