🧠 Fundamentos

"Lock-in" es quedar atado a un proveedor. En esta máquina tiene forma concreta: 165 proyectos con reglas en CLAUDE.md, 869 archivos de memoria y 2,3 GB de sesiones que solo Claude Code sabe leer.

Solo notas el lock-in el día en que abres Codex y empieza desde cero. Verlo antes es lo que motiva la separación.

Lock-in, memoria nativa, sesión JSONL, "Codex entra a ciegas".

Durable es lo que sobrevive al cambio de modelo: contexto del proyecto, playbooks, decisiones, handoffs, documentación. Descartable es el estado nativo: caché, historial en bruto, configuración del harness.

Migrar todo transporta ruido. Migrar solo lo durable cabe en Markdown y funciona en cualquier runtime.

Capa durable, estado nativo, Markdown portátil, "archiva por defecto".

Claude, Codex, Gemini o un modelo local pasan a ser solo ejecutores. Lo que necesita sobrevivir es tu estructura de trabajo, no el proveedor de turno.

Cada versión nueva de un modelo puede mejorar una skill y romper otra. Una estructura estable absorbe esos cambios sin reconstrucción.

Ejecutor, capa portátil, independencia del proveedor.

Piensa en dos clientes, North Star y Harbor. Lo que ambos tienen en común va al centro, compartido; solo lo exclusivo queda en una carpeta propia. Lo mismo vale para los runtimes: lo común a Claude y a Codex va al centro.

Cuanto mayor es el área del medio, más reutilizable es el sistema y menos mantenimiento duplicado hay.

Intersección, centralizar lo común, carpetas específicas solo para lo exclusivo.

Sin la separación, un segundo runtime queda subutilizado: en el diagnóstico real, 2.424 sesiones en Claude contra 64 en Codex en 14 días, y Codex sin AGENTS.md global, sin MCP y con una cuarta parte de las skills.

El costo no es solo dinero: es retrabajo, contexto perdido y dependencia de un único proveedor en momentos de bloqueo.

Subutilización, retrabajo, riesgo de proveedor único.

Lo que debe sobrevivir al cambio de modelo es la capa de contexto + conocimiento + Markdown + procesos + handoffs + memoria + herramientas. En una frase: no migres tu cerebro de Claude a Codex; separa el cerebro del modelo.

Es la regla para toda decisión del curso: si algo no cabe en una de esas siete capas, probablemente es estado nativo y se queda en el residuo.

Las siete capas, residuo del runtime, la frase resumen.

Modelo es el cerebro de IA (Claude Fable, GPT-6 Astra, un Qwen local). Runtime es el programa que ejecutas en la terminal (Claude Code, Codex CLI). Harness es la "carrocería" alrededor del modelo: herramientas, bucle de ejecución, permisos, memoria.

Casi todo lo que te "ata" está en el harness, no en el modelo. Separar los tres nombres muestra dónde intervenir.

Modelo, runtime, harness, bucle agéntico.

El archivo de instrucciones es el texto que el runtime lee antes de trabajar. Claude lee CLAUDE.md; Codex, Gemini y OpenCode leen AGENTS.md. Es el único punto realmente atado al proveedor.

Con un AGENTS.md portable y un CLAUDE.md que empieza con "@AGENTS.md", los dos runtimes leen la misma fuente.

CLAUDE.md, AGENTS.md, import @AGENTS.md, orden de lectura explícito.

Una skill es una carpeta con un SKILL.md (instrucciones de cómo hacer una tarea) y, a veces, scripts. Claude busca en ~/.claude/skills; Codex en ~/.codex/skills y ~/.agents/skills; el proyecto puede tener .agents/skills.

El formato es casi el mismo. Lo que cambia es la ruta de descubrimiento y las herramientas que la skill asume que existen.

SKILL.md, rutas de descubrimiento, skill canónica, adaptador por runtime.

MCP (Model Context Protocol) es un estándar para que el runtime acceda a herramientas y datos externos, como Magnific o Metricool. Da acceso; no fusiona historiales de chat, no resuelve conflictos de memoria, no separa clientes.

Mucha gente trata MCP como memoria portable. Es tubería. Registrar un MCP en Codex es lo que destraba las skills que dependen de él.

MCP, servidor de herramientas, credenciales referenciadas (nunca copiadas).

Un hook es un script que el runtime dispara en un evento (inicio de sesión, después de editar). Un plugin es una extensión instalada en el runtime. Un subagente es un rol con prompt propio. Los eventos y formatos no son iguales entre Claude y Codex.

Esos tres son el "residuo" que no migra. Saberlo evita intentar portar lo que no tiene equivalente.

SessionStart vs PostToolUse, plugin, subagente, solo nativo.

Handoff es un resumen estructurado del final de la sesión: decisiones, pendientes, próximos pasos, rutas de archivo, guardado en Markdown. Prime es la lectura de ese resumen al inicio de la sesión siguiente, en cualquier runtime.

