🧠 Por que separar o cérebro do modelo
Todo mundo pergunta "como migro do Claude pro Codex?". A pergunta certa é outra: o que do seu trabalho sobrevive à troca de modelo? Este módulo mostra onde você está preso sem perceber, o que é durável de verdade, e o princípio que guia o curso inteiro: não migre o cérebro, separe o cérebro do modelo.
🔒 O lock-in invisível
Você não assinou contrato nenhum, mas está preso. Cada regra que você escreveu num CLAUDE.md, cada fato que o Claude guardou na memória dele, cada sessão que ficou gravada em arquivo JSONL: tudo isso só o Claude lê. Se amanhã você abrir o Codex, ele começa do zero, como se você nunca tivesse trabalhado. Isso é lock-in, e ele é invisível porque cresceu um arquivo por vez.
Novo aqui? Lock-in é ficar preso a um fornecedor porque sair custa caro. CLAUDE.md é o arquivo de instruções que o Claude Code lê ao abrir uma pasta. JSONL é um formato de texto com um objeto JSON por linha; é assim que o Claude grava o histórico de cada sessão. Nenhum outro programa se importa com esses arquivos.
📊 O tamanho do problema numa máquina real (diagnóstico de 2026-09-14)
- •165 projetos com CLAUDE.md, e só 54 com AGENTS.md (o arquivo que o Codex lê).
- •869 arquivos de memória em 227 pastas, que só o Claude abre.
- •6.859 sessões JSONL, 2,3 GB de histórico que nenhuma outra ferramenta consegue usar.
- •O Codex, instalado na mesma máquina, sem instruções globais e sem MCP: cada sessão começa cega.
✓ Sinais de que você está bem
- ✓Suas regras estão num arquivo que qualquer ferramenta lê.
- ✓Um colega abriria seu projeto e entenderia o estado sem você.
- ✓Você sabe onde está a última decisão tomada.
✗ Sinais de lock-in
- ✗"O Claude sabe" é a resposta pra onde está alguma informação.
- ✗Trocar de ferramenta significa reexplicar tudo.
- ✗O histórico da sessão é a única fonte do que foi decidido.
Conceitos-chave
Dependência que cresce sem contrato, um arquivo por vez.
Instruções que só o Claude Code lê.
Fatos guardados no formato de uma ferramenta só.
Histórico bruto, gigante, ilegível para outra ferramenta.
🗂️ O que é durável e o que é descartável
Nem tudo merece ser migrado. A maior parte do que está na pasta do Claude é rastro: sessões antigas, tentativas descartadas, arquivos mortos. O que vale a pena é pequeno e tem cara de documento: o que o projeto é, o que foi decidido, o que está em andamento, como se faz cada coisa. Separar os dois é o primeiro trabalho, e ele é mais faxina do que engenharia.
Olhe o centro: o que é seu vive em Markdown dentro do projeto. As caixas azuis nas bordas são só executores; qualquer uma pode ser trocada sem que o centro mude.
✓ Durável: vale migrar
- ✓Contexto do projeto: o que é, pra quem, o que funciona.
- ✓Decisões aceitas, com data e motivo.
- ✓Playbooks e skills: como se faz cada tarefa.
- ✓Handoffs: onde parou e o que vem depois.
✗ Descartável: arquive por padrão
- ✗Sessões JSONL inteiras (2,3 GB de conversa bruta).
- ✗Memória automática sem aprovação (869 arquivos que ninguém revisou).
- ✗Configuração de plugin e hook: é da ferramenta, não sua.
- ✗Skills arquivadas que você não usa há meses.
💡 Dica prática
Regra do texto-base: arquive por padrão, traga de volta só quando precisar. Antes de migrar qualquer coisa, faça a faxina do seu "segundo cérebro". Migrar rastro só transporta ruído para a ferramenta nova.
Conceitos-chave
Contexto, decisões, playbooks, handoffs: o que sobrevive à troca.
Histórico bruto e configuração de ferramenta.
O default é guardar longe; contexto entra só quando é usado.
Texto simples que qualquer ferramenta lê. É o formato do cérebro.
🔄 Modelos mudam, sua estrutura fica
Olhe a linha do tempo dos últimos meses: um modelo novo a cada poucas semanas, cada um com nome, harness e manias próprias. Se a sua forma de trabalhar depende de um modelo específico, ela envelhece na mesma velocidade. Se depende de uma estrutura de arquivos, ela envelhece na velocidade do Markdown, ou seja, quase nunca.
Novo aqui? Modelo é o cérebro de IA em si (Claude, GPT, DeepSeek). Harness é o programa que dá mãos e olhos ao modelo: lê arquivos, roda comandos, mantém o histórico. Claude Code e Codex CLI são harnesses. O módulo 1.2 aprofunda esses termos.
Ontem: um harness, um modelo
Você escolheu uma ferramenta e moldou tudo nela: regras, memória, atalhos. Funcionava, e o preço ficou escondido.
Hoje: dois ou três harnesses na mesma máquina
Claude pra uma coisa, Codex pra outra, um modelo local pra tarefa barata. Cada um começa do zero porque o cérebro ficou no primeiro.
Amanhã: o modelo que você ainda não conhece
Vai aparecer. A única pergunta é se você vai reexplicar tudo ou apontar pra uma pasta e dizer "leia isto".
🧭 A frase que resume o curso
"O que realmente deve sobreviver à troca de modelo não é o Claude, o Codex ou o Gemini. É a sua camada de contexto, conhecimento, Markdown, processos, handoffs, memória e ferramentas."
Os modelos podem mudar. A sua estrutura de trabalho deve continuar funcionando.
Conceitos-chave
Modelo: semanas. Markdown: anos.
Qualquer harness que lê a camada portátil e age.
Pastas e arquivos com papel definido, não uma conversa.
O teste: apontar pra uma pasta substitui reexplicar?
⭕ O Diagrama de Venn: comum vs específico
O texto-base dá um exemplo com dois clientes, North Star e Harbor: descubra o que os dois têm em comum, centralize essa parte, e mantenha pastas separadas só para o que é exclusivo de cada um. A mesma lógica vale para ferramentas. O que Claude e Codex têm em comum é quase tudo: regras, contexto, decisões, skills em Markdown. O que é específico cabe em dois arquivos.
A área verde no meio é onde mora o seu trabalho. As pontas azuis são pequenas de propósito: só o que a ferramenta exige. Se as pontas crescerem, você está reescrevendo o comum duas vezes.
📐 A parte específica é menor do que parece
Segundo o texto-base, apenas AGENTS.md e CLAUDE.md estão fortemente ligados ao provedor. O Gemini também lê AGENTS.md; o GLM pode ser orientado a respeitá-lo. O CLAUDE.md é a exceção. Praticamente todo o resto é Markdown portátil.
Na máquina auditada: do CLAUDE.md global de 72 linhas, 71 eram portáteis e 7 eram específicas do Claude (menus interativos, plugins, hooks). É essa proporção que você deve esperar.
Conceitos-chave
O que todas as ferramentas usam. Centralize aqui.
O que é exclusivo de cada uma. Mantenha pequeno.
O arquivo de instruções que Codex, Gemini e outros leem.
Quanto maior o meio, menos você escreve duas vezes.
💸 O custo de não fazer nada
Não separar o cérebro do modelo parece de graça, porque nada quebra hoje. O custo aparece em pequenas doses: o Codex que responde errado porque não leu suas regras, a decisão tomada duas vezes porque ficou perdida numa sessão, a skill copiada à mão que divergiu da original, o colega (ou você em três meses) que não sabe por onde começar.
✗ O que você paga sem perceber
- ✗Reexplicar o projeto a cada ferramenta nova.
- ✗Skills que divergem: na máquina auditada, 4 lugares diferentes consumiam skills sem uma fonte única.
- ✗Decisões contraditórias porque a versão "certa" era a mais recente na conversa.
- ✗Impossível delegar: só a sua conta do Claude "sabe".
✓ O que a separação devolve
- ✓Qualquer executor entra no projeto e lê a mesma verdade.
- ✓Uma skill, N cópias geradas, com checagem de divergência.
- ✓Decisão tem arquivo, data e dono.
- ✓Você pode trocar de modelo numa tarde, não num mês.
⚠️ Aviso honesto do texto-base
"Tudo isso é iterativo. Cada alteração pode melhorar uma skill para um modelo e quebrar essa mesma skill para outro." Separar o cérebro não elimina manutenção; ela passa a acontecer num lugar só, em vez de em cada ferramenta.
Conceitos-chave
Pago em pequenas doses, nunca numa fatura.
Cópias que divergem da original com o tempo.
Outra pessoa ou outro agente consegue continuar?
Um lugar pra editar, N lugares pra gerar.
🧩 O princípio central
Sete palavras formam a camada que sobrevive: contexto, conhecimento, Markdown, processos, handoffs, memória e ferramentas. Cada uma vira uma pasta ou um arquivo no seu projeto, e cada trilha deste curso mostra como. Guarde a lista; ela é o mapa do que você vai construir.
Contexto e conhecimento
O que o projeto é, o que é verdade hoje, de onde veio cada fato. Vira context/overview.md, current-state.md e sources.md.
Markdown e processos
O formato e os "como se faz": AGENTS.md, skills, scripts. Portáteis porque são texto.
Handoffs e memória
Onde parou e o que foi aprendido: handoffs/latest.md e fatos promovidos com aprovação.
Ferramentas
MCP e scripts, registrados por ferramenta mas referenciando as mesmas chaves e os mesmos dados.
🎯 Resumo em uma frase
Não migre seu "cérebro" de Claude para Codex; separe o cérebro do modelo.
Claude, Codex, Gemini ou modelos locais viram apenas executores sobre uma camada de contexto portátil.
Conceitos-chave
Contexto, conhecimento, Markdown, processos, handoffs, memória, ferramentas.
O que roda por cima da camada. Trocável.
O que fica. Sua, em Markdown, dentro do projeto.
O verbo do curso inteiro.
Auto-checagem (opcional): qual frase resume melhor a tese deste módulo?
🎯 Resumo do módulo
Próximo módulo:
1.2 — O vocabulário: runtime, harness, skill, MCP, hook, handoff