Migrando do Claude Code: Trocando a ferramenta com o mesmo mapa, você ainda encontra o caminho de casa

📚 Navegação da Série: O artigo anterior (31 Dicas Avançadas e Aceleração) explicou como fazer todo o fluxo de trabalho rodar mais rápido, gastando menos e com menos retrabalho. Este artigo muda de perspectiva — escrito especialmente para você que está migrando do Claude Code: do modelo mental que você usou por mais de meio ano, o que pode ser copiado diretamente, o que precisa ser renomeado e o que há de novo e exclusivo no Codex. O próximo artigo (33 Pontos de Atenção no Windows) abordará os problemas específicos do Windows.

Primeiro, vamos reconstituir uma conversa real. No mês passado, um amigo que sempre usou o Claude Code instalou o Codex e começou com uma série de perguntas:

Ele: "Onde fica o CLAUDE.md do Codex? Por que ele não está lendo a versão que tenho na raiz do meu projeto?" Eu: "O Codex não reconhece o nome CLAUDE.md, ele lê AGENTS.md. Você pode migrar o conteúdo quase sem alterações." Ele: "E o que faço com as regras de permissão allow / deny no meu settings.json?" Eu: "Você também precisará trocá-las — o Codex usa ~/.codex/config.toml, formato TOML. O modelo de permissões adota a abordagem de 'sandbox + aprovação', não allowedTools." Ele: "E quanto a rodar scripts com claude -p? Comandos como /compact e /clear ainda existem?" Eu: "O claude -p corresponde ao codex exec, e a maioria dos comandos com barra inclinada estão presentes e têm quase o mesmo nome. Resumindo, você pode usar 90% da sua memória muscular diretamente."

Ele suspirou aliviado ao ouvir isso — afinal, não se trata de aprender uma ferramenta nova do zero, mas sim de usar o mesmo mapa com um conjunto diferente de nomes de lugares. Este artigo alinhará tudo o que ele perguntou, bem como o que ele não teve tempo de perguntar: quais conceitos correspondem diretamente, quais diferenças podem causar problemas se forem copiadas sem cuidado e, por fim, guiará você na conversão manual de um CLAUDE.md real para AGENTS.md.

Ao terminar este artigo, você obterá:

Uma garantia: 90% do seu modelo mental do Claude Code pode ser transferido diretamente para o Codex, tornando o custo de migração menor do que você imagina
Uma tabela comparativa completa de "Conceito do Claude Code → Correspondente do Codex", explicando as principais diferenças item por item
Três áreas onde os conceitos son "parecidos no nome, mas diferentes no comportamento" (instruções do projeto, arquivos de configuração e modelo de permissões) e os problemas comuns ao tentar copiá-los diretamente
O que existe no Claude Code mas não está presente ou funciona de forma diferente no Codex, para evitar suposições erradas
Um passo a passo prático para migrar seu CLAUDE.md para AGENTS.md

⚠️ Quaisquer comandos específicos, chaves de configuração e comportamentos padrão mencionados a seguir são baseados na documentação oficial do Codex. Nomes de modelos e números de versão que mudam frequentemente devem ser verificados no painel /model local e na saída do comando codex --help — evite apenas memorizá-los. Como ambas as ferramentas estão evoluindo rapidamente, esta tabela explica a "mapeamento de conceitos", não garantias de texto exato.

01 Garantia inicial: 90% do seu modelo mental pode ser transferido diretamente

Vamos esclarecer logo a maior fonte de ansiedade: ao migrar do Claude Code para o Codex, você não está aprendendo uma ferramenta nova do zero, mas sim reutilizando a mesma lógica subjacente sob uma nova roupagem.

Por que tanta certeza? Porque no nível mais fundamental, ambos são o mesmo tipo de coisa — CLI de programação assistida por AI que rodam no terminal, executam um "loop de agente" (agentic loop) e podem ler e gravar diretamente no seu repositório de código real. Você já viu esses três pontos repetidamente nos artigos sobre o Claude Code, e eles se aplicam exatamente da mesma forma no Codex.

Analogia: Mudar de um celular Android para outro de marca diferente. Não é uma mudança drástica como migrar do Android para o iOS — sua memória muscular para fazer chamadas, enviar mensagens, instalar aplicativos e deslizar para voltar continua intacta. Apenas os ícones mudaram de lugar, o menu de configurações tem uma estrutura diferente e alguns aplicativos têm outros nomes. Você não precisa aprender "como usar um celular" novamente, precisa apenas de dez minutos para descobrir "onde este celular guarda as coisas". Essa é exatamente a relação entre o Codex e o Claude Code.

