🧠 Fundamentos

"Lock-in" é ficar preso a um fornecedor. Nesta máquina ele tem forma concreta: 165 projetos com regras em CLAUDE.md, 869 arquivos de memória e 2,3 GB de sessões que só o Claude Code sabe ler.

Você só percebe o lock-in no dia em que abre o Codex e ele começa do zero. Enxergar isso antes é o que motiva a separação.

Lock-in, memória nativa, sessão JSONL, "o Codex entra cego".

Durável é o que sobrevive à troca de modelo: contexto do projeto, playbooks, decisões, handoffs, documentação. Descartável é o estado nativo: cache, histórico bruto, configuração do harness.

Migrar tudo transporta ruído. Migrar só o durável cabe em Markdown e funciona em qualquer runtime.

Camada durável, estado nativo, Markdown portátil, "arquive por padrão".

Claude, Codex, Gemini ou um modelo local viram apenas executores. O que precisa sobreviver é a sua estrutura de trabalho, não o provedor da vez.

Cada versão nova de modelo pode melhorar uma skill e quebrar outra. Estrutura estável absorve essas mudanças sem reconstrução.

Executor, camada portátil, independência de provedor.

Pense em dois clientes, North Star e Harbor. O que os dois têm em comum vai para o centro, compartilhado; só o que é exclusivo fica em pasta própria. O mesmo vale para runtimes: o comum ao Claude e ao Codex vai para o centro.

Quanto maior a área do meio, mais reutilizável o sistema e menos manutenção duplicada.

Interseção, centralizar o comum, pastas específicas só para o exclusivo.

Sem a separação, um segundo runtime fica subutilizado: no diagnóstico real, 2.424 sessões no Claude contra 64 no Codex em 14 dias, e o Codex sem AGENTS.md global, sem MCP e com um quarto das skills.

O custo não é só dinheiro: é retrabalho, contexto perdido e dependência de um único fornecedor em momentos de bloqueio.

Subutilização, retrabalho, risco de fornecedor único.

O que deve sobreviver à troca de modelo é a camada de contexto + conhecimento + Markdown + processos + handoffs + memória + ferramentas. Em uma frase: não migre seu cérebro de Claude para Codex; separe o cérebro do modelo.

É a régua para toda decisão do curso: se algo não cabe numa dessas sete camadas, provavelmente é estado nativo e fica no resíduo.

As sete camadas, resíduo do runtime, a frase-resumo.

Modelo é o cérebro de IA (Claude Fable, GPT-6 Astra, um Qwen local). Runtime é o programa que você roda no terminal (Claude Code, Codex CLI). Harness é a "carroceria" em volta do modelo: ferramentas, loop de execução, permissões, memória.

Quase tudo que "prende" você está no harness, não no modelo. Separar os três nomes mostra onde mexer.

Modelo, runtime, harness, loop agentic.

Arquivo de instruções é o texto que o runtime lê antes de trabalhar. O Claude lê CLAUDE.md; Codex, Gemini e OpenCode leem AGENTS.md. É o único ponto realmente preso ao provedor.

Com um AGENTS.md portátil e um CLAUDE.md que começa com "@AGENTS.md", os dois runtimes leem a mesma fonte.

CLAUDE.md, AGENTS.md, import @AGENTS.md, ordem de leitura explícita.

Skill é uma pasta com um SKILL.md (instruções de como fazer uma tarefa) e, às vezes, scripts. O Claude procura em ~/.claude/skills; o Codex em ~/.codex/skills e ~/.agents/skills; o projeto pode ter .agents/skills.

O formato é quase o mesmo. O que muda é o caminho de descoberta e as ferramentas que a skill assume existir.

SKILL.md, caminhos de descoberta, skill canônica, adaptador por runtime.

MCP (Model Context Protocol) é um padrão para o runtime acessar ferramentas e dados externos, como o Magnific ou o Metricool. Ele dá acesso; não funde históricos de chat, não resolve conflito de memória, não separa clientes.

Muita gente trata MCP como memória portátil. Ele é encanamento. Registrar um MCP no Codex é o que destrava as skills que dependem dele.

MCP, servidor de ferramentas, credenciais referenciadas (nunca copiadas).

Hook é um script que o runtime dispara num evento (início de sessão, depois de editar). Plugin é uma extensão instalada no runtime. Subagente é um papel com prompt próprio. Os eventos e formatos não são iguais entre Claude e Codex.

Esses três são o "resíduo" que não migra. Saber isso evita tentar portar o que não tem equivalente.

SessionStart vs PostToolUse, plugin, subagente, nativo-only.

Handoff é um resumo estruturado do fim da sessão: decisões, pendências, próximos passos, caminhos de arquivo, salvo em Markdown. Prime é a leitura desse resumo no começo da sessão seguinte, em qualquer runtime.

