Trocar o Codex pelo Claude Code: o que você precisa reconfigurar?

Fala aí, beleza? Instalar o agente novo leva um minuto, reconstruir a configuração leva a tarde…

Se você já tem um agente rodando de verdade, o npm install -g é a parte boba da história

O que dói é o resto: o arquivo de instruções do projeto que você foi lapidando por semanas, as permissões afinadas do seu jeito, um ou dois servidores MCP conectados, as skills que você escreveu na mão, os subagentes, os hooks

Nada disso viaja junto sozinho

Então bora tratar essa migração pelo que ela é: um trabalho de configuração

Aqui embaixo tem o mapa de onde cada coisa mora nos dois lados, o checklist com 7 passos e o erro comum de cada passo 🙂

Onde mora cada configuração no Codex e no Claude Code

Antes de mexer em qualquer arquivo, se liga nesse mapa: ele serve nos dois sentidos da migração

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Repara numa coisa: quase nada tem o mesmo nome, o mesmo formato E a mesma pasta ao mesmo tempo

Subagente de um lado é TOML, do outro é markdown com frontmatter

Skill é markdown nos dois, mas o diretório muda, e nenhuma das duas documentações confirma que uma ferramenta lê a pasta da outra

Antes de migrar: o que ter instalado e em mãos

Instalando o Claude Code:

npm install -g @anthropic-ai/claude-code

Ou pelo instalador nativo, no macOS, Linux e WSL:

curl -fsSL https://claude.ai/install.sh | bash

No PowerShell:

irm https://claude.ai/install.ps1 | iex

Tome cuidado: a documentação alerta pra NÃO usar sudo npm install -g

E se o caminho for o inverso:

npm install -g @openai/codex

brew install codex

Depois é rodar codex no terminal e fazer login com conta ChatGPT ou chave de API, em macOS, Windows ou Linux

O inventário que salva a sua tarde:

Antes de digitar qualquer comando, abre e olha o que existe hoje:

• ~/.codex/config.toml e o .codex/config.toml do repositório, se tiver
• o AGENTS.md do projeto (e qualquer AGENTS.override.md)
• as skills em .agents/skills e em $HOME/.agents/skills
• os subagentes em ~/.codex/agents/ e .codex/agents/
• os hooks, no hooks.json ou na seção hooks do config.toml
• os prompts customizados em ~/.codex/prompts/

E confere a versão do Claude Code: o comando /import, que é o atalho do passo 2, pede a v2.1.213 ou posterior

Checklist de migração: 7 passos para reconfigurar o agente

1. Instruções de projeto: do AGENTS.md ao CLAUDE.md

Primeiro o porquê, que aqui muda tudo: os dois leem instrução de jeitos diferentes

O Codex percorre da raiz do projeto (normalmente a raiz do Git) até o diretório atual e, em cada pasta, checa AGENTS.override.md, depois AGENTS.md, depois os nomes listados em project_doc_fallback_filenames, no máximo um arquivo por diretório

Os arquivos são concatenados da raiz pra baixo, então o mais próximo do diretório atual prevalece

E tem teto: ele para de somar quando o tamanho combinado atinge project_doc_max_bytes, 32 KiB por padrão (detalhe documentado no guia de AGENTS.md do Codex)

O Claude Code é mais direto: os CLAUDE.md são lidos no início de toda sessão, com a versão de usuário em ~/.claude/CLAUDE.md e a de projeto em CLAUDE.md ou .claude/CLAUDE.md no diretório de trabalho

Pra repositório que já usa AGENTS.md, a documentação de memória do Claude Code recomenda criar um CLAUDE.md que IMPORTE esse arquivo, assim as duas ferramentas leem a mesma instrução sem duplicar

Quando não tem nada específico do Claude no meio, o symlink resolve:

ln -s AGENTS.md CLAUDE.md

Ah, e tem um segundo canal de contexto do lado do Claude Code: a memória automática, em que ele mesmo escreve notas entre sessões

As primeiras 200 linhas do MEMORY.md, ou os primeiros 25KB (o que vier antes), entram no começo de cada conversa

O erro comum deste passo: esperar que o Claude Code leia o AGENTS.md sozinho

Ele não carrega por padrão: o /init só passa a ler AGENTS.md (além de .devin/rules/, .windsurf/rules/ ou .windsurfrules e .clinerules) com a variável de ambiente CLAUDE_CODE_NEW_INIT=1

E no sentido inverso vale o espelho: se o seu repositório usa um nome de arquivo diferente, o Codex ignora até você listar o nome em project_doc_fallback_filenames, no ~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

2. O atalho: rode o /import antes de fazer na mão

Antes de sair copiando arquivo, testa o caminho curto

O Claude Code tem o comando /import, que traz a configuração de um agente de código suportado: ele anexa uma cópia única de arquivos de instrução como o AGENTS.md ao CLAUDE.md correspondente e leva junto servidores MCP, comandos, subagentes e skills

