Claude Code alternatives: como migrar para outra ferramenta sem perder o setup que você construiu

Fala aí, beleza? O medo de trocar de agente de código quase nunca é pela ferramenta em si

É pelo setup

Aquelas instruções do projeto que você foi lapidando por meses, os comandos padrão que você digita sem pensar, as conexões com as ferramentas externas, o fluxo de revisão de diff que finalmente ficou redondo… a sensação é que trocar significa começar do zero

Só que a maior parte disso hoje é arquivo de texto dentro do repositório

E arquivo de texto viaja =)

O que segue é um roteiro de decisão: o que é portátil, o que fica pra trás, e como rodar a alternativa em paralelo antes de cravar qualquer coisa

Antes de migrar: faça o inventário do seu setup atual

Antes de mexer em QUALQUER coisa, você precisa saber o que tem na mão

Migração às cegas é o jeito mais rápido de descobrir que metade do seu contexto sumiu

O que procurar no repositório:

• <code>CLAUDE.md</code> na raiz: a memória persistente do projeto
• <code>.mcp.json</code> na raiz: os servidores MCP de escopo de projeto
• <code>.worktreeinclude</code> na raiz
• a pasta <code>.claude/</code> do projeto, onde vivem os arquivos de escopo do repositório (skills, rules e o <code>commands/</code> no formato legado)

O que procurar no home:

• <code>~/.claude/</code>: tudo que é escopo global, aquilo que te acompanha em todo projeto

Aqui tem uma pegadinha que pega muita gente

No Claude Code, os níveis de <code>CLAUDE.md</code> são aditivos: se existe um arquivo de projeto e um de usuário, o agente enxerga os dois ao mesmo tempo, sem regra dura de precedência entre níveis

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

O que isso significa na prática? Aquele comportamento que você acha que vem do repositório pode estar vindo do seu home, e quem clonar o projeto não vai ter aquilo

O Claude Code carrega o <code>CLAUDE.md</code> do diretório de trabalho e de todos os diretórios acima logo no início da sessão, e os arquivos de subdiretório entram sob demanda quando o agente lê um arquivo daquela pasta

Olha os dois antes de assumir de onde veio a regra

Vale também listar o que você montou por fora do padrão, tipo ferramentas da comunidade em volta do agente, porque essa parte costuma ser a menos portátil de todas

Tome cuidado! Antes do primeiro comando de migração: repositório limpo e commit feito

Migração boa é migração revertível

Mapa de equivalência: onde cada peça do setup vive em cada ferramenta

Isso aqui não é ranking e não é comparação de recurso nem de preço

É tabela de TRADUÇÃO: você já sabe onde a peça mora hoje, e quer saber o endereço dela do outro lado

Repare na linha das skills: o Cursor documenta compatibilidade com os diretórios do Claude e do Codex

Ou seja, em alguns casos a peça nem precisa se mudar de endereço, só ser encontrada 😀

A precedência é o detalhe que mais morde:

Essa é a parte que ninguém lê e depois vira dor de cabeça

• <code>AGENTS.md</code>: agentes leem o arquivo mais próximo na árvore de diretórios, então o mais específico tem precedência e cada subprojeto pode ter o seu
• Codex: os arquivos são concatenados da raiz para baixo, e os mais próximos do diretório atual prevalecem justamente por aparecerem depois no prompt combinado
• Cursor: <code>AGENTS.md</code> na raiz e em subpastas se combinam, com precedência para os mais específicos
• Claude Code: comportamento aditivo, o modelo vê os níveis juntos e o conflito acaba sendo resolvido pela interpretação dele

Mesmo texto, comportamento diferente

Guarda isso, porque o problema (c) lá embaixo é exatamente esse

Como migrar o setup passo a passo (e testar a alternativa em paralelo)

São sete passos, e eles se dividem em duas metades

Do 1 ao 5 você porta o setup pro formato aberto, e do 6 ao 7 você roda a alternativa em paralelo numa worktree, sem encostar no teu trabalho do dia a dia

1. Extraia as instruções do agente para um <code>AGENTS.md</code> na raiz

O AGENTS.md é um formato aberto de Markdown puro, e o site oficial diz que ele é usado por mais de 60 mil projetos open source

A analogia que funciona: pensa nele como um README voltado ao agente, não ao humano

Build, testes, convenções do projeto

Aquilo que você explicaria pra um dev novo no primeiro dia, incluindo o tipo de contexto pra bug que não reproduz na sua máquina

Se o repositório tem mais de um contexto (um front, um back, um pacote interno), usa um arquivo por subprojeto, já que o agente lê o mais próximo na árvore