É o mecanismo que substitui a dependência dos históricos JSONL nativos. Sessão → handoff → Markdown → prime → nova sessão.

Handoff, prime, handoffs/latest.md, continuidade cross-runtime.

O app desktop do Codex tem um botão Importar que traz skills, comandos, plugins, projetos e sessões do Claude Code. O Codex CLI 0.154 não tem esse comando: o "um clique" só existe na interface gráfica.

Evita procurar um comando que não existe e mostra que o import nativo é parte da solução, não a solução.

Import nativo, app vs CLI, itens pulados no import.

O texto-base imagina um "npx migrate to codex". Aqui esse comando é o kit agente-claude-codex: doctor, audit, adapt-instructions, init-core, sync-skills e readback-test, sempre em modo audit antes de alterar algo.

Um agente audita o setup inteiro antes de migrar, para nenhum detalhe se perder. Esse é o nível que a Trilha 2 executa passo a passo.

Kit, auditoria por agente, scripts reversíveis.

Conhecimento privado, contexto dos projetos, overview.md, sources.md, playbooks, handoffs e documentação. É a camada que não fica presa a nenhum modelo.

Para a maioria das pessoas é o único nível que muda o resultado. Os outros dois são logística.

Camada durável, playbooks, overview.md, sources.md.

A maior parte da migração é limpeza: arquivos mortos, coisas antigas, documentos arquivados, informação irrelevante. Arquive por padrão e traga de volta só quando precisar. CLAUDE.md de 1.391 linhas é ruído nos dois runtimes.

É o mesmo tipo de organização que você faria no computador mesmo sem IA. Migrar sujeira só muda a sujeira de lugar.

Arquivar por padrão, contexto sob demanda, segundo cérebro limpo.

Basicamente só o arquivo de instruções é preso ao provedor. O Gemini também usa AGENTS.md; um modelo local pode ser orientado a respeitá-lo. CLAUDE.md é a exceção específica do Claude. Praticamente todo o resto é Markdown portátil.

Reduz o medo: a parte que precisa de adaptador é pequena e conhecida.

Instruções específicas, Markdown portátil, adaptador mínimo.

Para Claude e Codex, não perca tempo construindo um "super-harness": os fornecedores já otimizam e adaptam os deles a cada modelo novo. Para modelos locais, o harness padrão é fraco e aí vale evoluir o seu, usando sessões excelentes como referência.

Direciona o esforço: contexto portátil para todos, harness próprio só onde faz diferença.

OmniAgent, super-harness, harness para modelo local, dsh-sandbox.

README.md é o onboarding de gente: como rodar, como testar, estrutura. AGENTS.md é curto, direto ao agente, e começa com a ordem de leitura dos outros arquivos.

Misturar os dois faz o agente ler tutorial e o humano ler regra de máquina. Separar deixa cada um enxuto.

Público de cada arquivo, ordem de leitura, instrução concisa.

overview.md guarda o que o projeto é, fatos verificados com fonte e data, preferências e hipóteses. current-state.md diz o que funciona e o que está pendente hoje.

Uma sessão nova responde "qual é o objetivo?" lendo esses dois arquivos, sem vasculhar histórico.

Overview, estado atual, fato datado, briefing de partida.

sources.md lista cada fonte com tipo (arquivo local, export datado, conexão viva), data, escopo e regra de refresh. decisions/ tem um arquivo por decisão aceita, com contexto e consequências.

Quando duas versões de uma informação brigam, a fonte e a decisão aceita resolvem. Sem isso, vence o arquivo mais recente, que nem sempre está certo.

Fonte, snapshot datado, decisão aceita, provenance.

O arquivo do trabalho atual: objetivo, quem é o dono, critério de pronto verificável, próxima ação concreta e bloqueios.

O agente passa a entender não só o histórico, mas o que está sendo feito agora e quando pode dizer "pronto".

Tarefa atual, dono, critério de aceite, próxima ação.

O handoff mais recente, sempre no mesmo caminho: projeto e escopo, objetivo, estado aceito, arquivos alterados, checks rodados com resultado, perguntas abertas e próxima ação exata.

Um caminho fixo ("latest") é o que permite ao Codex retomar o que o Claude deixou, e vice-versa.

latest.md, estado aceito, checks com evidência, próxima ação.

Skills reutilizáveis ficam em .agents/skills/ (onde o Codex procura) e comandos comuns em scripts/. Mas context/, tasks/ e handoffs/ são convenção sua: nenhum runtime os carrega sozinho. O AGENTS.md precisa mandar ler.

Uma estrutura bonita que o agente ignora não vale nada. A ordem de leitura explícita é o que a torna real.

Convenção vs auto-load, .agents/skills, scripts reproduzíveis.

Fato é o que foi verificado (versão do Codex é 0.154). Preferência é gosto do dono (autor de commit inematds). Hipótese é o que se supõe sem checar. Decisão é o que foi aceito depois de discutir.