O que exatamente pode ser transferido diretamente? Quando migrei do Claude Code, nunca tive problemas com os seguintes pontos:

O loop de agente "Pensar → Fazer → Verificar": você descreve o requisito, ele traça um plano, faz as alterações e depois verifica o resultado — esse fluxo é exatamente o mesmo.
O hábito de "deixar ler e entender a proposta primeiro": ao assumir um projeto desconhecido, leia-o por completo, proponha uma solução e só comece a agir após a confirmação. Ambas as ferramentas funcionam melhor assim.
A ideia de "escrever as regras do projeto em um arquivo e lê-las automaticamente a cada início de trabalho": apenas os nomes de arquivo e os detalhes de carregamento diferem (detalhes na próxima seção).
Comandos com barra como "console de sessão": alternar modelos, limpar o contexto, verificar o status — todos acessíveis através de uma /.

A primeira vez que usei o Codex para valer foi no ano passado, quando migrei um projeto FastAPI do Claude Code. Usei meus velhos hábitos e digitei meio no improviso: /status para ver a configuração, /model para alternar modelos, pedir uma proposta antes de alterar — e cerca de 80% das operações funcionaram direto. Os outros 20% eram diferenças nos nomes dos arquivos e na configuração de permissões, o que resolvi em dez minutos consultando a documentação oficial. A sensação de familiaridade de "ei, eu sei fazer isso" foi muito maior do que eu esperava.

💡 Resumo em uma frase: O Codex e o Claude Code são o mesmo tipo de ferramenta (CLI de terminal + loop de agente + leitura e escrita em repositórios reais). Você pode transferir 90% do seu modelo mental, precisando apenas reconhecer "onde as coisas ficam e como são chamadas".

02 Uma grande tabela comparativa: nomes antigos → nomes novos

Esta seção é a estrutura principal do artigo — ela mapeia cada conceito central que você aprendeu nos capítulos do Claude Code para seus nomes e caminhos correspondentes no Codex. Primeiro, observe a tabela para ter uma visão geral e, nas seções seguintes, detalharemos as linhas com as maiores diferenças.

Claude Code	Codex	Relação	Diferença em uma frase
Instruções do projeto `CLAUDE.md`	`AGENTS.md`	Renomeado	Conceito idêntico, mas as regras de cadeia de descoberta / sobreposição são diferentes (ver 03)
Arquivo de configuração `~/.claude/settings.json` (JSON)	`~/.codex/config.toml` (TOML)	Formato alterado	JSON → TOML, com chaves e estruturas totalmente diferentes (ver 04)
Modo de permissões + regras `allow`/`ask`/`deny`	Sandbox `sandbox` + Aprovação `approval`	Abordagem alterada	Mudança de "lista branca por ferramenta" para "delimitar território + perguntar apenas se sair dele" (ver 05)
Modo headless `claude -p`	Comando não interativo `codex exec`	Renomeado	Ambos significam "executar sem entrar na interface interativa e sair al terminar"
Camadas do `CLAUDE.md` (Usuário / Projeto / Subdiretório)	Camadas do `AGENTS.md` (Global / Projeto nível por nível)	Correspondente	Abordagem idêntica, mas o Codex adiciona o `AGENTS.override.md`
Ferramentas externas MCP	MCP	Quase universal	O mesmo protocolo, mas as sintaxes de configuração diferem
Subagentes Subagents	Subagentes Subagents	Correspondente	Presentes em ambos, mas os caminhos de configuração mudaram
Habilidades Skills	Habilidades Skills	Correspondente	Presentes em ambos, mas a organização de diretórios locais varia levemente
Comandos com barra (`/model`, `/compact`...)	Comandos com barra (`/model`, `/compact`...)	A maioria igual	Os nomes dos comandos são quase idênticos, com poucas exceções (ver 06)
Memória automática memory (ligada por padrão)	Memories / Chronicle	Correspondente, mas comportamento diferente	Memórias do Codex ficam desativadas por padrão, possuem restrições regionais e são geradas de forma assíncrona
Modelos Opus / Sonnet / Haiku	Série GPT-5.x	Modelos alterados	Carro-chefe `gpt-5.5`, leve `gpt-5.4-mini`, etc.

Você não precisa memorizar esta tabela, apenas lembre-se da regra geral:

Qualquer elemento no nível de "conceito" (instruções do projeto, permissões, memórias, subagentes, habilidades, MCP) está presente em ambos; a migração consiste apenas em "renomear + ajustar a sintaxe". O que realmente pode te pegar de surpresa são os itens "parecidos no nome, mas diferentes no comportamento" — instruções do projeto, arquivos de configuração e modelo de permissões. As próximas três seções abordam especificamente esses três pontos.

