Migrar desde Claude Code: un cambio de herramienta conservando su flujo de trabajo

📚 Navegación de la serie: El artículo anterior 〔31 Técnicas avanzadas y optimización de velocidad〕 detalló pautas para acelerar la velocidad de desarrollo y reducir la necesidad de reescritura de código en Codex. Este artículo está dirigido específicamente a usuarios con experiencia previa en Claude Code: qué aspectos de su modelo mental pueden transferirse directamente, qué conceptos cambian de nombre y qué características son exclusivas de Codex. El siguiente artículo 〔33 Pautas de uso en Windows〕 abordará aspectos de configuración específicos para este sistema operativo.

Comencemos recreando una conversación real. El mes pasado, un colega que utilizaba habitualmente Claude Code instaló Codex y me planteó una serie de dudas:

Él: "¿Dónde coloco el archivo CLAUDE.md de Codex? Tengo uno en la raíz de mi proyecto pero parece que lo ignora." Yo: "Codex no reconoce el nombre CLAUDE.md. Utiliza AGENTS.md en su lugar. Puedes migrar el contenido casi sin modificaciones." Él: "¿Y qué ocurre con las reglas de permisos allow / deny de mi archivo settings.json?" Yo: "También debes actualizarlas. Codex utiliza el archivo TOML ~/.codex/config.toml. Su modelo de seguridad se basa en los conceptos de 'sandbox' y 'aprobación', no en la directiva allowedTools." Él: "¿Cómo ejecuto scripts sin interfaz interactiva como con claude -p? ¿Y se mantienen comandos como /compact o /clear?" Yo: "El equivalente a claude -p es codex exec. La mayoría de comandos de consola se mantienen y se invocan de la misma forma. Prácticamente toda tu memoria muscular es aplicable."

La respuesta le tranquilizó al comprobar que no debía aprender una herramienta nueva desde cero, sino únicamente adaptar los nombres de los conceptos al nuevo entorno. Este artículo detalla las equivalencias de términos, las pautas de configuración y cómo reestructurar un archivo CLAUDE.md a AGENTS.md.

Al terminar de leer este artículo, obtendrás:

Tranquilidad al saber que puede transferir el 90% de sus pautas de trabajo de Claude Code a Codex con un bajo costo de transición.
Una tabla de equivalencia conceptual detallada entre Claude Code y Codex.
Pautas para evitar errores comunes en la migración de archivos de reglas del proyecto, archivos de configuración de preferencias y modelos de seguridad.
Identificación de las diferencias funcionales entre ambos entornos.
Un ejercicio paso a paso para migrar un archivo CLAUDE.md a AGENTS.md.

⚠️ Los comandos, propiedades de configuración y comportamientos se contrastan con la documentación oficial de Codex. Los modelos y parámetros son ilustrativos y pueden variar con el tiempo. Ambas herramientas se encuentran en desarrollo constante; la guía aborda la equivalencia de conceptos generales, no la compatibilidad exacta de sintaxis.

01 Transferencia de pautas de trabajo y modelo mental

Migrar de Claude Code a Codex no consiste en aprender un flujo de trabajo nuevo, sino en adaptar la sintaxis de las directivas a una nueva interfaz.

Ambas utilidades comparten la misma arquitectura de base: se ejecutan como herramientas de consola (CLI) para desarrollo, implementan un flujo de toma de decisiones autónomo (agentic loop) y operan directamente sobre el sistema de archivos de su repositorio local.

Analogía: Cambiar de marca de teléfono móvil con el mismo sistema operativo. El proceso no es equivalente a migrar de Android a iOS. Las acciones comunes (realizar llamadas, enviar mensajes, abrir aplicaciones o gestos de navegación) se mantienen; únicamente varían la ubicación de los menús de configuración, la estética de los iconos o el nombre de las aplicaciones del sistema. Migrar a Codex representa este tipo de transición.

Los siguientes aspectos se mantienen idénticos entre ambos entornos:

El ciclo de ejecución de tres fases: el modelo analiza el requerimiento, traza un plan de acción, aplica los cambios en el código y valida los resultados de forma iterativa.
La práctica de análisis previo: la recomendación de ordenar al agente leer el código del proyecto y proponer un diseño técnico antes de autorizar la escritura de los archivos.
La definición de reglas de proyecto: el uso de archivos de documentación locales para instruir al agente sobre convenciones de código y límites de diseño (con variaciones de carga).
El control mediante comandos de consola: el uso del prefijo / para cambiar de modelo, limpiar el contexto o verificar el estado de la sesión.

Al migrar mis proyectos FastAPI de Claude Code a Codex, comprobé que las directivas cotidianas como /status o /model operaban de la misma forma, requiriendo únicamente ajustar la sintaxis de los archivos de configuración y los nombres de las directivas de seguridad.

💡 Resumen en una frase: Codex y Claude Code comparten la misma arquitectura de CLI de desarrollo con agentes autónomos; sus pautas de diseño y uso del chat interactivo son transferibles directamente.

02 Tabla de equivalencias conceptuales

Se detallan las correspondencias de conceptos y rutas entre ambos entornos:

Concepto en Claude Code	Equivalente en Codex	Tipo de cambio	Puntos clave de diferencia
Reglas de proyecto: `CLAUDE.md`	`AGENTS.md`	Nombre de archivo	Misma función; cambian las prioridades y reglas de herencia (ver sección 03).
Preferencias: `~/.claude/settings.json`	`~/.codex/config.toml`	Formato de archivo	Migración de formato JSON a TOML; cambian las propiedades (ver sección 04).
Modelo de seguridad y permisos	Sandbox (`sandbox`) + Aprobación (`approval`)	Filosofía de control	Transición de permisos individuales por herramienta a límites de área y confirmación (ver sección 05).
Modo desatendido: `claude -p`	Ejecución no interactiva: `codex exec`	Nombre de comando	Ambos ejecutan una sola instrucción en consola y finalizan.
Niveles de `CLAUDE.md`	Niveles de `AGENTS.md`	Equivalente	Carga por proximidad; Codex introduce el archivo `AGENTS.override.md`.
Protocolo de herramientas MCP	Protocolo de herramientas MCP	Equivalente	Protocolo común; varía la sintaxis de registro en la configuración.
Agentes secundarios (Subagents)	Subagentes (Subagents)	Equivalente	Disponibles en ambos; varía la ubicación de su configuración.
Habilidades de agente (Skills)	Skills	Equivalente	Estructura común; varía la organización de los subdirectorios locales.
Comandos de consola (`/model`, `/compact`)	Comandos de consola (`/model`, `/compact`)	Equivalente	Coincidencia en la mayoría de nombres; varían atajos concretos (ver sección 06).
Memoria de sesiones (Memory)	Memories / Chronicle	Variación de comportamiento	En Codex la memoria se encuentra desactivada por defecto y tiene límites geográficos.
Modelos: Opus / Sonnet / Haiku	Modelos GPT-5.x	Variación de versiones	Equivalencias: insignia `gpt-5.5` y ligero `gpt-5.4-mini` (ver artículo 30).

La pauta general para el desarrollador consiste en:

Los conceptos de diseño de agentes (MCP, Skills, reglas de proyecto) se mantienen; debiendo reescribir la sintaxis de las variables de configuración y comprender la lógica de control del sandbox de seguridad.

Al seleccionar modelos, reemplace Opus por gpt-5.5 para tareas complejas y Haiku por gpt-5.4-mini para ejecuciones ligeras o procesamiento por lotes. Note que gpt-5.4-mini es el modelo optimizado para bajo costo, siendo gpt-5.5 la versión insignia.

💡 Resumen en una frase: Los flujos de trabajo son conceptualmente equivalentes; los cambios principales se concentran en las pautas de control del sandbox, la sintaxis del archivo de configuración TOML y la nomenclatura de las reglas del proyecto (AGENTS.md).

03 Reglas de proyecto: de `CLAUDE.md` a `AGENTS.md`

Esta es la primera actualización requerida al migrar un repositorio: Codex no lee archivos con el nombre CLAUDE.md. Las reglas e instrucciones del proyecto deben definirse en un archivo llamado AGENTS.md.

