Como pedir ao Claude Code para levar uma feature de um projeto para outro

Fala aí, beleza? Você resolveu um problema chato num projeto, ficou orgulhoso, e duas semanas depois precisa da MESMA coisa em outra base, com outra stack e outras convenções

Aí bate a tentação: abrir os dois lados e mandar o Claude copiar os arquivos de lá pra cá

Spoiler: é aí que a coisa desanda

A boa notícia é que trabalho entre projetos não é gambiarra, é caso de uso previsto: a documentação de multi-diretório do Claude Code cita explicitamente cross-project work, incluindo migrar código entre repositórios, como motivo pra adicionar diretórios na sessão

O segredo não está no comando, está no que você pede

Você descreve COMPORTAMENTO, e usa a origem como referência, não como fonte de cópia

Bora ver na prática?

O que você precisa antes de escrever o prompt

O mínimo é bem simples, mas cada item aqui muda o resultado:

• Os dois projetos acessíveis no disco da mesma máquina
• Clareza absoluta de quem é a ORIGEM (onde a feature já funciona) e quem é o DESTINO (onde ela vai nascer)
• Saber a diferença entre os dois comandos que dão acesso a outro diretório

Essa última parte é a que mais confunde, então vamos separar

Formação Recomendada

Formação Claude Code

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

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

Detalhe importante do /cd: ele exige o Claude Code na versão v2.1.169 ou superior, e pede confirmação de confiança se você nunca trabalhou naquele diretório

E tem um comportamento que pega MUITA gente de surpresa: por padrão, o Claude Code não lê os arquivos CLAUDE.md dos diretórios adicionados via --add-dir

Ou seja, você ganha acesso aos arquivos da origem, mas as regras da origem não vêm junto

No mesmo espírito, diretórios listados em permissions.additionalDirectories nos settings concedem apenas acesso a arquivos, sem carregar nenhuma configuração daquele diretório

Quer o contrário? Existe uma variável de ambiente pra isso:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Com ela ligada, o Claude passa a ler CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md e CLAUDE.local.md do diretório adicional

Decida com calma: às vezes você QUER as convenções da origem no contexto (diretório compartilhado, design system), às vezes elas só vão poluir o destino

Se você trabalha com camadas de memória por fora do Claude Code, vale entender antes quais agentes o Claude-Mem cobre, porque memória e acesso a arquivo são coisas diferentes

Passo a passo para portar uma feature entre projetos

A ordem aqui não é decorativa, ela existe pra que o contexto certo esteja carregado na hora certa

1. Abra a sessão no projeto de DESTINO

O Claude Code carrega todo CLAUDE.md do diretório de trabalho e de cada diretório pai no início da sessão, e carrega o arquivo de cada subdiretório sob demanda, quando lê arquivos ali

Então é no destino que a sessão precisa começar: é lá que as convenções da casa têm que valer

O erro comum deste passo: abrir a sessão na origem porque "é onde está o código", e depois estranhar que a implementação saiu com a cara do projeto errado

2. Dê acesso à origem

Dentro da sessão:

/add-dir ../projeto-antigo

Ou já na abertura, aceitando vários caminhos de uma vez:

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

A flag valida se cada caminho existe como diretório

O erro comum deste passo: caminho digitado errado ou relativo a partir de outro lugar, e a sessão morre antes de começar

3. Peça a exploração da origem, delegando ao Explore

O Explore é um agente embutido, rápido e somente leitura, otimizado para buscar e analisar bases de código

Ele é um subagente, ou seja, o Claude delega a ele pra entender um projeto sem fazer alterações, mantendo os resultados fora do contexto da conversa principal

É como mandar um estagiário ler o repositório inteiro e te trazer só o resumo, em vez de despejar cada arquivo na sua mesa

Use o Explore em ../projeto-antigo e me diga como o fluxo de
recuperação de senha funciona ali: quais rotas existem, o que
dispara o e-mail e onde o token é validado. Não edite nada.

O erro comum deste passo: pedir "leia tudo" sem recorte, e queimar contexto com arquivo que não tem nada a ver com a feature

4. Descreva o COMPORTAMENTO com precisão cirúrgica

A documentação oficial de boas práticas é direta: quanto mais precisas as instruções, menos correções

Referencie arquivos específicos, mencione restrições e aponte padrões de exemplo

O exemplo clássico dela é a troca de "conserte o bug" por "conserte o bug de login em que o usuário vê uma tela em branco após digitar credenciais erradas"

Mesma régua aqui: descreva o comportamento observado, não a tarefa genérica

Quero, neste projeto, o mesmo COMPORTAMENTO de recuperação de senha
que existe em ../projeto-antigo: o usuário pede o reset, recebe um
link de uso único com validade, e cai numa tela de nova senha.

Use ../projeto-antigo APENAS como referência de comportamento.
A implementação segue os padrões daqui: siga src/features/auth/login.ts
como exemplo de estrutura, e não adicione nenhuma dependência nova.

Repare no que esse prompt faz: cita arquivo, impõe restrição e aponta padrão de exemplo do destino

O erro comum deste passo: escrever "traz a feature X de lá" e deixar o resto por conta da IA