Quanto aos modelos correspondentes, resumindo: se no Claude Code você escolhia "Opus para tarefas pesadas, Sonnet para o dia a dia e Haiku para tarefas rápidas", no Codex a lógica muda para "gpt-5.5 para tarefas complexas e gpt-5.4-mini para tarefas simples". A lógica de seleção (combinar o poder de processamento com a dificuldade da tarefa) é idêntica. Consulte (30 Escolhendo os Modelos) para mais detalhes. Cuidado para não confundir o gpt-5.4 como modelo principal — o topo de linha é o gpt-5.5, enquanto o gpt-5.4-mini é sua versão leve.

💡 Resumo em uma frase: Os conceitos correspondem quase um para um e a migração é basicamente "trocar nomes e ajustar sintaxe". Os problemas reais se concentram nos três pontos "parecidos no nome, mas diferentes no comportamento": instruções do projeto, arquivos de configuração e modelo de permissões. Detalharemos cada um a seguir.

03 Instruções do projeto: `CLAUDE.md` → `AGENTS.md`

Este é o primeiro problema que você encontrará ao migrar, e foi a primeira pergunta do meu amigo: o Codex não lê o CLAUDE.md. Ele ignorará completamente a versão na raiz do seu projeto porque o arquivo que ele reconhece chama-se AGENTS.md.

A boa notícia é que você pode migrar o conteúdo quase exatamente como está. Visão geral do projeto, stack tecnológica, comandos frequentes, convenções de código e regras de não alteração — esses cinco tipos de informações servem ao mesmo propósito e usam a mesma sintaxe em ambos. O que você aprendeu no capítulo do Claude Code [18] sobre "escrever fatos para serem lembrados em todas as rodadas e remover tudo o que o código já explica por si só" continua valendo perfeitamente para o AGENTS.md.

Analogia: Reescrever um documento de transição de cargo ao mudar de empresa. Ao mudar de emprego, a maioria das informações principais da "Descrição do Projeto" do seu antigo trabalho — como stack de tecnologia, como executar testes e o que evitar — pode ser copiada diretamente para o modelo da nova empresa. Contudo, a estrutura de pastas e as regras de nomenclatura de documentação da nova empresa são diferentes, e você deve segui-las. O AGENTS.md se enquadra nessa situação de "o conteúdo é reutilizável, mas as regras de organização devem ser adaptadas".

Especificamente sobre as diferenças nas "regras de organização", listamos os pontos que podem dar problemas se forem copiados diretamente:

Dimensão	Claude Code (`CLAUDE.md`)	Codex (`AGENTS.md`)
Onde colocar nível de usuário	`~/.claude/CLAUDE.md`	`~/.codex/AGENTS.md`
Onde colocar nível de projeto	`./CLAUDE.md` ou `./.claude/CLAUDE.md`	`./AGENTS.md` (raiz do projeto)
Nível de subdiretório	Qualquer subdiretório `CLAUDE.md`, carregado quando encontrado	Do diretório Git raiz até o diretório atual passo a passo, selecionando um por diretório
Sobreposição temporária	Variante local `CLAUDE.local.md` (não adicionado ao git)	`AGENTS.override.md` (ignora o `AGENTS.md` no mesmo nível)
Limite de tamanho	Por número de linhas (recomendado menos de 200 linhas)	Por bytes (limite padrão acumulado de 32 KiB, `project_doc_max_bytes`)

Três diferenças mais importantes a serem lembradas:

Primeiro, o mecanismo de sobreposição temporária é diferente. O Claude Code usa o CLAUDE.local.md para configurações locais de preferência individual que não devem ir para o git. O Codex adota o AGENTS.override.md — onde ele estiver presente, o arquivo AGENTS.md correspondente no mesmo nível será completamente ignorado. Eles não funcionam da mesma forma: o primeiro adiciona dados pessoais extras, enquanto o segundo indica "use apenas este arquivo neste nível e desconsidere a outra versão". Veja mais em [11].

Segundo, o limite de tamanho muda de "contagem de linhas" para "tamanho em bytes". O Claude Code aconselha a manter o CLAUDE.md abaixo de 200 linhas; o Codex possui uma métrica rígida — quando o tamanho combinado excede o limite padrão de 32 KiB, ele inicia o truncamento ou até bloqueia o arquivo por completo. Tive problemas com isso ao migrar a documentação daquele projeto FastAPI: meu CLAUDE.md original era extenso e não prestei atenção no início. Mais tarde, notei que as diretrizes do subdiretório não estavam sendo aplicadas e, ao verificar, notei que a fusão dos arquivos havia estourado o limite. Portanto, faça uma limpeza antes de migrar, removendo qualquer detalhe que o Codex possa descobrir diretamente lendo o código.