Es el mecanismo que reemplaza la dependencia de los historiales JSONL nativos. Sesión → handoff → Markdown → prime → nueva sesión.

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

La app de escritorio de Codex tiene un botón Importar que trae skills, comandos, plugins, proyectos y sesiones de Claude Code. El Codex CLI 0.154 no tiene ese comando: el "un clic" solo existe en la interfaz gráfica.

Evita buscar un comando que no existe y muestra que el import nativo es parte de la solución, no la solución.

Import nativo, app vs CLI, elementos omitidos en el import.

El texto base imagina un "npx migrate to codex". Aquí ese comando es el kit agente-claude-codex: doctor, audit, adapt-instructions, init-core, sync-skills y readback-test, siempre en modo audit antes de modificar algo.

Un agente audita el setup completo antes de migrar, para que ningún detalle se pierda. Ese es el nivel que la Ruta 2 ejecuta paso a paso.

Kit, auditoría por agente, scripts reversibles.

Conocimiento privado, contexto de los proyectos, overview.md, sources.md, playbooks, handoffs y documentación. Es la capa que no queda atada a ningún modelo.

Para la mayoría de las personas es el único nivel que cambia el resultado. Los otros dos son logística.

Capa duradera, playbooks, overview.md, sources.md.

La mayor parte de la migración es limpieza: archivos muertos, cosas viejas, documentos archivados, información irrelevante. Archiva por defecto y trae de vuelta solo cuando haga falta. Un CLAUDE.md de 1.391 líneas es ruido en los dos runtimes.

Es el mismo tipo de organización que harías en la computadora incluso sin IA. Migrar basura solo cambia la basura de lugar.

Archivar por defecto, contexto bajo demanda, segundo cerebro limpio.

Básicamente solo el archivo de instrucciones está atado al proveedor. Gemini también usa AGENTS.md; a un modelo local se le puede indicar que lo respete. CLAUDE.md es la excepción específica de Claude. Prácticamente todo lo demás es Markdown portátil.

Reduce el miedo: la parte que necesita adaptador es pequeña y conocida.

Instrucciones específicas, Markdown portátil, adaptador mínimo.

Para Claude y Codex, no pierdas tiempo construyendo un "súper harness": los proveedores ya optimizan y adaptan los suyos a cada modelo nuevo. Para modelos locales, el harness por defecto es débil y ahí sí vale la pena evolucionar el tuyo, usando sesiones excelentes como referencia.

Orienta el esfuerzo: contexto portátil para todos, harness propio solo donde marca la diferencia.

OmniAgent, súper harness, harness para modelo local, dsh-sandbox.

README.md es el onboarding para personas: cómo ejecutar, cómo probar, estructura. AGENTS.md es corto, directo al agente, y empieza con el orden de lectura de los demás archivos.

Mezclar los dos hace que el agente lea un tutorial y el humano lea reglas de máquina. Separarlos deja a cada uno ligero.

Público de cada archivo, orden de lectura, instrucción concisa.

overview.md guarda qué es el proyecto, hechos verificados con fuente y fecha, preferencias e hipótesis. current-state.md dice qué funciona y qué está pendiente hoy.

Una sesión nueva responde "¿cuál es el objetivo?" leyendo esos dos archivos, sin escarbar en el historial.

Overview, estado actual, hecho fechado, briefing de partida.

sources.md lista cada fuente con tipo (archivo local, export fechado, conexión viva), fecha, alcance y regla de actualización. decisions/ tiene un archivo por decisión aceptada, con contexto y consecuencias.

Cuando dos versiones de una información chocan, la fuente y la decisión aceptada resuelven. Sin eso, gana el archivo más reciente, que no siempre está correcto.

Fuente, snapshot fechado, decisión aceptada, provenance.

El archivo del trabajo actual: objetivo, quién es el dueño, criterio de listo verificable, próxima acción concreta y bloqueos.

El agente pasa a entender no solo el historial, sino lo que se está haciendo ahora y cuándo puede decir "listo".

Tarea actual, dueño, criterio de aceptación, próxima acción.

El handoff más reciente, siempre en la misma ruta: proyecto y alcance, objetivo, estado aceptado, archivos modificados, checks ejecutados con resultado, preguntas abiertas y próxima acción exacta.

Una ruta fija ("latest") es lo que le permite a Codex retomar lo que Claude dejó, y viceversa.

latest.md, estado aceptado, checks con evidencia, próxima acción.

Las skills reutilizables van en .agents/skills/ (donde Codex las busca) y los comandos comunes en scripts/. Pero context/, tasks/ y handoffs/ son convención tuya: ningún runtime los carga por sí solo. El AGENTS.md tiene que ordenar leerlos.

Una estructura bonita que el agente ignora no vale nada. El orden de lectura explícito es lo que la hace real.

Convención vs auto-load, .agents/skills, scripts reproducibles.

Hecho es lo que fue verificado (la versión de Codex es 0.154). Preferencia es gusto del dueño (autor de commit inematds). Hipótesis es lo que se supone sin comprobar. Decisión es lo que se aceptó después de discutir.

