Git worktrees: um cérebro, vários agentes a trabalhar em paralelo

Imagine um único repositório com várias áreas distintas - um frontend, um backend, alguma infra-estrutura, a ligação do CI/CD - e vários agentes a trabalhar nele ao mesmo tempo, cada um no seu branch. Quer que avancem em paralelo sem se atrapalharem uns aos outros e quer uma inteligência central capaz de ver todo o trabalho de uma só vez: rever o diff de um agente, fazer merge do de outro, resolver um conflito, manter o conjunto coerente. As respostas ingénuas falham ambas. Os worktrees do Git são a resposta que não falha.

O problema: um checkout só contém um branch

Um clone normal só pode ter um branch em checkout de cada vez. Se o agente A muda o directório de trabalho para o seu branch, os ficheiros do agente B mudam-lhe debaixo dos pés - pôs toda a gente em fila à volta de uma única secretária. A solução óbvia são N clones completos, um por agente. Isso funciona, mas cada clone é o seu próprio .git: uma cópia completa do histórico, os seus próprios remotes, o seu próprio estado de fetch. Não partilham objectos nem se conhecem localmente, por isso mover um branch de um para outro implica uma ida e volta pelo remote.

N clones duplicam todo o histórico e só conseguem trocar trabalho através do remote. Os worktrees mantêm um único armazenamento de objectos partilhado, por isso os branches vivem lado a lado e quaisquer dois podem ser comparados ou unidos por merge localmente.

Os worktrees são o caminho do meio: um repositório - um .git, um armazenamento de objectos, um conjunto de branches - com vários directórios de trabalho, cada um em checkout num branch diferente, todos activos ao mesmo tempo. Isolamento do estado de trabalho, partilha do histórico.

O que é, de facto, um worktree

Pense num repositório como um cérebro e uma secretária. O cérebro é o .git: a base de dados de objectos, as refs, a configuração. A secretária é o directório de trabalho: os ficheiros que de facto edita. Um clone normal liga exactamente uma secretária a um cérebro. Um worktree separa-os - um cérebro, várias secretárias.

Cada secretária é um directório real no disco, em checkout num determinado branch, com o seu próprio HEAD e o seu próprio index (a área de staging). Mas todas partilham o mesmo armazenamento de objectos, por isso não há histórico duplicado e o custo em disco de uma secretária adicional é mínimo. Uma regra mantém toda a gente segura: o mesmo branch não pode estar em checkout em dois worktrees ao mesmo tempo. O Git simplesmente recusa - e essa recusa é exactamente o que impede dois agentes de corromperem o mesmo branch.

Um único armazenamento de objectos .git contém todo o histórico e todos os branches; cada directório de trabalho faz checkout de um branch diferente, com o seu próprio HEAD e index. Acrescente ou remova secretárias a baixo custo - o cérebro é partilhado.

Como funciona

Toda a interface se resume a um subcomando. A partir do seu repositório principal, acrescenta uma secretária, aponta-a a um branch (novo ou existente), e o git cria o directório e faz-lhe checkout:

# está no repositório principal (o "main worktree")
cd ~/work/app

# uma secretária para o agente do backend, num branch novo
git worktree add ../wt-backend -b feature/be-auth

# o agente do frontend, no seu próprio branch novo
git worktree add ../wt-frontend -b feature/fe-redesign

# o agente da infra, a partir de um branch existente
git worktree add ../wt-infra existing-infra-branch

git worktree list     # cada secretária + o branch de cada uma
git worktree remove ../wt-backend   # arrumar quando terminar
git worktree prune    # remover entradas administrativas obsoletas

No disco passa a ter pastas irmãs - o repositório principal mais wt-backend, wt-frontend, wt-infra - cada uma num branch diferente. Nos bastidores, as secretárias secundárias não carregam um directório .git completo; contêm um pequeno ficheiro .git que aponta de volta para o .git/worktrees/<name>/ do repositório principal. Continua a haver apenas um armazenamento de objectos. Um branch criado numa secretária fica logo visível a partir de todas as outras, porque há apenas um repositório.

Porque é este o substrato certo para vários agentes

O armazenamento de objectos partilhado é a chave de tudo. Como cada branch vive numa única base de dados, um agente coordenador instalado no main worktree pode operar sobre o trabalho de toda a gente sem tocar num remote: git log --all vê tudo, pode fazer diff entre os branches de quaisquer dois agentes, cherry-pick entre eles, merge, resolver conflitos - tudo localmente, na hora.