5. Entre no modo de planejamento antes de liberar edição

O modo de planejamento é acionado com Shift+Tab ou prefixando um único prompt com /plan

Nele o Claude pesquisa e propõe mudanças sem fazê-las: as edições ficam bloqueadas até você aprovar o plano

Em porte de feature isso vale ouro, porque é exatamente onde você descobre se ele entendeu "comportamento" ou entendeu "cópia"

6. Leia o plano de verdade e só então aprove

O que você procura na leitura: ele está criando arquivos no padrão do destino? Está inventando dependência? Está tratando a origem como referência ou como molde?

Se qualquer resposta for ruim, o conserto é no PROMPT, não no código depois

O erro comum deste passo: aprovar no automático porque o plano é longo e parece competente 😅

7. Isole a execução em um git worktree quando fizer sentido

Rodar cada sessão do Claude Code em seu próprio git worktree faz com que as edições de uma sessão nunca toquem os arquivos de outra

Dá pra pedir pro Claude trabalhar em um worktree e ele cria um com a ferramenta EnterWorktree

Tome cuidado com um detalhe: arquivos ignorados pelo git, tipo .env, não vão junto sozinhos

Pra isso existe o .worktreeinclude, com sintaxe de .gitignore, que copia arquivos que casam com um padrão E que também estão ignorados

O erro comum deste passo: criar o worktree, rodar o projeto e levar um erro de variável de ambiente faltando, sem entender de onde veio

Por que pedir para copiar arquivo por arquivo dá errado

Sintoma: a feature "chega" no destino e quebra na hora

Importa módulo que não existe ali, usa um helper que ficou pra trás, ignora a estrutura de pastas da casa e cria um padrão paralelo que ninguém pediu

Causa: o pedido foi de transporte de arquivos, não de comportamento

E tem uma razão mecânica por trás disso: os agentes Explore e Plan ignoram os arquivos CLAUDE.md e o git status da sessão pai, justamente pra manter a pesquisa rápida e barata

Somado a isso, diretórios adicionados via additionalDirectories dão acesso a arquivos sem carregar configuração alguma

Traduzindo: as regras da origem NÃO viajam junto com os arquivos dela

É o mesmo tipo de armadilha de quando você pega uma skill que funciona em outro projeto e cola na sua pasta esperando que funcione igual

Solução: reescrever o prompt em termos de comportamento, e apontar no destino QUAL arquivo serve de padrão

A origem responde "o que a feature faz"

O destino responde "como a gente escreve as coisas por aqui"

Como prevenir: mantenha o CLAUDE.md do destino enxuto

A documentação alerta que um CLAUDE.md inchado faz o Claude ignorar as instruções reais, e sugere um teste simples: pergunte de cada linha se removê-la causaria erro

Se a resposta for não, aquela linha está lá só ocupando espaço

Três situações em que esse prompt salva tempo

1. Fluxo de autenticação de um repo antigo pro novo

Clássico. O código velho funciona, mas é de outra era, outra biblioteca, outro jeito de organizar

Aqui o certo é /add-dir no repo antigo, sessão aberta no novo, e o pedido descrevendo o fluxo do ponto de vista do usuário

Se você percebeu que na real vai VIVER no projeto antigo por um tempo, aí sim /cd faz mais sentido, porque ele realoca a sessão e carrega o CLAUDE.md do novo diretório

2. Unificar um componente duplicado em duas apps do mesmo monorepo

O mesmo botão, o mesmo modal, duas implementações levemente diferentes, e ninguém sabe qual é a boa

É o cenário perfeito pra abrir a sessão já com os dois caminhos:

claude --add-dir ../apps/web ../apps/admin

E o pedido é comparativo: quais comportamentos cada versão tem, o que existe em uma e falta na outra, e qual vira o componente único

3. Reaproveitar convenções de um diretório compartilhado

Aqui a coisa muda de figura, porque o que você quer trazer NÃO é código, é regra

É o caso de ligar a variável e deixar as memórias daquele diretório entrarem no contexto:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Com isso o CLAUDE.md, o .claude/CLAUDE.md, os .claude/rules/*.md e o CLAUDE.local.md do compartilhado passam a ser lidos

Detalhe pra quem gosta de acompanhar novidade: o /cd é recurso recente, listado como novidade na documentação do Claude Code

Conclusão

A régua pra portar feature entre projetos cabe em três linhas

Comportamento descrito com precisão, do jeito que a documentação de boas práticas pede: arquivo citado, restrição declarada, padrão de exemplo apontado

Origem entra como REFERÊNCIA, via /add-dir, nunca como molde de cópia

E plano lido antes de aprovar, com o modo de planejamento segurando as edições até você dar o ok

O próximo passo prático é o menor possível: escolhe uma feature pequena, abre a sessão no destino, roda o /add-dir apontando pra origem e pede o plano ANTES de qualquer edição

Se o plano vier falando em comportamento e citando os arquivos certos do destino, tu já ganhou o jogo

Se vier falando em copiar arquivo, tu ganhou uma informação valiosa também: o prompt precisa de mais uma volta 😀

até o próximo post!