El contenido del archivo es compatible directamente: puede estructurar las secciones de descripción del proyecto, tecnologías implementadas, comandos comunes de ejecución de pruebas y convenciones de formato de la misma forma que en Claude Code. Las pautas de redacción del artículo [11] (evitar información obsoleta o redundante que el modelo pueda deducir leyendo el código) son plenamente válidas.

Analogía: Actualizar el formato de un documento técnico para un nuevo departamento. Al migrar un manual de operaciones de una división a otra, el contenido técnico (parámetros de la máquina, límites de presión) se conserva, pero debe adaptar el documento a la plantilla de logotipos y nomenclatura requerida por la nueva división. El archivo AGENTS.md representa esta plantilla.

Diferencias en las reglas de carga e implementación:

Característica	Claude Code (`CLAUDE.md`)	Codex (`AGENTS.md`)
Reglas de usuario globales	`~/.claude/CLAUDE.md`	`~/.codex/AGENTS.md`
Reglas de raíz de proyecto	`./CLAUDE.md` o `./.claude/CLAUDE.md`	`./AGENTS.md`
Reglas en subcarpetas	Se leen de forma ad-hoc al acceder	Se leen secuencialmente desde la raíz hasta el directorio activo
Modificador local	Archivo `CLAUDE.local.md` (no rastreado)	Archivo `AGENTS.override.md`
Límite de tamaño	Sugerido por debajo de 200 líneas	Límite por bytes (32 KiB combinados en `project_doc_max_bytes`)

Aspectos clave a considerar al migrar las reglas:

1. El mecanismo de anulación (override) de reglas. Claude Code utiliza CLAUDE.local.md para añadir preferencias locales del desarrollador que no deben subirse al repositorio. Codex implementa AGENTS.override.md el cual, en el directorio donde se ubique, anula la lectura del archivo AGENTS.md del mismo nivel.

2. Restricción por tamaño en bytes. Mientras que en Claude Code se aconseja no superar las 200 líneas por legibilidad, Codex impone una restricción de tamaño en bytes (32 KiB combinados para todos los archivos leídos). Si el tamaño consolidado supera este límite, la información puede ser truncada. Se recomienda limpiar las secciones de contexto histórico del archivo durante la migración para optimizar el tamaño.

3. Consolidación de reglas jerárquicas. Las reglas de Codex se consolidan leyendo desde el archivo global del usuario en el home, pasando por el de la raíz del proyecto y descendiendo por las carpetas hasta el directorio de trabajo activo, aplicando un principio de proximidad donde las reglas de subcarpetas tienen prioridad ante conflictos de directivas.

💡 Resumen en una frase: Migre sus reglas renombrando CLAUDE.md a AGENTS.md, elimine información de contexto histórico para no superar el límite de bytes consolidado y use AGENTS.override.md si requiere omitir las reglas de un directorio específico.

04 Archivos de preferencias: de JSON a TOML

El archivo de configuración de preferencias de usuario cambia de formato:

Claude Code: utiliza ~/.claude/settings.json en formato JSON.
Codex: utiliza ~/.codex/config.toml en formato TOML.

Analogía: Traducir un archivo de traducción de formatos. Los parámetros representados en el archivo (cuál es el modelo predeterminado, qué puertos utilizar) son equivalentes; sin embargo, debe reescribir la estructura para adaptarla a la sintaxis TOML, la cual prescinde de llaves o comas y organiza las secciones mediante encabezados de grupo.

Comparación de sintaxis para configuraciones comunes:

Configuración	Claude Code (`settings.json` - JSON)	Codex (`config.toml` - TOML)
Modelo de lenguaje	`"model": "claude-3-5-sonnet"`	`model = "gpt-5.5"`
Límite de permisos	`"permissions": { "deny": [...] }`	`sandbox_mode = "read-only"`
Agrupación de propiedades	Llaves de objeto `{}`	Encabezados de grupo `[sección]`
Asignación de variables	Dos puntos `:`	Signo de igualdad `=`