Una hipótesis anotada como hecho se convierte en una regla equivocada que el agente sigue con confianza. Separar los tipos corta ese error en el origen.

Hecho, preferencia, hipótesis, decisión.

Toda nota durable lleva un ID, el alcance (proyecto, máquina, cliente), la fuente, la fecha de observación, el estado (borrador, aceptado, revocado) y cuándo revisarla o expirarla.

Responde la pregunta clásica: "¿cuál de las varias versiones de esta información es la correcta?".

Metadatos de la nota, fecha de observación, expiración, dueño por tipo.

Provenance es el origen rastreable de una información. En un conflicto, gana la fuente más confiable y la decisión aceptada, no el archivo más nuevo. openpcbotv3 lo hace marcando la versión antigua con superseded_by en vez de borrarla.

El timestamp premia a quien escribió último, incluso a un agente que adivinó. La provenance premia a quien verificó.

Provenance, conflicto, superseded_by, nunca borrar, solo ocultar.

La memoria nativa (869 archivos de Claude, conversaciones) es materia prima. Promover es elegir un hecho verificado y escribirlo en overview.md con fuente y fecha, de forma deliberada. Nunca copiar en masa.

Copiar todo arrastra hipótesis y ruido. Promover hecho por hecho mantiene el overview corto y confiable.

Promoción deliberada, materia prima vs fuente, vault curado.

Cualquier índice de búsqueda, caché o base vectorial debe poder reconstruirse a partir de los registros que tú posees. La fuente de la verdad es el Markdown; el índice es derivado.

Si el índice es la única copia, tienes lock-in de nuevo, solo que en una herramienta de búsqueda.

Fuente vs derivado, rebuild, snapshot curado antes del retrieval.

Las claves de API, el estado nativo crudo y el material personal o de cliente no entran en el repositorio portátil. Las keys quedan en .env y se referencian; la evidencia bruta queda separada de lo que fue promovido.

En esta máquina hay 269 archivos de secretos en ~/projetos. Un workspace portátil que los arrastra consigo es una fuga esperando ocurrir.

Secreto referenciado, evidencia bruta separada, alcance de cliente.

Los dos mega-prompts tienen un campo MODE. En audit, el agente inspecciona, clasifica y devuelve un plan con árbol propuesto, mapeos y criterios de aceptación, sin tocar ningún archivo. Solo después vuelves a ejecutar con MODE: implement y un alcance acordado.

Una migración es difícil de revertir. Leer el plan antes cuesta minutos; deshacer una copia masiva cuesta días.

MODE audit/implement, plan revisable, cambios reversibles, alcance declarado.

"Actúa como mi ingeniero de migración": confirma alcance y evidencia, inventaría el sistema (instrucciones, skills, comandos, hooks, plugins, MCP, memoria), revisa el destino antes de convertir, produce el plan en una tabla, implementa solo en implement, separa la lógica portátil de la integración nativa, verifica la continuidad y entrega con handoff.

Es la hoja de ruta completa de una migración honesta, incluyendo lo que no se transfiere sin cambios.

WORKSPACE_ROOT, SOURCE_ROOTS, TARGETS, REPRESENTATIVE_TASK, KEEP_UNCHANGED.

"Actúa como mi arquitecto de workspace": inspecciona antes de diseñar, propone el núcleo portátil más pequeño, implementa README/AGENTS/context/tasks/handoffs, define los dueños de la información, agrega adaptadores nativos pequeños, controla la distribución de contexto, prueba la portabilidad y entrega. Tiene add-ons para uso personal, de cliente o mixto.

Sirve tanto para adaptar un proyecto existente como para nacer portátil desde el primer commit.

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

Cada activo del setup recibe una de cuatro etiquetas: reutilizable tal cual, necesita adaptador, solo existe en el runtime de origen, o no resuelto. En esta máquina: 72 skills reutilizables, 15 con adaptador, 2 nativas, 1 sin SKILL.md.

Convierte "migrar todo" en una lista con destino, rollback y prueba por ítem.

Matriz origen → destino, clasificación, rollback, criterio de aceptación por activo.

Todo check tiene uno de tres estados. "No ejecutado" es una respuesta válida y obligatoria cuando faltó acceso o tiempo; viene con los pasos para reproducirlo. El propio PDF admite que los autores no probaron ninguna migración real.

Un informe que distingue los tres estados es lo que separa una migración hecha de una migración declarada.

Pasó / falló / no ejecutado, reproducción, informe honesto.

Un árbol generado, un import exitoso o una configuración con sintaxis válida no prueban un comportamiento equivalente. La prueba es una sesión nueva que responde: objetivo actual, una regla con su archivo de origen, última decisión, próxima acción y conflictos.

Es la prueba de continuidad que la Ruta 2 ejecuta de verdad, en Claude y en Codex. ¿Lo encontró? ¿Lo leyó? ¿Lo entendió? ¿Lo usó?

Readback en sesión nueva, las 5 preguntas, prueba de uso.