Terceiro, a cadeia de descoberta funciona por "concatenação" e não por "sobreposição". O arquivo global e o do projeto funcionam simultaneamente. Em caso de conflito, a versão mais próxima do diretório atual terá prioridade. Essa abordagem de carregamento hierárquico é semelhante à do Claude Code, mas a ordem de mesclagem do Codex (da raiz até as ramificações mais profundas, onde os níveis mais próximos são concatenados por último e ganham prioridade maior) é detalhada mais claramente na documentação oficial, conforme explicado em [11].

💡 Resumo em uma frase: O conteúdo do CLAUDE.md pode ser migrado quase intacto para o AGENTS.md. No entanto, atente-se às três diferenças: o nome do arquivo, o mecanismo de sobreposição local (CLAUDE.local.md → AGENTS.override.md) e os limites de tamanho (linhas → bytes). Limpe o arquivo antes de migrar.

04 Arquivo de configuração: `settings.json` (JSON) → `config.toml` (TOML)

Segundo problema: a configuração contida em seu ~/.claude/settings.json não pode ser colada diretamente no Codex. Até mesmo o formato do arquivo é diferente entre as ferramentas.

Claude Code: ~/.claude/settings.json, no formato JSON, concentrando permissões, variáveis de ambiente, hooks e o modelo padrão em um único arquivo.
Codex: ~/.codex/config.toml, no formato TOML, onde ficam os controles para o modelo, sandbox, aprovações, MCP, etc.

Analogia: Dois diagramas elétricos para o mesmo projeto, um usando o sistema métrico e outro o sistema imperial. O que o desenho quer comunicar (qual fiação conecta a qual interruptor) é o mesmo, mas a unidade de medida e os símbolos gráficos são diferentes. Você não pode entregar um projeto em polegadas para uma equipe de instalação que trabalha com metros — você precisa converter e redesenhar item por item. A transição de JSON para TOML é exatamente esse processo de "recriar a sintaxe mantendo o mesmo objetivo".

Veja abaixo as diferenças mais evidentes nos formatos:

O que você quer configurar	Claude Code (`settings.json`, JSON)	Codex (`config.toml`, TOML)
Modelo padrão	`"model": "claude-..."`	`model = "gpt-5.5"`
Permissões / Segurança	`"permissions": { "deny": [...] }`	`sandbox_mode = "..."` + `approval_policy = "..."`
Estrutura aninhada	Chaves `{ }` + vírgulas	Cabeçalho de seção `[section]` + sinal de igual
Aspas em strings	Aspas duplas obrigatórias	Aspas duplas

Vejamos um exemplo simples de comparação. Definindo o modelo padrão no Claude Code (JSON):

json

{
  "model": "claude-sonnet-4"
}

Definindo o modelo padrão e a intensidade de raciocínio no Codex (TOML):

toml

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"

Atenção a algumas regras de escrita no TOML que costumam induzir a erros na transição do JSON: as associações usam = em vez de :; não se utilizam chaves para encapsular objetos inteiros, usando cabeçalhos de seção [section] para agrupamento; e não se adicionam vírgulas no final das linhas. Logo quando migrei, por hábito de JSON, inseri vírgulas no final de cada linha do meu config.toml, e o Codex reportou erros de análise imediatamente. Este é um erro comum de digitação ao migrar de JSON para TOML, compartilhado aqui para que você possa evitá-lo.

As descrições detalhadas das diversas opções disponíveis no config.toml (modelo, sandbox, aprovações, intensidade de raciocínio, níveis de serviço, MCP...) podem ser encontradas em (18 Configuração Detalhada do config.toml). Neste estágio, você só precisa entender uma coisa: não tente "traduzir" o seu settings.json inteiro, em vez disso, consulte a tabela de chaves em [18] e configure novamente apenas as linhas que você realmente utiliza. A maioria dos usuários altera apenas cerca de três a cinco opções relacionadas a modelo, sandbox e aprovações.

💡 Resumo em uma frase: A conversão de settings.json (JSON) para config.toml (TOML) requer reescrever no novo formato, não apenas copiar e colar. O TOML utiliza =, [section] e não permite vírgulas no final das linhas — evite carregar vírgulas do JSON. Reconfigure apenas os itens necessários usando o guia em [18].

05 Modelo de permissões: Modo de permissão → Sandbox + Aprovação

