O que é e porque importa
Se abrires três sessões do Claude Code na mesma pasta e deres a cada uma um trabalho diferente, mais cedo ou mais tarde atropelam-se. Uma altera um ficheiro enquanto a outra está a trabalhar nele, e no fim já não percebes que alteração veio de quem.
Um worktree resolve exatamente isto. É uma cópia do projeto numa pasta própria, com um ramo próprio. A história do projeto é a mesma, porque é uma funcionalidade do git e não um truque do Claude, mas os ficheiros estão separados: o que o Claude altera numa cópia não mexe nas outras.
Cada sessão do Claude trabalha na sua cópia: ninguém mexe no projeto principal até tu decidires. No fim vês o que cada uma fez, ficas com o que está bem e deitas fora o resto.
Só precisas de uma coisa: o projeto tem de usar git e ter pelo menos um commit.
1. Uma sessão, uma cópia
A partir do terminal, abre cada sessão já dentro da sua cópia. A partir da pasta do projeto, corre:
claude --worktree erro-login
A versão curta, -w erro-login, também serve. O Claude Code cria a pasta .claude/worktrees/erro-login num ramo novo, worktree-erro-login, e a sessão trabalha lá dentro.
Dentro de uma sessão já aberta
Se a sessão já estiver aberta, ou se não usares o terminal, escreve antes de mais nada:
Trabalha num worktree novo chamado erro-login.
O Claude cria a cópia sozinho e diz-te onde está a trabalhar. Na app de computador também podes escolher a opção worktree quando abres uma sessão nova.
Repete noutras janelas com outros nomes: «pagina-precos», «testes». Um trabalho por sessão, com um nome claro: daqui a duas horas tens de perceber num instante o que está em cada cópia.
Uma coisa para fazer só uma vez: acrescenta .claude/worktrees/ ao ficheiro .gitignore, para as cópias não aparecerem como ficheiros novos no projeto principal. Podes pedi-lo ao Claude numa linha.
2. O que saber antes de começar
A cópia parte do ramo principal online, normalmente o main, não do que tens no computador e ainda não enviaste. Se tens commits que ainda não enviaste com um push, não estão na cópia: primeiro envia, depois abre as cópias. Se o projeto não estiver online em lado nenhum, a cópia parte de onde tu estás.
Depois há os ficheiros. Uma cópia só tem os ficheiros que o git conhece: não leva os ficheiros excluídos do projeto, como o .env com as chaves, nem as bibliotecas instaladas. Se arrancares sem eles, a app na cópia não abre ou os testes falham por motivos que não têm nada a ver com o trabalho.
Para teres o .env em cada cópia, cria na pasta principal do projeto um ficheiro .worktreeinclude com uma linha lá dentro:
.env
O Claude Code lê-o sempre que cria uma cópia e copia para lá os ficheiros da lista. Segue as mesmas regras do .gitignore e só copia ficheiros que o git ignora, por isso não duplica nada do código. Se tiveres outros ficheiros assim, tipo .env.local, acrescenta uma linha para cada um.
Já as bibliotecas têm de ser instaladas. Na cópia pede:
Instala o que for preciso nesta cópia.
3. Quando acabar: guarda e confere
Primeiro guarda. A junção só vê o trabalho guardado com um commit: o que fica só na pasta da cópia não passa. Na sessão da cópia escreve:
Faz commit de todo o trabalho nesta cópia.
Depois passa para a sessão principal, a que está aberta no projeto a sério, e escreve:
Mostra-me o que o ramo worktree-erro-login muda em relação ao main, ficheiro a ficheiro, e corre os testes.
Se na lista aparecer um ficheiro que não tem nada a ver com o trabalho, tipo a página de preços num trabalho sobre o login, pergunta ao Claude porque mexeu nele.
4. Junta o que está bem
Sempre a partir da sessão principal:
Junta o ramo worktree-erro-login ao main. Se houver conflitos, para e explica-mos antes de decidires.
Se o ramo principal do teu projeto não se chama main, tipo master, muda o nome no prompt. Se não tiveres a certeza, pergunta ao Claude.
Um conflito é quando dois trabalhos alteraram as mesmas linhas de maneira diferente e alguém tem de escolher que versão fica. Prefiro perceber o que o Claude escolhe a descobrir depois.
Um de cada vez: primeiro um, testes, depois o seguinte. Se juntares três ramos seguidos e depois alguma coisa se partir, não sabes qual dos três foi.
5. Deita fora o que não presta
Quando fechas uma sessão que trabalha numa cópia, o Claude Code vê se lá dentro há trabalho: ficheiros alterados, ficheiros novos, commits. Se houver, pergunta-te se queres manter a cópia ou tirá-la. Se a cópia estiver limpa e não tiveres dado nome à sessão, tira-a sozinho.
Se o trabalho não te agradar, tira-a: o projeto principal fica como estava. Mas tirar a cópia apaga a pasta e o ramo dela, com tudo o que lá está. Se já juntaste o trabalho, não perdes nada, porque já está no ramo principal.
Se quiseres, antes de a tirares pede:
Resume-me o que tinhas experimentado nesta cópia
Assim a ideia não se perde. Se decidires manter a cópia, ao sair o Claude Code escreve-te o comando para a retomares mais tarde.
Para veres quantas cópias tens por aí, pergunta ao Claude ou corre git worktree list. Para tirar uma à mão há o git worktree remove, seguido da pasta da cópia.
A regra de ouro
Três trabalhos diferentes, três cópias. Se dois trabalhos mexem nos mesmos ficheiros, fá-los um a seguir ao outro: as cópias evitam os desastres, não os conflitos.
O erro do login e a página de preços funcionam lindamente em paralelo, porque estão em partes diferentes da app. Refazer o menu e mudar as cores da app toda, não: acabam nos mesmos ficheiros e, na altura de juntar, tens tudo em conflito.
Os erros mais comuns
- Dois trabalhos que mexem nos mesmos ficheiros em duas cópias: divide-os por zona da app, ou fá-los um a seguir ao outro.
- Arrancar sem .env e sem bibliotecas: manda preparar a cópia antes de dares o trabalho, ou põe os ficheiros no .worktreeinclude.
- Juntar sem commit: o que fica só na pasta não vai com o ramo, por isso manda fazer o commit na cópia primeiro.
- Juntar tudo de uma vez: junta um ramo, corre os testes e só depois passa ao seguinte.
- Tirar uma cópia sem olhar para ela: tirá-la também apaga o ramo, por isso junta primeiro ou pede um resumo do que lá estava.
Checklist
- O projeto usa git e tem pelo menos um commit
- .claude/worktrees/ está no .gitignore
- Uma sessão por trabalho, cada uma na sua cópia com um nome claro
- Cada cópia tem .env e bibliotecas antes de começar
- Commit na cópia, depois revisão a partir da sessão principal
- Um ramo de cada vez, com testes pelo meio
- As cópias que já não servem foram tiradas
Perguntas frequentes
Tenho mesmo de usar o terminal?
Não. Podes pedir ao Claude para trabalhar num worktree dentro de uma sessão já aberta, com a frase do passo 1. O terminal só é preciso se quiseres abrir a sessão já dentro da cópia com --worktree. Na app de computador escolhes a opção worktree quando abres a sessão.
E se precisar na cópia do trabalho que ainda não enviei?
Tens dois caminhos. O mais simples é fazer push antes de abrires as cópias. O outro é pedir ao Claude para pôr worktree.baseRef em "head" nas definições: assim as cópias partem de onde estás no computador, com os commits que ainda não enviaste.
As cópias veem-se umas às outras?
Os ficheiros não, estão separados. A história do git é partilhada: é por isso que a partir da sessão principal podes ver e juntar os ramos das cópias, como no passo 3. Mas o que uma cópia ainda não pôs num commit não se vê a partir dos outros ramos.