<pre><code>AGENTS.md apps/web/AGENTS.md apps/api/AGENTS.md</code></pre>

O erro comum deste passo: despejar o <code>CLAUDE.md</code> inteiro na raiz e deixar instrução específica de uma pasta valendo pro repositório todo

2. Decida como os dois arquivos vão conviver

O CLI do Cursor lê <code>AGENTS.md</code> e também <code>CLAUDE.md</code> na raiz do projeto, e aplica os dois como rules, junto com <code>.cursor/rules</code>

Então duplicar conteúdo entre eles não é neutro: é instrução repetida chegando duas vezes

Decida quem é a fonte da verdade antes de sair copiando

O erro comum deste passo: copiar e colar o mesmo bloco nos dois arquivos e esquecer de atualizar um deles depois

3. Converta os comandos personalizados para o formato de skill

Uma skill é simplesmente uma pasta com um arquivo <code>SKILL.md</code>, cujo frontmatter YAML exige os campos <code>name</code> e <code>description</code>, mais scripts e referências opcionais

No Claude Code, o formato recomendado hoje é <code>.claude/skills/&lt;nome&gt;/SKILL.md</code>, e o <code>.claude/commands/</code> é formato legado que continua funcionando

A equivalência é documentada: um <code>.claude/commands/deploy.md</code> cria o comando <code>/deploy</code> e funciona igual a uma skill em <code>.claude/skills/deploy/SKILL.md</code>

<pre><code>.claude/skills/deploy/SKILL.md</code></pre>

<pre><code>— name: deploy description: Descreve quando e como rodar o deploy deste projeto —</code></pre>

O erro comum deste passo: criar a pasta e esquecer <code>name</code> ou <code>description</code> no frontmatter, que são obrigatórios

4. Centralize as regras compartilhadas e linke entre projetos

O diretório <code>.claude/rules/</code> aceita symlinks, o que te deixa manter um conjunto de regras num lugar só e apontar vários projetos pra ele

Os exemplos documentados são estes:

<pre><code>ln -s ~/shared-claude-rules .claude/rules/shared ln -s ~/company-standards/security.md .claude/rules/security.md</code></pre>

Muito massa pra quem tem cinco repositórios com a mesma convenção de commit

O erro comum deste passo: criar o symlink e achar que acabou (spoiler: o alvo fora do diretório de trabalho tem regra própria, e é o primeiro problema da próxima seção)

5. Recrie as conexões MCP no formato do destino

Aqui a notícia é boa

O MCP é um padrão aberto pra conectar aplicações de IA a sistemas externos, com suporte em clientes como Claude, ChatGPT, VS Code e Cursor

Então o servidor é o MESMO: o que muda é onde você declara ele

No Claude Code os servidores de escopo de projeto ficam em <code>.mcp.json</code> na raiz, sob a chave <code>mcpServers</code>, com entradas do tipo http (campo <code>url</code>) ou stdio (campos <code>command</code> e <code>args</code>), e o arquivo é lido no início da sessão

No Cursor a chave <code>mcpServers</code> também vale, em <code>.cursor/mcp.json</code> no projeto ou <code>~/.cursor/mcp.json</code> no home, e o arquivo de projeto tem prioridade quando o mesmo nome de servidor aparece nos dois

O erro comum deste passo: esquecer que o <code>.mcp.json</code> do Claude Code exige uma aprovação única, gerenciável em <code>/mcp</code>, e concluir que o servidor está quebrado quando ele só não foi aprovado ainda

Rodando a alternativa em paralelo (passos 6 e 7):

Setup portado, agora vem a parte que o título prometeu: testar o outro agente sem parar o teu trabalho

6. Crie uma worktree pra rodar a alternativa em paralelo

Esse é o pulo do gato pra testar sem bagunçar o trabalho em andamento

O <code>git worktree add</code> cria uma árvore de trabalho adicional ligada ao mesmo repositório, compartilhando quase tudo exceto os arquivos por worktree, como <code>HEAD</code> e o index

<pre><code>git worktree add ../projeto-teste-agente git worktree list</code></pre>

O <code>git worktree list</code> mostra a worktree principal e as vinculadas, então dá pra conferir na hora se deu certo

Na prática: teu checkout principal continua com o agente de sempre, e a worktree nova é onde a alternativa roda

O erro comum deste passo: tentar reusar um branch que já está checado out em outra worktree (o git recusa, e com razão)

7. Compare os dois agentes na MESMA tarefa e revise o diff antes de decidir

Nada de tarefa de brinquedo

Pega uma tarefa real do backlog, roda nos dois, e lê o diff dos dois lados com o mesmo rigor que você leria um PR de outra pessoa

