🗺️ Os três níveis de migração
Um clique, um comando, pessoal. A newsletter que deu origem a este curso divide a migração do Claude para o Codex em três níveis. Os dois primeiros são mecânicos e rápidos; o terceiro é o que realmente importa e o que nenhuma ferramenta faz por você. Aqui você entende cada nível, o que é de fato específico do modelo, por que a maior parte do trabalho é uma faxina, e quando vale a pena construir seu próprio harness.
🖱️ Nível 1: importar no app Codex
O nível mais raso é o mais fácil: você abre o app desktop do Codex, clica em Importar, e ele puxa do Claude Code as skills, os comandos, os plugins, os projetos e as sessões de chat. É a promessa do "um clique". Funciona, e para quem só quer experimentar o Codex com o que já tem, resolve.
Mas há uma pegadinha que a auditoria desta máquina revelou: o Codex CLI (a versão de terminal, 0.154 na data do diagnóstico) não tem comando import. O "um clique" existe só no app desktop. Se o seu fluxo é no terminal, o nível 1 simplesmente não está disponível para você. É por isso que o curso existe: para o nível 2 e o 3.
Novo aqui? "Import nativo" é quando a própria ferramenta de destino oferece um botão ou comando oficial para trazer a configuração de outra ferramenta. "CLI" é a versão de linha de comando (você digita codex no terminal); "app desktop" é a janela com interface gráfica. São o mesmo produto, mas nem sempre têm os mesmos recursos.
✓ O que o nível 1 resolve
- ✓Traz skills, comandos e plugins de uma vez, sem você mexer em arquivo.
- ✓Copia projetos e sessões de chat, então o histórico não some.
- ✓Ideal para testar o Codex em 5 minutos.
✗ O que ele não resolve
- ✗Não existe no CLI: quem trabalha no terminal fica sem.
- ✗Copia o ruído junto: skills mortas, sessões velhas, memória sem aprovação.
- ✗Não separa nada: você continua com dois cérebros, agora duplicados.
- ✗Nada garante que o Codex vai usar o que importou.
Conceitos-chave
Botão oficial da ferramenta de destino. Só no app desktop do Codex.
Mesmo produto, recursos diferentes. O CLI 0.154 não importa.
Importar duplica o cérebro; não o torna portátil.
Rode codex --help e olhe a lista de comandos você mesmo.
⌨️ Nível 2: um comando
O segundo nível é a ideia de um comando que leva todos os seus recursos do Claude Code para o Codex. O texto original imagina algo como npx migrate to codex e sugere que dá para adaptar para uma stack com Gemini. Ele também recomenda, antes de rodar qualquer coisa, deixar um agente auditar toda a configuração do Claude para que nenhum detalhe se perca.
Esse comando hipotético não existe pronto. Foi por isso que o kit agente-claude-codex nasceu: ele é o nível 2 desta máquina, quebrado em cinco scripts que rodam em ordem e que você vai usar de verdade na Trilha 2.
Leia como uma escada: o nível 1 é mecânico e raso, o nível 2 automatiza a mudança, e só o nível 3, em destaque, carrega o que sobrevive à troca de modelo. Quanto mais alto, mais durável.
🧰 O "um comando" desta máquina: cinco scripts em ordem
scripts/doctor.sh e scripts/audit.sh: diagnosticam o ambiente e inventariam skills, hooks, MCP, sem alterar nada.
scripts/adapt-instructions.sh: separa o CLAUDE.md em AGENTS.md portátil mais resíduo Claude.
scripts/init-core.sh: instala o núcleo portátil sem sobrescrever o que já existe.
scripts/sync-skills.sh: uma fonte canônica de skill, cópias geradas por runtime, checagem de drift.
scripts/readback-test.sh: abre sessão nova em cada runtime e prova que o agente leu e usou o contexto.
💡 Dica prática
Todo script do nível 2 começa em modo audit: lê e relata, não muda. Só depois que você leu o relatório e aprovou, o passo seguinte altera arquivos, e sempre com backup ao lado. Se um "comando de migração" que você encontrar por aí não tiver essa fase de auditoria, desconfie.
Conceitos-chave
Migração automatizada e reproduzível, não manual.
Um agente inventaria tudo para nada se perder.
O kit que implementa o nível 2 em cinco scripts.
Cada passo tem backup ou gera arquivo proposto.
🧠 Nível 3: a camada pessoal durável
Este é o nível que realmente importa para a maioria das pessoas. Aqui entram o conhecimento privado, o contexto dos projetos, o overview.md, o sources.md, os playbooks, os handoffs e a documentação. É a camada durável, a que não fica presa a nenhum modelo específico. Nenhum botão de importar e nenhum script fazem isso por você, porque é a sua forma de trabalhar, não uma configuração.
Pense no que aconteceria se amanhã o Claude e o Codex sumissem e você tivesse que usar um terceiro agente. O que você gostaria de ter guardado em arquivos comuns, legíveis por qualquer um? Isso é o nível 3.
Conhecimento privado
Fatos sobre você, seus clientes, seus projetos. Nesta máquina: os runbooks do Skool, do login INEMA.PRO, dos modelos da Magnific.
Contexto dos projetos
O que cada projeto é, onde está, o que funciona, o que está pendente. Hoje espalhado em 165 arquivos CLAUDE.md.
Playbooks e processos
Como você publica, versiona, gera imagem, entrega. Regras que valem para qualquer agente que trabalhe com você.
Handoffs
O resumo estruturado de cada sessão: decisões, pendências, próximos passos, caminhos de arquivo. Viaja para qualquer provedor.
✓ Sinais de que está no nível 3
- ✓É Markdown comum, dentro do projeto, sem depender de plugin.
- ✓Uma pessoa entende ao abrir, não só um agente.
- ✓Tem data, fonte e dono.
- ✓Sobrevive se você trocar de ferramenta amanhã.
✗ Sinais de que ainda é nível 1 ou 2
- ✗Vive em
~/.claude/projects/*/memorye só o Claude lê. - ✗Está em sessões JSONL de 2,3 GB que ninguém vai reler.
- ✗Depende de um hook ou plugin que o outro runtime não tem.
- ✗Foi importado, mas nunca lido nem aprovado.
Conceitos-chave
O que sobrevive à troca de modelo.
Fatos verificados e de onde vieram. Detalhe no 1.4.
Processo escrito que qualquer agente segue.
Resumo de sessão que a próxima sessão lê primeiro.
🧹 A grande faxina
A mudança de mentalidade principal, nas palavras do texto original: a maior parte disso é simplesmente uma grande faxina. Parece algo supercientífico, mas é basicamente um Marie Kondo para as suas pastas, o mesmo tipo de organização que você faria no computador mesmo se a IA não existisse.
O cérebro do Claude Code de muita gente está cheio de arquivos mortos, coisas antigas, documentos arquivados e informação irrelevante. Migrar isso cru só transporta o ruído. Antes de migrar qualquer coisa: limpe o "segundo cérebro", arquive por padrão, e traga informação de volta ao contexto apenas quando for necessária.
Novo aqui? "Marie Kondo das pastas" é a regra de guardar só o que ainda serve e arquivar o resto. "Segundo cérebro" é o conjunto de anotações e arquivos onde você guarda o que não cabe na cabeça. "Arquivar por padrão" significa que a regra é tirar do caminho; trazer de volta é a exceção, feita sob demanda.
📊 O ruído desta máquina, medido no diagnóstico de 2026-09-14
- •6.859 sessões JSONL do Claude, 2,3 GB, mais 209 do Codex. Histórico, não fonte.
- •227 pastas de memória com 869 arquivos que só o Claude lê e ninguém aprovou.
- •CLAUDE.md de 1.391 linhas num projeto (ruflo), 542 em outro. Arquivo desse tamanho vira ruído nos dois runtimes.
- •11 skills arquivadas e 117 ativas, das quais 89 só existem no Claude.
Inventariar
Rode a auditoria antes de decidir. Você não limpa o que não enxerga.
Arquivar por padrão
Skill que não roda há 90 dias, sessão antiga, memória sem uso: para o arquivo. Nada é apagado, só sai do caminho.
Promover o que vale
Fato verificado vai para o overview.md com data e fonte. Regra estável vai para o AGENTS.md. O resto fica onde está.
Só então migrar
Com o cérebro enxuto, o que atravessa para o Codex é pequeno, claro e útil.
Conceitos-chave
Limpar é a maior parte do trabalho, não a migração.
Tirar do caminho é a regra; trazer de volta, a exceção.
Sessões, memória e CLAUDE.md gigantes têm número.
Contexto entra na sessão quando a tarefa pede.
🎯 O que é realmente específico do modelo
Aqui está a boa notícia que muda o tamanho do problema: a parte realmente presa ao provedor é pequena. Basicamente, só o agents.md e o claude.md estão fortemente ligados a uma ferramenta. O Gemini também usa agents.md. O GLM pode ser orientado a respeitar esse arquivo. O claude.md é a única exceção realmente específica do Claude. Praticamente todo o resto é Markdown portátil.
Compare os tamanhos: a caixa pequena é tudo que depende do provedor, dois arquivos de instrução. A caixa grande, em destaque, é o seu trabalho de verdade, e é só Markdown que qualquer agente lê.
🧩 Quem lê o quê
Lê
CLAUDE.md. Com @AGENTS.md na primeira linha, importa o portátil.Lê
AGENTS.md. Sem ele, entra "cego": 13 projetos desta máquina estão assim.Também lê
AGENTS.md.Podem ser orientados a respeitar
AGENTS.md por instrução no prompt ou no harness.⚠️ O erro a evitar
Manter duas fontes de verdade: um CLAUDE.md e um AGENTS.md escritos à mão, cada um com regras diferentes. Nesta máquina, 39 projetos têm os dois arquivos e ninguém sabe qual manda. O padrão certo é um só portátil (AGENTS.md) e o outro importando (@AGENTS.md) mais o resíduo específico.
Conceitos-chave
CLAUDE.md e AGENTS.md são o que prende ao provedor.
Codex, Gemini e GLM leem; o Claude importa.
O núcleo não muda; a borda traduz para cada ferramenta.
Nunca dois arquivos de instrução divergentes.
🔧 Quando vale construir seu próprio harness
Uma tentação comum é construir um "OmniAgent" ou um super-harness que envolva todos os modelos. Para Claude e Codex, o texto é direto: não perca tempo com isso. Os harnesses deles já são bastante otimizados, e são os próprios fornecedores que fazem o trabalho de acompanhar e adaptar o harness conforme novos modelos aparecem.
Onde vale criar o seu? Para modelos locais. Nesses casos o harness padrão costuma ser muito mais fraco. É o que o autor faz com o PyHarness, treinando e evoluindo a partir de sessões excelentes feitas com modelos fortes. Nesta máquina, o caso análogo é o dsh-sandbox e o openpcbotv3, que você vai ver na Trilha 3.
Novo aqui? "Harness" é a estrutura em volta do modelo: o loop que lê sua mensagem, decide chamar ferramentas, roda comandos, lê arquivos e devolve a resposta. Claude Code e Codex são harnesses. "PyHarness" é o harness próprio, em Python, que o autor do texto mantém para modelos locais, usando como referência sessões boas de modelos como Astra e Fable. Um "super-harness" seria um harness único por cima de todos os modelos.
✓ Vale construir harness quando
- ✓O modelo é local e o harness padrão dele é fraco.
- ✓Você tem sessões excelentes de modelos fortes para usar como referência.
- ✓Privacidade, custo ou offline exigem rodar tudo em casa.
✗ Não vale quando
- ✗O alvo é Claude ou Codex: o fornecedor já otimiza e atualiza.
- ✗A motivação é "unificar tudo": o que unifica é o contexto, não o harness.
- ✗Você ainda não fez a faxina nem tem a camada durável no lugar.
🔭 Dois avisos do texto original
- •Tudo isso é iterativo. Cada alteração pode melhorar uma skill para um modelo e quebrar a mesma skill para outro. Acompanhe o que cada modelo realmente precisa.
- •Modelos fechados podem não precisar mais de skills. Se forem treinados com base nas suas conversas, muitas skills viram desnecessárias. Modelos locais talvez continuem dependendo delas. Construa agnóstico, mas acompanhe cada provedor.
Conceitos-chave
O loop de ferramentas em volta do modelo.
Não vale para Claude e Codex: eles já cuidam disso.
Aqui sim: o padrão é fraco e você pode treinar o seu.
Melhorar para um pode quebrar para outro. Medir sempre.
Auto-checagem (opcional): você trabalha no terminal com o Codex CLI e quer migrar seu setup do Claude. Qual caminho está disponível?
🎯 Resumo do módulo
Próximo módulo:
1.4 — Anatomia de um workspace portátil: AGENTS.md, context/, tasks/, handoffs/