Ejemplo en Claude Code (JSON):

json

{
  "model": "claude-3-5-sonnet"
}

Equivalente en Codex (TOML):

toml

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

Precauciones al escribir el archivo TOML: no incluya comas al final de las líneas y use el signo de igualdad = para la asignación de variables. Incluir comas (un hábito común al escribir JSON) provocará errores de análisis sintáctico al iniciar Codex.

Consulte la estructura y variables del archivo de preferencias en el artículo [18 config.toml 配置详解], traduciendo únicamente los parámetros activos de su configuración anterior a la sintaxis TOML correspondiente.

💡 Resumen en una frase: Traduzca la configuración de settings.json a la sintaxis TOML en config.toml, utilizando asignaciones con =, omitiendo las comas al final de las líneas y agrupando las propiedades mediante declaraciones de [sección].

05 Transición del modelo de seguridad y permisos

Esta sección aborda el cambio de lógica en la gestión de permisos del sistema de archivos.

El modelo de seguridad de Claude Code se basa en dos variables:

Niveles de permiso: escalas de autorización que van desde el nivel restrictivo default hasta el nivel permisivo bypassPermissions.
Reglas individuales por herramienta: declaración en el JSON de listas de herramientas o comandos del sistema autorizados (allow / ask / deny), bloqueando por ejemplo comandos específicos como rm.

Codex simplifica este control estructurándolo en dos parámetros independientes:

Sandbox (sandbox): define la frontera física de lectura/escritura (read-only, workspace-write, danger-full-access).
Aprobación (approval): define si el sistema solicita confirmación visual antes de ejecutar comandos (untrusted, on-request, never).

Analogía: Pasar de una política de control de firmas individuales a una política de asignación de zonas de acceso. Claude Code autoriza o deniega la firma para cada factura individual (cada comando o herramienta); Codex delimita el presupuesto de la oficina (el sandbox de escritura) y determina si el analista requiere reportar los gastos en tiempo real o si puede operar de forma autónoma hasta agotar el límite (la política de aprobación).

Equivalencias en la configuración de seguridad:

Comportamiento deseado	Configuración en Claude Code	Configuración en Codex
Bloquear la escritura en el sistema; solo lectura	Modo `default` en solo lectura	Sandbox `read-only`
Permitir cambios en el proyecto; restringir el exterior	Modos de aceptación de cambios	Sandbox `workspace-write` + Aprobación `on-request`
Ejecución desatendida sin confirmaciones visuales	Nivel `bypassPermissions`	Sandbox `danger-full-access` + Aprobación `never` (o uso del modificador `--yolo`)
Restringir comandos de consola específicos	Declaración de denegación en permisos	Reglas experimentales de Starlark usando `prefix_rule()` para interceptar comandos
Modificar el nivel de seguridad activo	Atajo `Shift+Tab` en la sesión	Comando `/permissions` en el chat o parámetros de arranque

Diferencias conceptuales clave:

1. Desacoplamiento de permisos y notificaciones. Puede configurar el nivel de sandbox de solo lectura (read-only) con una política de no intervención (never) para permitir a Codex analizar y auditar el código local de forma silenciosa sin interrumpir su sesión con alertas de confirmación.

2. Ajuste automático según la presencia de Git. Al arrancar, Codex evalúa el directorio: si cuenta con control de versiones Git, asume el sandbox workspace-write con aprobación on-request como perfil seguro; si el directorio no tiene Git, restringe el sandbox a read-only para prevenir modificaciones accidentales de archivos sin historial.

3. Restricciones del sandbox en el proyecto. En el nivel workspace-write, el acceso a la red externa y la modificación de la carpeta .git están bloqueados por defecto; si el script requiere llamadas de red, debe habilitar explícitamente network_access = true en su configuración.

Consulte las opciones detalladas de seguridad en el artículo [15], adaptando las reglas de acceso bajo el esquema de sandbox de Codex.

💡 Resumen en una frase: La seguridad en Codex se gestiona mediante el nivel del sandbox (frontera de cambios) y la política de aprobación (frecuencia de notificaciones); abandonando las listas de comandos individuales en favor de límites globales de directorio.

