Você entrega um bug ao Claude Code e uma pequena funcionalidade ao Codex, sai de perto e, quando volta, encontra um arquivo que parece errado. A edição de um dos agentes sumiu. Ou as duas edições estão lá e o build falha. Ou, pior ainda, tudo compila e um teste quebra em algum lugar que nenhum dos agentes tocou. Nada travou enquanto você estava fora. Os dois agentes fizeram o trabalho que você pediu. O arquivo não conseguiu comportar dois autores ao mesmo tempo, e ninguém te avisou qual deles venceu.
Esse silêncio é o verdadeiro problema. Um arquivo não é uma ferramenta de merge. Quando dois agentes de código escrevem em auth.ts no mesmo diretório em momentos sobrepostos, não existe lock, não existe fila, não existe aviso; existe apenas o processo que salvou por último. Este artigo percorre a colisão passo a passo, nomeia o modo de falha em cada etapa e termina com um checklist que você pode executar antes da sua próxima sessão paralela.
Ele também aponta para o fluxo de trabalho ao qual essas correções levam. O Sharkly é uma plataforma tudo-em-um de comando e gestão de Agentes que fica acima dos agentes de código que você já usa. Ela dá a cada Task seu próprio worktree isolado e mantém contexto, progresso, bloqueios, resultados e revisão humana visíveis desde a solicitação até a entrega. Você pode construir a mesma disciplina manualmente com Git puro, e a maior parte deste artigo mostra como. A última seção trata de quando fazer isso na mão deixa de valer a pena.
Não existe lock: quem escreve por último vence
Comece pela pior versão, porque é a mais comum e a menos visível. Os dois agentes rodam no mesmo diretório de trabalho. O Agente A lê auth.ts, planeja uma alteração e começa a escrever. O Agente B lê o mesmo auth.ts um segundo depois, planeja uma alteração diferente com base na versão que leu e também escreve.
Nenhum dos dois leu a edição do outro, porque a edição ainda não tinha sido salva quando eles leram. Quem salva por segundo sobrescreve o arquivo em disco com uma versão que nunca conteve o trabalho do primeiro agente. Isso é o last-write-wins, e ele é silencioso. Não há marcador de conflito, não há erro, não há código de saída. O Agente A relata sucesso. O Agente B relata sucesso. Um deles está mentindo para você e não sabe disso.
A corrida pelo lockfile é a mesma falha num lugar mais caro. O Agente A roda npm install e reescreve o package-lock.json; o Agente B, no meio da instalação, reescreve o arquivo de novo a partir de um estado inicial diferente. O resultado é um lockfile que não corresponde a nenhuma das duas árvores de dependências, e a quebra aparece na máquina de outra pessoa dias depois. Saídas de build compartilhadas, uma única porta de dev-server e um cache global falham exatamente da mesma forma.
A solução não é um agente mais inteligente. É dar a cada agente uma sala só dele.
Uma cópia de trabalho por agente: a sobrescrita silenciosa vira um conflito visível
Um worktree do Git é uma segunda cópia de checkout de um mesmo repositório, em seu próprio branch, compartilhando um único armazenamento de objetos .git. Cada agente ganha um diretório real para editar, compilar e testar sem enxergar o trabalho em andamento de ninguém.
# From the main repo
git worktree add ../repo-agent-a -b agent/auth-refactor
git worktree add ../repo-agent-b -b agent/session-timeout
Aponte o Agente A para ../repo-agent-a e o Agente B para ../repo-agent-b. Agora as edições não salvas de A em auth.ts são invisíveis para B, e nenhum dos agentes pode sobrescrever o arquivo do outro em disco, porque estão editando dois arquivos diferentes em dois branches diferentes. O modelo de worktree é abordado com mais profundidade em Git worktrees para agentes de código de IA e worktrees de agentes de código: um checkout por tarefa.
Repare no que o isolamento fez aqui. Ele não impediu que os dois agentes editassem o mesmo arquivo. Ele converteu uma perda silenciosa de dados em um conflito de merge visível no momento em que os branches voltam a se encontrar. Isso é um avanço real: o Git para e mostra exatamente as linhas em desacordo, e você as resolve com plena visão das duas versões. Um conflito que você consegue ver é um problema que você consegue corrigir. A sobrescrita que você não conseguia ver era a que ia para produção.
Vale deixar claro um limite: worktrees isolam arquivos, não efeitos colaterais. Um banco de dados compartilhado, uma única porta ou um caminho de saída fixado no código ainda colidem entre worktrees. Isole esses também, ou serialize os agentes que precisam deles.
O conflito que você não consegue ver
Aqui está o modo de falha que sobrevive ao isolamento. O Agente A, trabalhando em seu próprio worktree, renomeia getUser() para fetchUser() e atualiza todos os pontos de chamada que ele possui. O Agente B, trabalhando em seu próprio worktree ao mesmo tempo, escreve três novos pontos de chamada para getUser(), porque era esse o nome da função quando B leu o arquivo.
Os dois branches fazem merge sem nenhum marcador de conflito. O Git compara linhas, e linha por linha nada se sobrepôs: A alterou seus arquivos, B adicionou novos. O merge está limpo. Então o build quebra por um getUser indefinido, ou compila e falha em tempo de execução onde o verificador de tipos não conseguiu alcançar. Nenhuma ferramenta sinalizou isso, porque textualmente não houve colisão. As duas edições discordavam quanto ao significado do arquivo, não quanto ao seu texto.
É por isso que "simplesmente isole os agentes" não é a resposta completa. O isolamento adia uma colisão no mesmo arquivo para uma colisão na mesma interface, e o segundo tipo se esconde melhor do que o primeiro. A alavanca aqui é o escopo das tarefas, não as ferramentas. Uma regra útil: se você não consegue descrever as tarefas de dois agentes sem citar o mesmo arquivo ou a mesma função, elas são uma tarefa só, não duas. Dividir o trabalho ao longo das fronteiras entre módulos é a maior parte do que impede Claude Code e Codex trabalhando juntos em uma única base de código de virar uma tarde inteira de depuração. Quando duas tarefas realmente compartilham uma interface, serialize-as, ou faça merge e rebase entre as etapas para que o segundo agente leia a realidade do primeiro.
Onde a configuração faça-você-mesmo para de escalar, e o que um quadro de tarefas acrescenta
Dois agentes e um arquivo compartilhado, você consegue gerenciar na mão: dois worktrees, escopo cuidadoso, um merge que você acompanha. O método se sustenta até a contagem ficar difícil. Qual agente está em qual branch. Qual worktree corresponde a qual tarefa. Qual de cinco merges limpos alterou silenciosamente uma interface compartilhada. Quais branches estão esperando sua revisão, e quais você já olhou. Os comandos do Git nunca ficaram mais difíceis; a burocracia em torno deles ficou, e é exatamente nessa burocracia que as colisões no mesmo arquivo passam despercebidas, porque você aprovou um merge que não leu por completo.
Um quadro de tarefas muda o que você acompanha. Em vez de uma parede de terminais e worktrees desanexados, cada unidade de trabalho é uma Task com um responsável, um branch e um estado. No Sharkly, uma Task recebe automaticamente seu próprio worktree isolado, de modo que o isolamento em nível de arquivo é o padrão, e não um comando que você precisa lembrar de rodar. Execução, bloqueios e resultados retornam à Task, para que você revise uma alteração em relação ao escopo declarado dela em vez de fazer engenharia reversa da intenção a partir de um diff. E a divisão do trabalho permanece fixa: agentes pesquisam, executam, testam e relatam; pessoas definem a direção, concedem autoridade e aceitam o resultado. A automação para onde o julgamento da equipe é necessário.
Esse último ponto é o que o isolamento sozinho nunca resolve. Ferramentas melhores tornam o isolamento e o merge mais fáceis, mas a revisão não escala com o número de agentes; ela escala com a sua atenção, e a revisão humana é o verdadeiro gargalo no trabalho com agentes paralelos. Cinco agentes produzem cinco branches no tempo em que você lê um com cuidado. Um quadro de tarefas não lê o código por você. Ele mantém a fila honesta para que a edição que parece plausível não seja passada de olhos e mesclada porque você perdeu a noção de em qual pilha ela estava. A mesma matemática de conflitos aparece no nível do repositório também, abordada em múltiplos agentes de código no mesmo repositório.
Você pode construir isso com worktrees e disciplina, ou usar o Sharkly para gerenciar o fluxo de trabalho. Se você já roda vários agentes, o valor está em ter um só lugar onde as tarefas e os resultados deles vivem, em vez de espalhados por terminais.
O checklist para executar antes da sua próxima sessão paralela
Rode isto antes de apontar dois agentes para qualquer coisa:
- Dê a cada agente seu próprio worktree. Nunca dois agentes em um mesmo diretório de trabalho.
git worktree add ../repo-<task> -b agent/<task>por tarefa. Veja agentes paralelos em worktrees isolados. - Defina o escopo das tarefas de modo que não citem o mesmo arquivo ou a mesma função. Se precisarem, é uma tarefa só; serialize-a.
- Isole os efeitos colaterais, não apenas os arquivos. Bancos de dados, portas, caminhos de saída e caches separados, ou serialize os agentes que os compartilham.
- Faça rebase antes de fazer merge quando dois branches rodaram a partir do mesmo commit inicial, para que o trabalho do segundo agente fique em cima do primeiro.
- Rode a verificação de tipos e a suíte de testes completa após cada merge, não só depois do último. Conflitos semânticos passam por um merge limpo e falham aqui.
- Revise cada branch em relação ao escopo da sua tarefa, um de cada vez. Uma pilha de checkmarks verdes não lidos é onde o conflito invisível vai para produção.
Dois agentes editando um arquivo não é um caso extremo raro; é a cara do trabalho paralelo no momento em que suas tarefas se sobrepõem por um centímetro. Planeje-se para a colisão, torne-a visível e mantenha uma única pessoa decidindo o que vai ser mesclado.