Esta é a parte com a maior diferença conceitual durante a migração, e vale a pena gastar algum tempo para reestruturar seu entendimento aqui. Se você tentar aplicar diretamente a lógica de "lista branca" do Claude Code, acabará confuso.

O modelo de segurança do Claude Code gira em torno de dois aspectos principais:

Modo de permissão (permission mode): possui seis níveis, indo de default (pergunta a cada passo) a bypassPermissions (totalmente livre), alternados usando Shift+Tab.
Lista branca de regras: definição de allow / ask / deny no seu settings.json para controlar permissões específicas por ferramenta ou por comando (por exemplo, bloqueando com deny o comando rm -rf).

O Codex funciona de forma diferente. Ele divide o controle de "qual o limite das ações" e "quando o usuário deve ser consultado" in dois controles independentes:

Sandbox: gerencia "qual o limite das ações" — com três níveis: read-only / workspace-write / danger-full-access.
Aprovação (approval): gerencia "quando perguntar a você" — com três níveis: untrusted / on-request / never.

Analogia: Substituir um sistema de "reembolso item a item" por um modelo de "limite de orçamento + aprovação de excessos". O Claude Code assemelha-se ao reembolso tradicional: cada transação (cada ferramenta, cada comando) é previamente categorizada como permitida, proibida ou sujeita a aprovação. O Codex funciona como um orçamento moderno: ele estabelece uma área de ação ("sandbox"). Dentro dessa área, você pode executar o que desejar sem interrupções (sem solicitar aprovação) e apenas precisará de autorização explícita se tentar agir fora dos limites configurados. O primeiro controla por "item", o segundo por "área". Trata-se de uma mudança estrutural de raciocínio.

Organizei as relações de mapeamento em uma tabela de migração:

Efeito desejado no Claude Code	Configuração no Claude Code	Configuração no Codex
Permitir apenas leitura, sem alterar arquivos	Modo `default` / Apenas leitura	Sandbox `read-only`
Permitir alterações no projeto sem interrupções, mas solicitar aprovação fora dele	Equivalente ao `acceptEdits`	Sandbox `workspace-write` + Aprovação `on-request` (combinação ideal para uso diário)
Totalmente automático, sem nenhuma pergunta	`bypassPermissions`	Sandbox `danger-full-access` + Aprovação `never` (a opção `--yolo` é ainda mais radical: ignora o sandbox por completo)
Bloquear um comando perigoso específico	Regras em `permissions.deny`	Regras experimentalmente configuradas com `prefix_rule()` para correspondência de prefixo do comando, definindo `decision = "forbidden"` para bloquear
Alternar nível de rigor	Pressionar `Shift+Tab`	Digitar `/permissions` na sessão ou usar `-s` / `-a` na inicialização

Alguns pontos importantes que exigem atenção especial ao migrar:

Primeiro, "não perguntar" não significa "dar acesso livre". No Claude Code, os modos tornam-se progressivamente mais flexíveis. No Codex, esses dois controles funcionam de forma independente — é perfeitamente viável definir "apenas leitura + sem perguntas" (read-only + never), o que significa "pode ler à vontade, mas sem me interromper durante o processo". O nível never serve apenas para silenciar os pedidos de aprovação, não para liberar privilégios extras.

Segundo, a configuração padrão depende da "existência de um repositório Git". O Codex adota uma abordagem inteligente na inicialização: em diretórios gerenciados por Git, ele atribui workspace-write + on-request (modo Auto), enquanto em locais sem Git o padrão é definido como read-only. Esse recurso ausente no Claude Code serve como uma excelente proteção de segurança — evite ativar acesso total em diretórios temporários sem Git (comentei em [15] sobre o susto que levei com isso).

Terceiro, no modo workspace-write, a rede externa vem desativada por padrão e o diretório .git fica protegido em modo apenas leitura. Essas duas configurações padrão costumam ser contra-intuitivas para quem está migrando do Claude Code. Para habilitar acesso à internet, você deve ativar explicitamente network_access.

As regras completas de permissão (combinação dos três níveis, escrita de regras e limites do modo --yolo) são explicadas em (15 Permissões, Sandbox e Aprovação). Ao migrar, o foco principal é consolidar o entendimento desse novo conceito de "dois controles separados", sem tentar encaixar a lógica antiga de lista de permissões.

💡 Resumo em uma frase: O "modo de permissão + lista branca allow/deny" do Claude Code converte-se no Codex em "dois controles separados: sandbox (limite de ações) e aprovação (quando perguntar)". Atente-se a: "não perguntar ≠ acesso livre", configurações dependentes do Git e rede desabilitada por padrão no workspace-write — copiar regras sem entender esses três pontos gerará problemas.