Uma hipótese anotada como fato vira regra errada que o agente segue com confiança. Separar os tipos corta esse erro na origem.

Fato, preferência, hipótese, decisão.

Toda nota durável leva um ID, o escopo (projeto, máquina, cliente), a fonte, a data de observação, o status (rascunho, aceito, revogado) e quando revisar ou expirar.

Responde a pergunta clássica: "qual das várias versões dessa informação é a correta?".

Metadados da nota, data de observação, expiração, dono por tipo.

Provenance é a origem rastreável de uma informação. Em conflito, vence a fonte mais confiável e a decisão aceita, não o arquivo mais novo. O openpcbotv3 faz isso marcando a versão antiga com superseded_by em vez de apagar.

Timestamp premia quem escreveu por último, inclusive um agente que chutou. Provenance premia quem verificou.

Provenance, conflito, superseded_by, nunca apagar, só esconder.

A memória nativa (869 arquivos do Claude, conversas) é matéria-prima. Promover é escolher um fato verificado e escrevê-lo no overview.md com fonte e data, de forma deliberada. Nunca copiar em massa.

Copiar tudo transporta hipóteses e ruído. Promover fato a fato mantém o overview curto e confiável.

Promoção deliberada, matéria-prima vs fonte, vault curado.

Qualquer índice de busca, cache ou banco vetorial deve poder ser reconstruído a partir dos registros que você possui. A fonte da verdade é o Markdown; o índice é derivado.

Se o índice é a única cópia, você tem lock-in de novo, só que numa ferramenta de busca.

Fonte vs derivado, rebuild, snapshot curado antes de retrieval.

Chaves de API, estado nativo cru e material pessoal ou de cliente não entram no repositório portátil. Keys ficam em .env e são referenciadas; evidência bruta fica separada do que foi promovido.

Nesta máquina há 269 arquivos de segredo em ~/projetos. Um workspace portátil que os arrasta junto é um vazamento esperando acontecer.

Segredo referenciado, evidência bruta separada, escopo de cliente.

Os dois mega-prompts têm um campo MODE. Em audit, o agente inspeciona, classifica e devolve um plano com árvore proposta, mapeamentos e critérios de aceite, sem tocar em arquivo. Só depois você roda de novo com MODE: implement e escopo acordado.

Migração é difícil de reverter. Ler o plano antes custa minutos; desfazer uma cópia em massa custa dias.

MODE audit/implement, plano revisável, mudanças reversíveis, escopo declarado.

"Aja como meu engenheiro de migração": confirma escopo e evidência, inventaria o sistema (instruções, skills, comandos, hooks, plugins, MCP, memória), checa o alvo antes de converter, produz o plano em tabela, implementa só em implement, separa lógica portátil de integração nativa, verifica continuidade e entrega com handoff.

É o roteiro completo de uma migração honesta, incluindo o que não transfere sem mudança.

WORKSPACE_ROOT, SOURCE_ROOTS, TARGETS, REPRESENTATIVE_TASK, KEEP_UNCHANGED.

"Aja como meu arquiteto de workspace": inspeciona antes de desenhar, propõe o menor núcleo portátil, implementa README/AGENTS/context/tasks/handoffs, define donos da informação, adiciona adaptadores nativos pequenos, controla distribuição de contexto, prova portabilidade e entrega. Tem add-ons para uso pessoal, cliente ou misto.

Serve tanto para adaptar um projeto existente quanto para nascer portátil desde o primeiro commit.

PILOT_PROJECT, KNOWLEDGE_SOURCES, CLIENT_SCOPE, add-on pessoal/cliente.

Cada ativo do setup recebe uma de quatro etiquetas: reutilizável como está, precisa de adaptador, só existe no runtime de origem, ou não resolvido. Nesta máquina: 72 skills reutilizáveis, 15 de adaptador, 2 nativas, 1 sem SKILL.md.

Transforma "migrar tudo" em uma lista com destino, rollback e teste por item.

Matriz origem → destino, classificação, rollback, critério de aceite por ativo.

Todo check tem um de três estados. "Não rodado" é resposta válida e obrigatória quando faltou acesso ou tempo; vem com os passos para reproduzir. O próprio PDF admite que nenhuma migração real foi testada pelos autores.

Um relatório que distingue os três estados é o que separa migração feita de migração declarada.

Passou / falhou / não rodado, reprodução, relatório honesto.

Uma árvore gerada, um import bem-sucedido ou uma configuração com sintaxe válida não provam comportamento equivalente. A prova é uma sessão nova que responde: objetivo atual, uma regra com o arquivo de origem, última decisão, próxima ação e conflitos.

É o teste de continuidade que a Trilha 2 executa de verdade, no Claude e no Codex. Encontrou? Leu? Entendeu? Usou?

Readback em sessão nova, as 5 perguntas, prova de uso.