Lembrando: v2.1.213 ou posterior

O erro comum deste passo: rodar o /import e achar que acabou

A lista do que ele leva é essa aí de cima

Permissão e hook não estão nela, então esses dois continuam por sua conta (passos 3 e 7)

3. Permissões e autonomia: duas chaves viram três blocos

No Codex, autonomia é assunto de duas chaves separadas: approval_policy (quando ele para e pergunta, aceitando untrusted, on-request, never e a forma granular) e sandbox_mode (o que ele pode tecnicamente fazer no disco e na rede, com read-only, workspace-write e danger-full-access)

Pasta gravável fora do workspace? Isso vive em sandbox_workspace_write.writable_roots

No Claude Code o desenho é outro: as permissões são regras no formato Tool ou Tool(specifier) dentro do settings.json, organizadas em deny, ask e allow

{
  "permissions": {
    "deny": ["Read(./.env)"],
    "ask": ["Bash(curl *)"],
    "allow": ["Bash(npm run lint)"]
  }
}

E a parte de "quando ele para e pergunta" vira modo de permissão: default, acceptEdits (aceita edições de arquivo automaticamente), bypassPermissions (sem prompts), plan (explora sem editar), dontAsk e auto

O plan é o mais próximo do espírito de um sandbox só de leitura, e o acceptEdits é o que mais lembra a rotina de deixar o agente editar sem interromper

Detalhe importante: mesmo em bypassPermissions, uma regra de deny bloqueia a ferramenta

O erro comum deste passo: assumir que a regra mais específica ganha

Não ganha, e aqui vale separar as duas coisas pra não embolar

Primeiro vem a ordem dos blocos: a avaliação passa pelo deny, depois pelo ask, depois pelo allow

Dentro dessa varredura, quem decide é a PRIMEIRA regra que casar, independente de ser mais específica que as outras

Ou seja: o que manda é a posição na varredura, não o nível de detalhe do specifier

4. MCP: o mesmo servidor, em outro arquivo

No Codex a configuração de MCP fica no próprio config.toml, em blocos [mcp_servers.nome], com um comando dedicado pra gerenciar:

codex mcp list
codex mcp add nome --url https://exemplo.com/mcp

Ele aceita launcher stdio ou URL HTTP streamable, e variáveis com --env KEY=VALUE

No Claude Code o caminho é JSON: .mcp.json, ~/.claude.json ou o comando claude mcp add

O erro comum deste passo: conectar o servidor em escopo de projeto e achar que ele nasceu ativo

Servidores declarados nesse escopo passam por aprovação por servidor, então se a ferramenta "sumiu", desconfia disso antes de mexer na config

5. Skills e comandos: o formato viaja, a pasta não

As skills do Codex ficam em .agents/skills dentro do repositório (ele varre do diretório atual até a raiz) e em $HOME/.agents/skills pras pessoais, cada uma sendo uma pasta com SKILL.md contendo name e description, invocáveis por /skills ou digitando $

As do Claude Code ficam em ~/.claude/skills/, no .claude/skills/ do projeto (que você versiona no git) ou no .claude/skills/ de um diretório passado em --add-dir

E tem um mimo: o Claude Code monitora essas pastas e aplica as mudanças na sessão em curso, sem reiniciar

O SKILL.md segue o padrão aberto Agent Skills, que roda em várias ferramentas de IA, e o Claude Code estende esse padrão com coisas próprias (controle de invocação, execução em subagente e injeção dinâmica de contexto)

Ou seja: o conteúdo em si é bem portável, o endereço é que muda

Já os comandos customizados são o ponto mais bagunçado dos dois lados

No Codex, os prompts vivem em ~/.codex/prompts/, só no nível raiz da pasta, chamados como /prompts:nome, e a documentação marca o recurso como deprecated indicando skills no lugar

No Claude Code, .claude/commands/ e ~/.claude/commands/ são o formato legado: o recomendado hoje é .claude/skills/<nome>/SKILL.md, que aceita a mesma invocação por barra e ainda pode ser acionado pelo próprio Claude

O erro comum deste passo: migrar pro formato legado

Se você vai reescrever mesmo assim, reescreve como skill de uma vez

6. Subagentes: TOML vira markdown

No Codex, subagente é arquivo .toml em ~/.codex/agents/ (pessoal) ou .codex/agents/ (projeto), com os campos obrigatórios name, description e developer_instructions, e ele já traz o default, o worker e o explorer

No Claude Code é markdown com frontmatter YAML em ~/.claude/agents/ ou .claude/agents/, com campos como description, tools, model e permissionMode

---
description: Revisa o diff atual em busca de bug de correção
tools: Read, Grep, Bash
model: sonnet
---

Aqui vai a instrução do subagente, o que era o developer_instructions do lado do Codex

O erro comum deste passo: converter só a casca

O texto do developer_instructions é o miolo do subagente, ele precisa virar o corpo do markdown, não uma linha perdida no frontmatter

7. Hooks: revise evento por evento