06 Hábitos de interação: Diferenças e semelhanças nos comandos com barra e gerenciamento de sessões

A boa notícia está de volta: uma vez iniciada a sessão, a maior parte da sua memória muscular funcionará diretamente. A correspondência entre os comandos com barra é extremamente alta e os termos mais comuns são idênticos.

O que você deseja fazer	Claude Code	Codex	É idêntico?
Alternar modelo	`/model`	`/model`	✅
Compactar o contexto	`/compact`	`/compact`	✅
Limpar tela e iniciar nova conversa	`/clear`	`/clear`	✅
Verificar status / configuração	`/status` (ou `/config`)	`/status`	Quase idêntico
Gerar instruções do projeto	`/init`	`/init`	✅ (um gera o `CLAUDE.md`, o outro gera o `AGENTS.md`)
Visualizar alterações (diff)	`/diff`	`/diff`	✅
Pedir revisão das alterações	`/review`	`/review`	✅
Ajustar nível de permissões	`Shift+Tab`	`/permissions`	❌ Entrada diferente

As diferenças residem principalmente em dois aspectos:

Primeiro, o acesso para alterar permissões mudou. O Claude Code utiliza o atalho Shift+Tab para alternar entre os modos; o Codex utiliza o comando com barra /permissions para abrir o menu de seleção. O resultado prático é o mesmo, mas o método mudou de tecla de atalho para seleção em menu.

Segundo, a distinção entre /clear e /new é mais detalhada no Codex. No Codex, /clear serve para limpar a tela e iniciar um novo chat, enquanto /new inicia um chat paralelo mantendo a tela atual ativa. No Claude Code, a limpeza costuma ser feita basicamente via /clear (permitindo recuperar chats anteriores com /resume). É uma pequena variação que vale a pena conhecer.

Minha experiência prática na primeira semana após a migração: quase não precisei consultar a sintaxe dos comandos — comandos como /model para alternar modelos, /status para monitorar status e /compact para reduzir contexto vieram intuitivamente. A única vez em que parei foi ao tentar configurar permissões: apertei Shift+Tab por reflexo e nada aconteceu, antes de me lembrar que no Codex usa-se /permissions. O guia rápido completo de comandos com barra está disponível em (12 Comandos com Barra e Atalhos), mas você pode ir usando seus hábitos antigos e verificar apenas quando houver dúvidas.

💡 Resumo em uma frase: A semelhança entre os comandos com barra é altíssima (/model, /compact, /clear, /diff, /review possuem o mesmo nome). Pode utilizar os comandos habituais e tirar dúvidas apenas quando necessário. A maior diferença é a alteração de permissões — Shift+Tab no Claude Code e /permissions no Codex.

07 Evite suposições automáticas: Diferenças e ausências no Codex

O maior perigo na migração não é "não saber usar", mas sim "assumir que funciona exatamente igual ao Claude Code, quando na verdade há diferenças". Esta seção aborda os tópicos onde equívocos são comuns.

Primeiro, o status padrão do sistema de memória é o oposto. No Claude Code, a gravação de memória automática vem ativada por padrão, dividida por repositório Git e recuperada no início da sessão. As Memories do Codex vêm desativadas por padrão, possuem restrições regionais, rodam de forma assíncrona em segundo plano e usam regras diferentes de armazenamento e gerenciamento. Quando meu amigo migrou, he assumiu que "se eu disser uma vez, ele lembrará" — e logo em seguida usou o gerenciador de pacotes incorreto, simplesmente por carregar a expectativa do recurso automático de memória do Claude Code. Quaisquer diretrizes obrigatórias e permanentes devem ser inseridas no arquivo de instruções do projeto (AGENTS.md) em ambas as ferramentas, sem depender da memória do assistente, conforme explicado em [19].

Segundo, o Codex traz recursos inexistentes no Claude Code. Não encare as funcionalidades apenas como "nomes trocados" — existem inovações importantes:

AGENTS.override.md: arquivo de sobreposição local para aquele nível específico de pastas, sem correspondente no Claude Code ([11]).
Chronicle: capacidade de integrar capturas de tela para construção de memórias. Atualmente listado como "versão preliminar de pesquisa" (research preview), requer ativação manual, possui limitações regionais e é exclusivo do Codex ([19]).
Seleção automática baseada em Git: atribuição inteligente do nível de sandbox na inicialização conforme a presença ou ausência de Git no diretório ([15]).

Third, inversamente, alguns componentes do Claude Code funcionam em formatos diferentes no Codex. Por exemplo, a variação local CLAUDE.local.md é substituída pelo AGENTS.override.md, embora com semântica diferente. A lista branca de permissões para comandos específicos corresponde a rules experimentais no Codex (escritas em Starlark, não como arrays JSON).