Edições paralelas e isoladas - cada agente é dono de um directório, por isso não há colisões de ficheiros.
Um branch por agente - imposto pelo git; o mesmo branch não pode estar activo em duas secretárias.
Barato de criar e desmontar - as secretárias partilham objectos, por isso criar ou remover uma demora segundos.
Um cérebro central - um único .git significa uma única fonte da verdade sobre a qual o orquestrador pode raciocinar: todos os branches, todos os commits, o histórico inteiro.
Compilações e testes independentes - cada secretária tem o seu próprio node_modules, o seu próprio resultado de build e as suas caches, por isso os agentes correm os seus pipelines ao mesmo tempo sem se atropelarem.

Este último ponto é fácil de subestimar. Directórios de trabalho separados significam estado de build separado, por isso um agente do frontend pode correr o seu servidor de desenvolvimento enquanto o agente da infra aplica Terraform numa sandbox e o agente do backend corre a sua bateria de testes - nenhum deles a disputar os mesmos ficheiros.

Formas de trabalhar

Os worktrees são um substrato, não um método. Alguns padrões encaixam-se bem em equipas reais e em frotas reais de agentes.

Orquestrador e trabalhadores

O main worktree é o cérebro central. Lança um trabalhador por worktree, cada um no seu branch. Os trabalhadores fazem commit nos seus branches; o orquestrador integra - merge, rebase, cherry-pick entre eles, localmente - depois faz push e abre os pull requests. É o que melhor corresponde a "uma inteligência, vários agentes".

O orquestrador vive no main worktree e consegue ver todos os branches de uma só vez. Cada agente trabalha na sua secretária, no seu branch; o orquestrador revê, faz merge localmente, depois faz push e abre PRs.

Um worktree por área (de vida longa) - wt-fe, wt-be, wt-infra, wt-cicd como secretárias semi-permanentes que espelham as suas aplicações. Ideal quando agentes ou equipas correspondem bem a subsistemas.
Um worktree por tarefa (efémero) - crie uma secretária nova para cada funcionalidade ou bug e deite-a fora ao fazer merge. Ideal quando o trabalho tem forma de tarefa em vez de forma de equipa.
Um worktree de integração - uma secretária dedicada onde o orquestrador faz continuamente merge de toda a gente, para apanhar conflitos cedo. O seu canário do "isto tudo ainda encaixa?".

No Claude Code isto já vem incluído

Se conduzir os agentes com o Claude Code, o padrão de worktree é nativo, em vez de algo que tenha de montar à mão. Um sub-agente pode ser lançado com isolamento por worktree - corre no seu próprio worktree criado automaticamente, e a secretária é limpa no fim, ou seja, o padrão efémero automatizado. Há também ferramentas para mover a sessão actual para dentro e para fora de um worktree. Assim, "uma inteligência central a orquestrar N agentes em N branches" torna-se: esta sessão é o cérebro no main worktree, cada agente lançado recebe o seu próprio worktree isolado, e a integração acontece de volta na secretária principal.

Armadilhas que vale a pena conhecer

O mesmo branch em dois worktrees é bloqueado - de propósito. Dê a cada secretária um branch distinto.
Os artefactos de build são por worktree - o node_modules e afins não são partilhados, por isso cada secretária precisa da sua própria instalação. Normalmente é o que se quer para haver isolamento, mas é disco e tempo a sério.
Não aninhe um worktree dentro do repositório - ou o git vai tentar segui-lo como ficheiros. Mantenha as secretárias como pastas irmãs (../wt-*) e ignore o padrão se alguma vez as guardar lá dentro.
Use git worktree remove, não rm -rf - apagar a pasta à mão deixa uma entrada administrativa obsoleta; o git worktree prune limpa essas.
Os hooks e a configuração são partilhados - todas as secretárias lêem o mesmo .git/config e os mesmos hooks. Normalmente não há problema, ocasionalmente apanha-o de surpresa.
Os submódulos acrescentam atrito entre worktrees - se o seu repositório os usar, conte com configuração extra por secretária.

O modelo mental é todo o truque: um cérebro, várias secretárias. Deixe de pensar num repositório como uma pasta dentro da qual muda de branch e comece a pensar nele como um único histórico partilhado a partir do qual qualquer número de directórios de trabalho pode ler ao mesmo tempo. É isso que permite a uma inteligência central coordenar uma frota de agentes - cada um seguro no seu próprio branch - enquanto o histórico que todos partilham se mantém a única fonte da verdade.