O Codex carrega hooks de um hooks.json ou da seção hooks inline no config.toml, com eventos como PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SessionEnd, SubagentStart, SubagentStop, UserPromptSubmit e Stop

O Claude Code configura hooks dentro dos arquivos de settings, nos escopos gerenciado, usuário (~/.claude/), projeto (.claude/) e local (.claude/settings.local.json), e recarrega os settings ao detectar mudança, sem reiniciar a sessão

O erro comum deste passo: olhar os nomes de evento parecidos e concluir que é só copiar e colar

Nenhuma das duas documentações confirma compatibilidade entre os formatos

Trata como reescrita e testa hook por hook, com calma

O que a prática mostra: os hábitos de prompt que não viajam junto

Agora a parte que nenhum /import resolve

No vídeo abaixo eu gravei um curso gratuito de Codex e, montando aquilo, ficou escancarado o quanto a nossa rotina fica colada na ferramenta

O primeiro sinal foi o arquivo de contexto: no Codex, o AGENTS.md cumpre exatamente o papel do arquivo de instruções que eu já uso no Claude Code, e é aquele arquivo que segura a régua do projeto inteiro

O segundo foi as skills

Eu já tinha skills instaladas numa pasta genérica, sobra do uso em outras ferramentas de IA, e o Codex simplesmente passou a usar essas skills sozinho no primeiro projeto, sem eu pedir

Parece massa, mas se liga: excesso de skill atrapalha

A ferramenta aciona skill quando ninguém pediu, e isso aumenta o consumo

É o mesmo problema que eu já tinha comentado nos vídeos de Claude Code e Antigravity, e ele reaparece exatamente igual do outro lado

Outro hábito que não viaja: o SEU jeito de deixar o agente solto

Eu não gosto de rodar vários agentes em paralelo, pelo risco de conflito de edição nos mesmos arquivos, e só libero quando as tarefas são bem diferentes entre si

Esse tipo de decisão não mora em arquivo nenhum, mora na sua cabeça, e é ela que você tem que reescrever em forma de permissão e de modo quando muda de ferramenta

O mesmo vale pra escolha de modelo (eu preferi o de uso geral ao otimizado pra programação, porque nem toda tarefa é código: tem regra de negócio, tem pesquisa pro projeto) e pra forma de pedir

O Codex lê e entende o codebase existente, edita arquivos, roda comando com permissão e aceita screenshot como input, print de um layout de referência ou de um erro na tela

No teste prático eu criei uma landing page do zero em HTML, CSS e JS a partir de um único prompt e abri o resultado no navegador: ficou bonito, mas o logo eu que teria que fornecer

E teve o que me incomodou: o app não mostra os arquivos sendo construídos em tempo real como outras ferramentas, e pra ver o código eu precisei abrir a pasta ou o painel de git

Besteira? É, mas é o tipo de detalhe que muda o seu ritmo de conferência, e conferência é justamente o que segura o barco em tarefa sensível, tipo quando você vai delegar a escrita de testes pro agente

Migrar de vez, rodar os dois em paralelo ou migrar só um projeto?

Não existe uma resposta só, existem três cenários bem diferentes

Troca definitiva:

Aqui você roda o /import, revisa o CLAUDE.md gerado, traduz permissões e hooks na mão e só DEPOIS apaga o legado

A ordem importa: apagar ~/.codex/config.toml antes de validar MCP e permissão é pedir pra ficar sem referência quando algo não funcionar

E se a dúvida ainda é se vale a pena virar a chave, dá uma olhada no que o Claude Code entrega na prática antes de queimar as pontes

Os dois agentes no mesmo repositório:

Esse é o cenário mais comum de quem trabalha em time

A regra de ouro é fonte única de instrução: um CLAUDE.md que importa o AGENTS.md, ou o symlink, pra ninguém editar um arquivo e esquecer o outro

Skill, aí, é duplicação consciente: os diretórios são diferentes e leitura cruzada não é confirmada em documentação nenhuma, então mantém a versão do repo nos dois lugares e trata isso como manutenção, não como acidente

Migração de um projeto só:

Esse é o teste barato, e é o que eu faria primeiro

Mexe SÓ no escopo de projeto (.claude/settings.json, .claude/skills/, .claude/agents/, .mcp.json) e deixa o escopo de usuário intacto

Se der ruim, o estrago fica dentro de um repositório

Conclusão

O custo real de migrar do Codex para o Claude Code (ou de voltar) não está na instalação, que é npm install -g e login

Está em traduzir instrução, permissão, MCP, skill, comando, subagente e hook de um endereço pro outro, sabendo que os formatos mudam e que compatibilidade parecida não é compatibilidade confirmada

O próximo passo concreto é este: pega um repositório pequeno, roda o inventário do checklist, aplica os 7 passos ali, valida permissão e MCP na prática e só então encosta no projeto principal

Faz o teste com calma que a segunda migração leva um terço do tempo da primeira 😀

até o próximo post!