06 Comandos de consola de uso común

La interfaz de chat de Codex mantiene los comandos de consola habituales de Claude Code, facilitando la transición:

Acción	Comando en Claude Code	Comando en Codex	Coincidencia
Cambiar el modelo activo	`/model`	`/model`	Coincidente
Compactar el contexto	`/compact`	`/compact`	Coincidente
Limpiar la pantalla y sesión	`/clear`	`/clear`	Coincidente
Consultar estado y configuración	`/status` (o `/config`)	`/status`	Coincidente
Inicializar reglas en la carpeta	`/init`	`/init`	Coincidente (Genera `AGENTS.md`)
Consultar diferencias (diff)	`/diff`	`/diff`	Coincidente
Analizar consistencia de cambios	`/review`	`/review`	Coincidente
Ajustar niveles de seguridad	Atajo `Shift+Tab`	Comando `/permissions`	Variación de atajo

La diferencia principal radica en la gestión de permisos en el chat: Codex implementa el comando /permissions para desplegar el selector de niveles en pantalla, en lugar del atajo de teclado Shift+Tab de Claude Code. Asimismo, Codex diferencia el comando /clear (limpiar pantalla y sesión) del comando /new (abrir un nuevo hilo manteniendo la pantalla anterior).

07 Consideraciones sobre el comportamiento del sistema

Preste atención a las siguientes variaciones en las características del entorno:

1. Estado por defecto del sistema de memoria. En Claude Code, la memoria de contexto se encuentra activa de forma predeterminada, asociándose a los directorios de trabajo. En Codex, las Memories se encuentran desactivadas por defecto y su disponibilidad está vinculada a directrices de servicio y políticas regionales de datos. Se aconseja registrar las pautas persistentes del proyecto en AGENTS.md para asegurar su lectura constante en cada sesión (ver artículo [19]).

2. Funcionalidades exclusivas de Codex. Codex incorpora herramientas no disponibles en Claude Code:

AGENTS.override.md: archivo de anulación de reglas locales para subdirectorios.
Chronicle: herramienta de recopilación de contexto basada en la actividad de la pantalla (en fases de prueba y sujeta a disponibilidad regional).
Asignación automática del sandbox: evaluación en tiempo de ejecución del estado de Git para restringir los permisos de escritura en carpetas sin control de versiones.

3. Sintaxis de control de comandos en reglas. Si requiere bloquear la ejecución de herramientas específicas, Codex utiliza un sistema de reglas basado en archivos de código Starlark (con la función prefix_rule), en lugar de declaraciones de cadenas de texto en arreglos JSON.

08 Práctica: Migrar un archivo `CLAUDE.md` a `AGENTS.md`

Realizaremos el proceso práctico de migrar una plantilla de reglas de proyecto de Claude Code a Codex en un entorno de pruebas local.

Requisitos: contar con Codex instalado y operar en una terminal de comandos.

Paso 1: Crear un proyecto con un archivo CLAUDE.md de prueba

Inicialice un directorio de pruebas y cree el archivo de reglas de Claude Code:

bash

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

Cree el archivo CLAUDE.md con la siguiente estructura habitual (incluyendo una sección de contexto histórico que depuraremos):

# Especificaciones del proyecto migrate-demo

Este proyecto implementa una API de gestión de inventarios usando FastAPI. Fue diseñado originalmente por el equipo técnico en 2024 para reemplazar la base de código obsoleta en PHP; el proceso de migración de datos tomó tres meses y requirió validaciones de consistencia de esquemas... [Contexto histórico extenso no relevante para la codificación].

## Tecnologías

- Python 3.11 / SQLite / pytest

## Comandos

- `pytest` — Ejecutar pruebas unitarias
- `black .` — Formatear archivos de código

## Pautas de estilo

- Tipado estricto en firmas de funciones
- Formato de strings con comillas simples

## Restricciones

- No realizar commits en la rama main directamente
- No utilizar librerías de ORM distintas a SQLAlchemy

Paso 2: Desarrollar el archivo de reglas AGENTS.md

