Como trabalhar em dois projetos ao mesmo tempo no Claude Code sem misturar o contexto

Fala aí, beleza? A resposta chega citando um arquivo que não existe nesse repositório, uma convenção que é do outro cliente, uma stack que você nem usa aqui

Quem abre mais de um repositório no mesmo dia já viveu essa cena

Você fecha um projeto, abre outro, emenda a conversa e de repente o Claude Code está resolvendo o problema de hoje com a régua de ontem

Aí bate a desconfiança e você começa a reler CADA resposta, o que mata boa parte do ganho de usar a ferramenta

A boa notícia é que isso quase nunca é o modelo "se confundindo": é arranjo. Sessão é atrelada a um diretório, configuração tem escopo, e worktree existe justamente pra separar frentes dentro do mesmo repo (no terminal, quem cria o worktree é a flag --worktree, e tem passo a passo dela lá embaixo)

Bora entender o mecanismo e depois montar o passo a passo? 🙂

Por que o contexto de um projeto vaza para o outro

O sintoma é sempre parecido: você pede um ajuste no projeto A e vem resposta com nome de arquivo, convenção ou biblioteca do projeto B

Antes de acusar o modelo, vale olhar o que já estava carregado ali dentro. São cinco causas verificáveis, uma de cada vez

1. Um monte de coisa entra no contexto antes de você digitar

CLAUDE.md, auto memory, nomes das ferramentas MCP e descrições das skills carregam no início da sessão

Ou seja: quando você digita a primeira mensagem, o contexto JÁ tem conteúdo

Solução: se uma regra do projeto B está num escopo que vale pra tudo, ela entra na sessão do projeto A sem você pedir nada

2. Escopo de usuário vale para todos os projetos

Esse é o vilão mais comum. Tem coisa que mora na sua máquina, não no projeto

Solução: mover pro escopo de projeto tudo que é específico de um repositório

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

3. Os arquivos somam, não substituem

Esse ponto pega muita gente. Os CLAUDE.md encontrados são CONCATENADOS, indo do escopo mais amplo ao mais específico

Não é o do projeto sobrescrevendo o do usuário, é um em cima do outro

No settings a lógica é parecida: valor escalar de escopo mais específico sobrescreve (o do projeto vence o do usuário), arrays são concatenados e regras de permissão se somam entre escopos

Guarda essa régua, porque skill tem uma regra de desempate própria e diferente dessa, e eu volto nisso no passo 4

Solução: escrever a regra global pensando "isso é verdade em QUALQUER projeto meu?". Se a resposta é não, ela não é global. Vale ler a documentação de memória do Claude Code pra ver a lista de escopos completa

4. Mesma conversa carregando assunto antigo

Às vezes o contexto errado não veio de arquivo nenhum, veio de você mesmo, três horas atrás, na mesma conversa

Solução: /clear começa uma conversa nova com contexto vazio, e a recomendação da doc é usar justamente ao trocar pra um trabalho não relacionado. A conversa anterior não é apagada, continua disponível em /resume

5. Auto memory por projeto, derivada do repositório git

Cada projeto tem seu diretório de auto memory em ~/.claude/projects/<project>/memory/

Só que o caminho deriva do repositório git

E aí vem a consequência: todos os worktrees e subdiretórios do MESMO repo compartilham um único diretório de auto memory

Uma confusão comum aqui: dentro de ~/.claude/projects/ moram duas coisas com chaves DIFERENTES. O arquivo da conversa é gravado pelo diretório exato onde você rodou o comando (o tal <encoded-cwd>), enquanto a pasta de auto memory deriva do repositório git

Por isso dois worktrees do mesmo repo têm arquivos de sessão separados, mas dividem a mesma auto memory

Solução: contar com isso no planejamento. Worktree separa arquivo de trabalho, não separa auto memory

Como prevenir: diagnosticar antes de acusar

Antes de sair mexendo em arquivo, olhe o que a sessão carregou

/context dá um panorama ao vivo do uso de contexto por categoria, com sugestões de otimização, incluindo quais arquivos CLAUDE.md e de auto memory foram carregados