Leia com atenção a seguinte lista de verificação antes de iniciar a migração:

Suposição comum	Realidade no Codex
❌ O Codex também lê o `CLAUDE.md`	✅ Ele lê apenas o `AGENTS.md` (exceto se configurado em `project_doc_fallback_filenames`)
❌ A memória vem ativada por padrão e grava tudo automaticamente	✅ Memories vêm desativadas por padrão, rodam de forma assíncrona e possuem restrições regionais
❌ Basta copiar o arquivo `settings.json`	✅ É necessário reescrevê-lo no formato TOML como `config.toml`
❌ O controle de permissões é baseado em lista branca de ferramentas	✅ É gerenciado através de dois controles: sandbox e aprovação
❌ Alternar permissões via `Shift+Tab`	✅ O ajuste é feito digitando `/permissions` no terminal do Codex

💡 Resumo em uma frase: O maior risco na migração é presumir que o comportamento é idêntico. Lembre-se de que a memória fica desativada por padrão; o Codex introduz recursos como AGENTS.override.md, Chronicle e seleção de nível de sandbox baseada no Git; e as permissões operam via controles separados, não por listas brancas. Revise os itens acima antes de começar.

08 Prática: Convertendo um `CLAUDE.md` para `AGENTS.md`

A melhor forma de aprender é praticando. A seguir, usaremos um exemplo prático de arquivo CLAUDE.md para demonstrar a migração manual para AGENTS.md e validar se o Codex leu as instruções. Siga os passos abaixo, leva apenas cinco minutos.

Nota sobre diferenças de plataforma: os comandos mkdir e git init mostrados a seguir funcionam diretamente no Mac / Linux. No Windows, recomendamos utilizá-los no Git Bash, WSL ou criar os itens manualmente via Explorador de Arquivos. A referência ~ representa a pasta inicial do usuário, que no Windows corresponde ao caminho C:\Users\SeuNomeDeUsuario\.

Passo 1: Preparar um CLAUDE.md para migração.

Crie um projeto fictício e salve um CLAUDE.md típico (simulando um arquivo herdado do Claude Code):

bash

mkdir migrate-demo && cd migrate-demo
git init

Crie o arquivo CLAUDE.md na raiz do projeto e insira o seguinte conteúdo (com algumas linhas de contexto dispensáveis para demonstrar a limpeza de instruções):

# migrate-demo 项目说明

这是一个基于 FastAPI 的订单管理后端。本项目由订单团队在 2023 年立项，
最初用 Flask，后来为了异步性能迁到 FastAPI，技术选型经过三轮评审……（一大段背景）

## 技术栈

- Python 3.11 / PostgreSQL / pytest

## 常用命令

- `pytest` —— 运行测试
- `ruff check .` —— 跑 lint

## 编程约定

- 所有函数必须有类型注解
- 字符串统一用双引号

## 禁区

- 不要改动 migrations/ 里已有的迁移文件
- 新增生产依赖前先问我

Resultado esperado: o arquivo CLAUDE.md é criado na raiz. Observe a descrição do histórico do projeto — o Codex não precisa dessas informações para gerar código, sendo a parte ideal para ser removida durante a migração.

Passo 2: Converter para AGENTS.md.

Crie um novo arquivo AGENTS.md, copie as informações relevantes e aproveite para remover o histórico de desenvolvimento (mantendo o restante do conteúdo quase igual):

# migrate-demo — 基于 FastAPI 的订单管理后端

## 技术栈

- Python 3.11 / PostgreSQL / pytest

## 常用命令

- `pytest` —— 运行测试
- `ruff check .` —— 跑 lint

## 编程约定

- 所有函数必须有类型注解
- 字符串统一用双引号

## 禁区

- 不要改动 migrations/ 里已有的迁移文件
- 新增生产依赖前先问我

Resultado esperado: o arquivo AGENTS.md é criado na raiz do projeto, mais curto do que o original CLAUDE.md — as partes removidas eram apenas contextos que o Codex consegue identificar analisando o próprio código ou que não têm utilidade prática. Este é um exemplo real de "migração de conteúdo com otimização".

Passo 3: Pedir ao Codex para repetir as regras detectadas, a fim de validar a migração.

Execute o seguinte comando no diretório do projeto (solicitando apenas um resumo; o uso de --ask-for-approval never serve para evitar pedidos de aprovação no terminal e obter uma resposta limpa — este é o método padrão recomendado na documentação oficial para atestar a leitura do AGENTS.md, pode usar tranquilamente):