Cree el archivo AGENTS.md en el mismo directorio. Transfiera el contenido técnico del archivo anterior, eliminando la sección de contexto histórico de la introducción:

# migrate-demo — API de gestión de inventarios con FastAPI

## Tecnologías

- Python 3.11 / SQLite / pytest

## Comandos

- `pytest` — Ejecutar pruebas unitarias
- `black .` — Formatear archivos de código

## Pautas de estilo

- Tipado estricto en firmas de funciones
- Formato de strings con comillas simples

## Restricciones

- No realizar commits en la rama main directamente
- No utilizar librerías de ORM distintas a SQLAlchemy

Resultado esperado: el directorio contiene el archivo AGENTS.md con la información de desarrollo limpia y sin datos de contexto histórico redundantes, reduciendo el consumo de bytes en la ventana de contexto.

Paso 3: Validar la lectura de las nuevas reglas en Codex

Ejecute la siguiente consulta en su terminal de comandos para verificar que Codex procesa el nuevo archivo de reglas (usamos --ask-for-approval never para omitir diálogos de confirmación operativos):

bash

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

Resultado esperado: la terminal inicia a Codex y el modelo devuelve la síntesis de las tecnologías, comandos, pautas y restricciones descritas en su archivo AGENTS.md. La correcta síntesis confirma que Codex lee e incorpora las directivas de AGENTS.md en su contexto.

Paso 4: Conservar compatibilidad durante la transición (Opcional)

Si comparte el repositorio con desarrolladores que aún utilizan Claude Code y requiere que Codex lea el archivo CLAUDE.md existente como alternativa, declare la propiedad de fallback en su archivo global ~/.codex/config.toml:

toml

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

Con esta propiedad, si el directorio no cuenta con AGENTS.md, Codex leerá CLAUDE.md como origen de reglas de proyecto secundario.

💡 Resumen en una frase: La práctica de migración consiste en: crear un archivo CLAUDE.md de prueba → reescribirlo como AGENTS.md depurando el contexto histórico de la introducción → comprobar la lectura sintáctica en la terminal de Codex → configurar fallback en config.toml si requiere mantener compatibilidad con ambos entornos.

Resumen

Este artículo ha detallado el proceso de transición de Claude Code al entorno de Codex:

心智模型 transferible: los conceptos fundamentales de desarrollo asistido mediante agentes autónomos y ciclos de iteración se mantienen sin cambios.
Reglas del proyecto: actualice sus archivos de reglas renombrando CLAUDE.md a AGENTS.md, depurando el contenido para cumplir con el límite de bytes.
Configuración de preferencias: reescriba su archivo de configuración JSON a TOML en ~/.codex/config.toml, cuidando los detalles de sintaxis del formato.
Gestión de la seguridad: adopte la lógica de control basada en niveles de sandbox (privilegios de directorio) y políticas de aprobación (frecuencia de notificaciones), simplificando la gestión de permisos locales.
Comandos de consola: se conservan los comandos comunes de chat, reemplazando el atajo de permisos Shift+Tab por el comando /permissions.

La equivalencia general de conceptos facilita la transición al entorno de Codex, permitiéndole conservar sus flujos de trabajo habituales de desarrollo.

El siguiente artículo 33 · Pautas de uso en Windows: analizaremos las pautas de instalación, la gestión de rutas y las limitaciones del sandbox de Codex específicas para entornos de desarrollo bajo el sistema operativo Windows.

Migrar desde Claude Code: un cambio de herramienta conservando su flujo de trabajo ​

01 Transferencia de pautas de trabajo y modelo mental ​

02 Tabla de equivalencias conceptuales ​

03 Reglas de proyecto: de CLAUDE.md a AGENTS.md ​

04 Archivos de preferencias: de JSON a TOML ​

05 Transición del modelo de seguridad y permisos ​

06 Comandos de consola de uso común ​

07 Consideraciones sobre el comportamiento del sistema ​

08 Práctica: Migrar un archivo CLAUDE.md a AGENTS.md ​

Resumen ​

Lecturas recomendadas ​