É o único jeito honesto de comparar, porque demo bonita todo mundo tem

O erro comum deste passo: julgar pela velocidade da primeira resposta em vez de julgar pelo diff que você teria que revisar todo dia

Três problemas que aparecem no meio da migração

(a) As regras compartilhadas por symlink não carregam:

Sintoma: você criou o symlink dentro de <code>.claude/rules/</code> e o conteúdo simplesmente não aparece no comportamento do agente

Causa: symlink cujo alvo está FORA do diretório de trabalho é tratado como import externo, e só carrega depois da aprovação de imports externos no projeto

Solução: aprova os imports externos no projeto, ou, se você quer evitar esse passo, mantém as regras em <code>~/.claude/rules/</code>

Como prevenir: decide isso ANTES de espalhar o mesmo symlink em dez repositórios

(b) O <code>git worktree add</code> recusa criar a worktree:

Sintoma: o comando falha e você não sai do lugar

Causa: por padrão, o <code>git worktree add</code> recusa criar uma nova worktree quando o branch informado já está checado out em outra worktree, e também quando o caminho já foi atribuído

Solução: usa outro branch ou outro caminho

Como prevenir: roda <code>git worktree list</code> antes, pra ver o que já existe (já me ferrei uma vez tentando adivinhar)

(c) Instruções conflitantes depois de duplicar arquivos:

Sintoma: o mesmo texto de instrução produz comportamentos diferentes em cada ferramenta, e você jura que está ficando louco

Causa: a regra de resolução MUDA

No Claude Code os níveis são aditivos e o conflito acaba resolvido pela interpretação do modelo

No <code>AGENTS.md</code> e no Codex, o arquivo mais próximo prevalece, e no Codex isso acontece pela ordem da concatenação da raiz para baixo

Solução: para de escrever a mesma regra em dois níveis e deixa cada arquivo responsável por um escopo

Como prevenir: instrução genérica na raiz, instrução específica no subprojeto, sem sobreposição

Quatro cenários de migração e o que fazer em cada um

Não existe resposta única aqui, existe o SEU caso

1. Troca definitiva de agente:

Foco total em portar duas coisas: instruções e skills

Instruções viram <code>AGENTS.md</code> na raiz (mais os arquivos por subprojeto), e cada comando personalizado vira pasta com <code>SKILL.md</code>

O resto do fluxo você reconstrói em cima disso

2. Uso híbrido, duas ferramentas no mesmo repositório:

Aqui o formato aberto trabalha a seu favor

O CLI do Cursor lê <code>AGENTS.md</code> e <code>CLAUDE.md</code> na raiz, e o Cursor carrega skills também de <code>.claude/skills/</code> e <code>.codex/skills/</code> por compatibilidade

Aposta nos diretórios com compatibilidade cruzada em vez de manter dois setups paralelos na unha

3. Time em que cada pessoa usa um agente diferente:

Instrução de projeto versionada no repositório, sempre

Se está no <code>AGENTS.md</code> commitado, vale pra todo mundo, independente do agente que a pessoa abriu

O padrão de empresa (segurança, convenções) pode ficar centralizado e entrar por symlink em <code>.claude/rules/</code>, lembrando da regra de import externo do problema (a)

4. Avaliação sem compromisso:

Você não precisa decidir nada pra testar

Cria a worktree, roda a alternativa lá por uma tarefa real, e deixa o teu trabalho principal intocado na worktree original

Se não gostou, remove e segue a vida 😀

O setup que vale a pena construir é o que não depende de uma ferramenta

A conclusão é meio chata de tão simples

Quanto mais o seu setup vive como Markdown versionado no repositório e como padrão aberto, menor é o custo de trocar de agente

E não é papo de comunidade só: o <code>AGENTS.md</code> é mantido sob governança da Agentic AI Foundation, dentro da Linux Foundation, e o MCP foi doado pela Anthropic pra essa mesma fundação, um fundo dirigido cofundado com Block e OpenAI e com apoio de Google, Microsoft, AWS, Cloudflare e Bloomberg

Ou seja: os dois pedaços mais importantes do seu setup, instrução e conexão, estão em formato que ninguém é dono sozinho

O que fica pra trás numa migração é sempre o que você amarrou no específico de uma ferramenta

Então o próximo passo é hoje mesmo: abre o repositório, escreve o <code>AGENTS.md</code> como se fosse o README do agente, e roda a alternativa numa worktree por UMA tarefa real antes de qualquer decisão definitiva

Decisão com diff na mão é bem diferente de decisão por hype…

Até o próximo post!