bash

codex --ask-for-approval never "Summarize the current instructions."

Resultado esperado: o Codex exibirá as regras que você acabou de configurar — stack técnica, comandos pytest / ruff, anotações de tipo, uso de aspas duplas, regras de migração e novos pacotes. Se ele retornar esses itens, significa que o arquivo AGENTS.md foi importado com sucesso no contexto da sessão e a migração foi concluída.

Passo 4 (Opcional): Remover o arquivo CLAUDE.md antigo.

Após validar a migração, manter o arquivo CLAUDE.md antigo não trará problemas (pois o Codex não o lerá), mas pode confundir outros desenvolvedores da equipe. A exclusão do arquivo fica a seu critério — como esta é uma operação de alteração de sistema, execute-a manualmente em vez de delegar ao assistente. Caso queira que o Codex também considere arquivos com nome CLAUDE.md (útil em períodos de transição com sistemas legados ativos), adicione a seguinte linha em ~/.codex/config.toml:

toml

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md"]

Ao incluir essa configuração, a sequência de busca do Codex em cada diretório passa a ser AGENTS.override.md → AGENTS.md → CLAUDE.md, selecionando o primeiro arquivo existente e preenchido. Esta é a maneira mais simples de garantir que arquivos CLAUDE.md antigos continuem funcionando durante a transição (reinicie o Codex após fazer a alteração para aplicá-la).

💡 Resumo em uma frase: Migração = transferir o conteúdo do CLAUDE.md para o AGENTS.md + remover descrições excessivas de histórico, validando a importação com "Summarize the current instructions". Para manter compatibilidade com o CLAUDE.md antigo durante a transição, configure project_doc_fallback_filenames.

Resumo

Neste capítulo, abordamos de forma prática a transição conceitual e de ambiente ao migrar do Claude Code para o Codex:

Dimensão	Conclusão principal
Visão geral	90% do modelo mental pode ser usado diretamente; o aprendizado consiste em descobrir "onde as coisas ficam e como são chamadas"
Instruções do projeto	`CLAUDE.md` → `AGENTS.md`, com conteúdo migrável, mas com diferenças em mecanismo de sobreposição temporária e limites de tamanho (linhas → bytes)
Arquivo de configuração	`settings.json` (JSON) → `config.toml` (TOML), exigindo reescrever no novo formato e evitar vírgulas extras típicas de JSON
Modelo de permissões	De modo de permissão + lista branca para dois controles separados: sandbox e aprovação; lembre-se de que "sem perguntas ≠ privilégios extras"
Hábitos de interação	A maioria dos comandos com barra é idêntica; a principal diferença está na alteração de permissões (`Shift+Tab` → `/permissions`)
Evite surpresas	Memória desativada por padrão, e recursos novos no Codex como `AGENTS.override.md` e Chronicle

Agora você deve ser capaz de: migrar um CLAUDE.md de forma limpa para AGENTS.md; saber como reconfigurar o settings.json em um novo config.toml; substituir a estrutura antiga de "modos + lista branca" pela abordagem "sandbox + aprovação" do Codex; e desviar dos erros comuns de suposição de comportamento idêntico. Em resumo — a experiência adquirida no Claude Code continua valendo, apenas sob uma nova roupagem.

O próximo artigo (33 Pontos de Atenção no Windows) — no qual recomendei aos usuários do Windows usarem o Git Bash ou WSL: por que isso é necessário? Quais são os problemas comuns relacionados ao uso do Codex no Windows, incluindo sandbox, caminhos de arquivo e terminal? Fica uma pequena reflexão: como o Codex implementa o sandbox em sistemas operacionais que não oferecem nativamente os recursos de isolamento presentes no Linux? Detalharemos o ecossistema Windows no próximo capítulo.

Migrando do Claude Code: Trocando a ferramenta com o mesmo mapa, você ainda encontra o caminho de casa ​

01 Garantia inicial: 90% do seu modelo mental pode ser transferido diretamente ​

02 Uma grande tabela comparativa: nomes antigos → nomes novos ​

03 Instruções do projeto: CLAUDE.md → AGENTS.md ​

04 Arquivo de configuração: settings.json (JSON) → config.toml (TOML) ​

05 Modelo de permissões: Modo de permissão → Sandbox + Aprovação ​

06 Hábitos de interação: Diferenças e semelhanças nos comandos com barra e gerenciamento de sessões ​

07 Evite suposições automáticas: Diferenças e ausências no Codex ​

08 Prática: Convertendo um CLAUDE.md para AGENTS.md ​

Resumo ​

Leituras recomendadas ​