/memory lista os arquivos CLAUDE.md, CLAUDE.local.md e de regras carregados na sessão, permite ligar ou desligar a auto memory e abre a pasta de auto memory

Dois comandos, dez segundos, e você para de adivinhar 😀

O que você precisa antes de começar

Checagem rápida antes do passo a passo:

• Claude Code instalado e funcionando no terminal (se claude sobe numa pasta qualquer, tá valendo)
• Os projetos em diretórios distintos, de preferência repositórios git separados
• git instalado, no caso de quem vai usar worktree
• Saber onde fica o ~/.claude/ da sua máquina e o .claude/ de cada projeto
• Ter na ponta da língua os comandos de diagnóstico (/context e /memory) e os de conversa (/clear, /compact, /resume)

Uma observação sobre onde a conversa fica guardada: sessão do Claude Code é uma conversa salva atrelada a um diretório de projeto, guardada localmente em ~/.claude/projects/<encoded-cwd>/*.jsonl

Repara que a chave aqui é o diretório onde você rodou o comando, codificado no nome da pasta. É outra chave que a da auto memory, que deriva do repositório git, como eu expliquei na causa 5

Se a variável CLAUDE_CONFIG_DIR estiver definida, elas ficam em $CLAUDE_CONFIG_DIR/projects/<encoded-cwd>/*.jsonl

Passo a passo: duas frentes ao mesmo tempo, cada uma com seu contexto

Os passos de 1 a 6 servem pra dois repositórios diferentes, e o passo 7 é o cenário de duas frentes DENTRO do mesmo repo, com worktree

1. Uma instância por projeto, cada uma no seu terminal

Dá pra rodar várias instâncias do Claude Code ao mesmo tempo, cada uma no seu terminal, com tarefas separadas e contexto independente

# terminal 1
cd ~/dev/projeto-a
claude

# terminal 2
cd ~/dev/projeto-b
claude

O erro comum deste passo: abrir a segunda sessão de dentro do diretório do primeiro projeto. A sessão fica atrelada ao diretório onde você rodou o comando, então ela nasce guardada no lugar errado

2. Separe as regras por escopo

Regra do projeto vai em ./CLAUDE.md ou ./.claude/CLAUDE.md

Só o que é universal (seu jeito de trabalhar, que vale em qualquer repo) vai em ~/.claude/CLAUDE.md

Ainda existe a política gerenciada da organização, e a ordem de leitura vai do escopo mais amplo pro mais específico

Depois de mexer, roda /memory na sessão de cada projeto e confere o que está carregado

O erro comum deste passo: jogar convenção específica no ~/.claude/CLAUDE.md. Como os arquivos são concatenados, essa regra viaja com você pra TODO projeto

3. Separe as configurações

Três arquivos, três alcances diferentes:

~/.claude/settings.json        # usuário: vale em todos os projetos
.claude/settings.json          # projeto: versionado com o time
.claude/settings.local.json    # pessoal daquele projeto: não versionado

Valores escalares de escopo mais específico sobrescrevem (o do projeto vence o do usuário), arrays são concatenados

Tome cuidado com um detalhe: regras de permissão se SOMAM entre escopos em vez de sobrescrever

O erro comum deste passo: achar que a permissão definida no projeto substitui a do usuário. Ela não substitui, ela soma

4. Separe MCP e skills por escopo

Servidor MCP tem três escopos. O local registra o servidor só pra aquele projeto e é privado, o project grava um .mcp.json na raiz e compartilha com o time, e o user grava em ~/.claude.json e fica disponível em todos os projetos da máquina

claude mcp add ... --scope project   # .mcp.json na raiz do projeto
claude mcp add ... --scope user      # ~/.claude.json, vale em tudo

Skill segue a mesma ideia de escopo: pessoal em ~/.claude/skills/ (vale em todos os seus projetos) e de projeto em .claude/skills/ (compartilhada pelo git)

Mas atenção numa diferença que confunde: o desempate por NOME das skills não segue a régua do settings. A doc é explícita, enterprise sobrepõe pessoal e pessoal sobrepõe projeto, e uma skill em qualquer desses níveis sobrepõe a embutida de mesmo nome

Ou seja, aqui é o escopo mais amplo que ganha o empate, o contrário do valor escalar do settings

Na prática isso não muda a receita, muda o cuidado: em skill, o que separa projeto de projeto é o NOME. Se você repetir o mesmo nome no escopo pessoal e no do projeto, a versão pessoal é que vale, e você acha que está rodando a do repositório

O erro comum deste passo: registrar tudo no escopo user por preguiça (e ainda repetir nome de skill entre os escopos). Lembra que os nomes das ferramentas MCP e as descrições das skills carregam já no início da sessão, então isso ocupa contexto no projeto que nem usa aquilo

5. Retome cada conversa no lugar certo

O jeito mais simples é entrar na pasta do projeto e continuar:

cd ~/dev/projeto-a
claude --continue

claude --continue retoma a sessão mais recente do diretório atual, sem você precisar rastrear ID nenhum

Quando você tem o ID em mãos, claude --resume aceita um ID específico e pode ser rodado de qualquer diretório: ele procura no projeto atual e nos worktrees dele primeiro, depois em todos os outros projetos da máquina

E se a sessão precisar mudar de pasta, o /cd move a sessão pra outro diretório e realoca ela pro armazenamento daquele diretório, então ela passa a aparecer no seletor de lá

O erro comum deste passo: ver a mensagem No conversation found to continue e achar que perdeu a conversa. Isso é o que aparece quando não existe sessão NAQUELE diretório, ou seja, provavelmente você só está na pasta errada

6. Troque de assunto com /clear em vez de emendar

/clear inicia uma nova conversa com contexto vazio, e a conversa anterior continua disponível em /resume (dá até pra passar um nome pra rotular ela no seletor)

Quando você quer liberar contexto mas MANTER a mesma conversa, o caminho é /compact, que aceita instrução do que preservar:

/compact focus on the auth bug fix

Assim o resumo guarda o que você escolheu em vez do que o passe automático adivinha, e escrever bem essa instrução é a mesma habilidade de escrever um bom prompt: se quiser afiar isso, dá uma olhada nessas técnicas de prompt no Claude Code

A compactação automática roda perto do limite, e o /autocompact define o quão cheio o contexto fica antes desse passe, aceitando uma contagem de tokens (por exemplo /autocompact 500k)

O erro comum deste passo: emendar assunto novo na conversa velha "pra não perder o histórico". O histórico não some com o /clear, ele continua no /resume

7. Duas frentes no mesmo repositório? Worktree, com a flag --worktree

Um git worktree é um diretório de trabalho separado, com arquivos e branch próprios, compartilhando o histórico do repositório

Rodando cada sessão no seu worktree, as edições de uma nunca tocam os arquivos da outra: uma constrói a feature, a outra corrige o bug

No terminal, quem cria esse worktree e já sobe o Claude dentro dele é a flag --worktree (ou -w), com um nome:

# terminal 1
claude --worktree feature-login

# terminal 2
claude -w fix-header

Por padrão o worktree fica em .claude/worktrees/<nome>/ na raiz do repositório, num branch chamado worktree-<nome>

Se você não informar nome, o Claude gera um (a doc cita bright-running-fox como exemplo)

Rodar o comando de novo com outro nome, em outro terminal, inicia uma segunda sessão isolada

Como cada frente vira um branch próprio, ajuda bastante já saber usar o Claude Code com o Git na hora de fechar commit e PR

Subagente também pode rodar em worktree próprio: dá pra pedir isso na conversa ou fixar num subagente customizado com isolation: worktree no frontmatter

E tem uma diferença de comportamento entre os ambientes: no aplicativo de desktop cada sessão nova já ganha um worktree próprio automaticamente, enquanto no terminal o worktree é criado com a flag

O erro comum deste passo: esperar que o worktree isole também a memória. Ele isola o diretório de trabalho, e a auto memory continua derivando do repositório

8. Quando o trabalho precisa MESMO de mais de uma pasta

Aí não é vazamento, é necessidade real. Dá pra dar ao Claude Code acesso a diretórios de trabalho adicionais:

claude --add-dir ../apps ../lib

Também existe o /add-dir dentro da sessão e a chave additionalDirectories no settings. A flag valida se cada caminho existe como diretório

Duas ressalvas honestas aqui: quando o Claude roda cd na sessão principal, o novo diretório vale pros comandos Bash seguintes desde que continue dentro do diretório do projeto ou de um diretório adicional

E sessões de subagente NUNCA carregam mudanças de diretório de trabalho

O erro comum deste passo: usar --add-dir como atalho pra tocar dois projetos numa sessão só. Isso é o oposto do que a gente montou até aqui

Três cenários comuns e o arranjo certo para cada um

Cenário 1: dois repositórios diferentes no mesmo dia

Esse é o caso clássico do freela e de quem toca produto e cliente na mesma semana

Arranjo: uma instância por diretório, cada uma no seu terminal, com as regras no CLAUDE.md de cada projeto

O ~/.claude/CLAUDE.md fica só com o que é verdade nos dois

Cenário 2: monorepo

Aqui o truque é onde você INICIA a sessão

Iniciando o Claude a partir de packages/api/, ele carrega o packages/api/CLAUDE.md e o CLAUDE.md da raiz, sem nenhuma instrução de packages/web/ no contexto

E tem um detalhe que ajuda muito: CLAUDE.md e CLAUDE.local.md de subdiretórios não carregam no início, eles são descobertos abaixo do diretório atual e incluídos quando o Claude lê arquivos daqueles subdiretórios

Skills de .claude/skills/ aninhados seguem a mesma lógica: ficam disponíveis quando o Claude lê ou edita um arquivo daquele subdiretório

Ou seja, o monorepo já é sob demanda por construção, desde que você não suba tudo pra raiz

Cenário 3: feature e correção de bug no MESMO repositório

Arranjo: um worktree por sessão, criado com claude --worktree <nome>, cada um no seu terminal

Uma sessão constrói a feature, a outra corrige o bug, e nenhuma edita o arquivo da outra

A ressalva honesta, de novo: como o caminho da auto memory deriva do repositório git, todos os worktrees do mesmo repo compartilham um único diretório de auto memory

O que percebi rodando um projeto de verdade em sessão isolada

No vídeo abaixo eu rodo o mesmo prompt em duas ferramentas ao mesmo tempo, cada uma no seu projeto zerado, e o briefing era gordo

O pedido era um quadro estilo Kanban com quatro colunas (a fazer, em progresso, revisão e concluído), e nos dados de exemplo eu pedi três quadros, cinco cards por quadro e quatro membros do time

Isso é um monte de decisão específica de UM projeto

E é exatamente esse tipo de coisa que você não quer vazando pro repositório do lado: nomes de coluna, dados de exemplo, convenção de nomenclatura em português

Quando testei, o Claude Code passou cerca de 5 minutos ainda na fase de planejamento, parando pra perguntar coisas que definiam pontos do projeto e pesquisando bibliotecas e boas práticas, enquanto a outra ferramenta já avançava no código

Gostei desse comportamento, porque as perguntas afetavam decisões reais do projeto

Mas repara no que isso significa pro nosso assunto: todo esse briefing, as perguntas, as respostas e as decisões ficaram DENTRO do contexto daquele diretório

Um projeto por sessão, sem herança de outro repositório 🙂

No vídeo você vê a comparação rodando lado a lado, do planejamento até os dois projetos abertos no navegador, testando funcionalidade por funcionalidade

Próximo passo

Se tem uma coisa pra levar daqui é essa: contexto separado não é disciplina, é arranjo de diretório e de escopo

A sessão fica atrelada ao diretório, a configuração tem escopo, os arquivos somam em vez de substituir e a flag --worktree separa as frentes dentro do mesmo repo

O próximo passo é pequeno e dá pra fazer agora: abre cada projeto no seu próprio terminal, roda /context e /memory na sessão de cada um e olha a lista com calma

Toda regra que aparecer ali vinda do escopo de usuário sem precisar estar, move pro CLAUDE.md do projeto

Só isso já derruba a maior parte das respostas com cara de projeto errado

Qualquer dúvida, me chama, e até o próximo post! 😀