Cómo migrar de Kiro a Codex sin perder el contexto (2026)

El contenido se transfiere. La estructura no. El direccionamiento del espacio de trabajo de Kiro vive en .kiro/steering/ y el direccionamiento global en ~/.kiro/steering/, ambos como archivos .md planos. Codex lee archivos AGENTS.md. La prosa se mueve sin modificaciones; la pregunta es dónde aterriza.

Un archivo por directorio es la restricción que gobierna todo. El descubrimiento de Codex es un recorrido: "Comenzando en la raíz del proyecto (normalmente la raíz de Git), Codex desciende hasta tu directorio de trabajo actual... En cada directorio a lo largo de la ruta, busca AGENTS.override.md, luego AGENTS.md, y después cualquier nombre alternativo en project_doc_fallback_filenames. Codex incluye como máximo un archivo por directorio".

Seis archivos de direccionamiento en una sola ruta se convierten en máximo un archivo. O bien los concatenas en un único AGENTS.md en la raíz o los distribuyes en los directorios cuyo código gobiernan — y la segunda opción es para la que está diseñado el modelo de Codex.

El direccionamiento global se mapea, con una regla de primer archivo. En el directorio de inicio de Codex, "Codex lee AGENTS.override.md si existe. De lo contrario, Codex lee AGENTS.md. Codex utiliza solo el primer archivo no vacío en este nivel". Así que tu directorio ~/.kiro/steering/ de convenciones personales se convierte exactamente en un archivo en ~/.codex/AGENTS.md. El archivo de anulación (override) es útil para un cambio temporal: "Usa ~/.codex/AGENTS.override.md cuando necesites una anulación global temporal sin eliminar el archivo base".

El orden de fusión está establecido, y es el inverso de lo que algunos asumen. "Codex concatena archivos desde la raíz hacia abajo, uniéndolos con líneas en blanco. Los archivos más cercanos a tu directorio actual anulan las directrices anteriores porque aparecen más tarde en el prompt combinado". Lo último gana. Eso se mapea limpiamente con el instinto de Kiro de que lo específico supera a lo general, pero se logra por la posición en un prompt concatenado en lugar de por una regla de precedencia.

Ninguno de los cuatro modos de inclusión de Kiro tiene un equivalente en Codex. Esta es la pérdida sustancial, por lo que vale la pena enumerar a qué estás renunciando.

inclusion: always es el valor predeterminado y se mapea directamente — esos archivos eran incondicionales en Kiro y siguen siendo incondicionales en Codex.

inclusion: fileMatch con un fileMatchPattern carga un archivo "solo cuando se trabaja con archivos que coinciden con el patrón especificado", y la documentación es clara sobre el porqué: "Esto mantiene el contexto relevante y reduce el ruido al cargar directrices especializadas solo cuando es necesario". Codex no tiene carga activada por patrones. Un archivo fileMatch pasa a estar siempre cargado o no cargado.

Los archivos inclusion: manual están "disponibles bajo demanda al hacer referencia a ellos con #steering-file-name en tus mensajes de chat", y también "aparecen como comandos de barra diagonal (slash commands)". Codex no tiene adjuntos de instrucciones bajo demanda.

inclusion: auto, con un nombre y una descripción, es el modo basado en relevancia. También está ausente.

Kiro es directo al afirmar que estos modos existen por una razón: ayudan a "optimizar el rendimiento y garantizar que el contexto relevante esté disponible cuando se necesite". Eliminarlos significa que todo lo que conserves se pagará en cada ejecución.

AGENTS.md ya se comporta como Codex, incluso dentro de Kiro. Kiro admite el estándar, con una diferencia documentada: "Los archivos AGENTS.md no admiten modos de inclusión y siempre se incluyen". Si parte de tu configuración de Kiro ya está en AGENTS.md, esa parte es una copia directa y ya has estado viviendo con la carga incondicional para ella.

El límite de bytes es el modo de fallo que nadie espera. "Codex omite los archivos vacíos y deja de agregar archivos una vez que el tamaño combinado alcanza el límite definido por project_doc_max_bytes (32 KiB por defecto)". Se detiene. No advierte. Los remedios documentados están disponibles: "Aumenta el límite o divide las instrucciones en directorios anidados cuando alcances el límite".

Ahora combina ambos hechos. Los usuarios de Kiro suelen tener más texto de direccionamiento total que una configuración comparable de Codex, precisamente porque los modos de inclusión hacían que fuera barato mantener mucho de él. Aplana eso en archivos incondicionales y los 32 KiB llegarán antes de lo que imaginas. Esta es la misma clase de deficiencia silenciosa detrás de why Codex skips your AGENTS.md rules.

Las especificaciones (specs) no se transfieren. Las especificaciones de Kiro son artefactos estructurados — cada especificación genera requirements.md, design.md y tasks.md bajo .kiro/specs/<name>/, realizando un seguimiento de las historias de usuario, la arquitectura y las tareas de implementación discretas. Codex no tiene un sistema de especificaciones para recibirlas. Los archivos son markdown y permanecen en el repositorio si los deseas, pero dejan de ser artefactos activos sobre los cuales un agente realiza un seguimiento del progreso.

El direccionamiento en la nube tiene un límite que vale la pena conocer. Si usaste Kiro en la web, ten en cuenta que "'Global steering' se refiere a tu directorio local ~/.kiro/steering/, que el sandbox de la nube no puede leer", razón por la cual Kiro proporciona Configuration Sync para sesiones en la nube. El archivo global de Codex vive en la máquina que ejecuta Codex, por lo que se aplica la misma clase de cuestión dondequiera que lo ejecutes.

Paso 1: Reestructurar por ubicación, no por tema

Resiste el instinto de concatenar todo en un único AGENTS.md en la raíz. Ese es el camino más rápido y te lleva directo al límite de bytes.

En su lugar, clasifica tus archivos de direccionamiento según el lugar donde se aplica su guía, luego coloca cada uno en el directorio que gobierna. Un archivo de direccionamiento cuyo fileMatchPattern era "app/api/**/*" se convierte en app/api/AGENTS.md. Uno limitado a "src/components/**/*" se convierte en src/components/AGENTS.md. El propio consejo de Codex coincide: "Codex deja de buscar una vez que llega a tu directorio actual, así que coloca las anulaciones lo más cerca posible del trabajo especializado".

Esto recupera una parte significativa de lo que hacía fileMatch. No todo — Codex se activa según tu directorio de trabajo en lugar de los archivos que lee el agente —, pero un desarrollador que trabaja en app/api obtiene la guía de la API y no la de los componentes, que era el objetivo.

Para contenido genuinamente universal, mantén un único AGENTS.md en la raíz y hazlo corto. Tu pila tecnológica, tus convenciones de código, tus comandos de compilación y prueba. Mueve los archivos inclusion: always aquí y nada más.

Cuando un directorio anidado necesite reemplazar en lugar de extender la guía superior, usa AGENTS.override.md en ese directorio — Codex lo busca primero y lo toma en lugar de un AGENTS.md hermano.

Dos notas prácticas. Si un repositorio ya utiliza un nombre de archivo diferente, regístralo en lugar de renombrarlo: project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] en ~/.codex/config.toml hace que Codex los trate como archivos de instrucciones, y la documentación advierte que "Los nombres de archivo que no estén en esta lista se ignoran para el descubrimiento de instrucciones". Y si tienes revisión de código de Codex en GitHub, las reglas de revisión pertenecen a una sección ## Code Review Rules "en el AGENTS.md más cercano al código que gobiernan las reglas".

Paso 2: Decide qué sucede con los archivos manual y auto, luego mide el resultado

Tus archivos inclusion: manual e inclusion: auto son los que no tienen hogar. Eran las guías de resolución de problemas, los procedimientos de migración, la "documentación con mucho contexto que solo se necesita ocasionalmente" — la propia descripción de Kiro de para qué es mejor el modo manual.

Tienes tres opciones honestas y una mala. Puedes promoverlos a incondicionales y pagar por ellos en cada ejecución. Puedes colocarlos en un directorio anidado para que se carguen solo cuando alguien trabaje allí. Puedes dejarlos como documentación ordinaria del repositorio que el agente lee cuando se le solicita, lo cual es lo más cercano a su comportamiento original. La mala opción es concatenarlos en el archivo raíz, que es como alcanzas los 32 KiB y comienzas a perder la guía que realmente necesitabas.

Luego verifica. Codex documenta exactamente cómo, y este no es un paso que debas omitir después de una reestructuración:

Ejecuta codex --ask-for-approval never "Summarize the current instructions." desde la raíz del repositorio y confirma que los archivos globales y de proyecto aparezcan en orden de precedencia. Ejecuta codex --cd subdir --ask-for-approval never "Show which instruction files are active." para confirmar que las anulaciones anidadas reemplazan a las reglas más amplias. Para una auditoría completa, "opta por un registro TUI en texto plano con codex -c log_dir=./.codex-log y revisa ./.codex-log/codex-tui.log".

Dos cosas que hacen que esto sea más barato de lo que parece. No hay caché con la que luchar: "Codex reconstruye la cadena de instrucciones en cada ejecución (y al comienzo de cada sesión de TUI), por lo que no hay caché que borrar manualmente". Y si la guía parece truncada, la documentación indica la solución directamente: aumenta project_doc_max_bytes o divídela en directorios anidados.

Mientras configuras, decide sobre la propia capa de memoria de Codex por separado. Existe y está desactivada por defecto, con su propio comportamiento que vale la pena entender en sus propios términos; turning on Codex's local memories cubre lo que conserva y cómo controlarlo.

Todo lo anterior es una reestructuración real, y te deja haciendo un intercambio que Kiro nunca te impuso: qué guía vale la pena cargar en cada ejecución.

Ese intercambio solo existe porque las instrucciones y los hechos se almacenan en el mismo lugar. Las instrucciones son cortas y de comportamiento — "ejecuta make test-payments aquí", "nunca rotes claves sin notificar a seguridad". Los hechos son largos y referenciales — por qué la API tiene versión en la ruta, qué significa un término internamente, qué servicio posee qué cola. Kiro te permitía mantener ambos en el direccionamiento porque los modos de inclusión hacían que los hechos fueran baratos. Codex te cobra por ellos en cada ejecución, frente a un techo de 32 KiB.

Divídelos y el techo dejará de importar. Los archivos AGENTS.md se mantienen pequeños y de comportamiento; los hechos viven en un almacén que el agente lee cuando surge la pregunta. MemoryLake se configura en tres pasos.

Paso 1: Crea una clave API

Inicia sesión y genera una clave API desde tu panel de control. No forma parte de la cadena de instrucciones, por lo que nada de lo que contenga cuenta para project_doc_max_bytes ni tiene que duplicarse en un directorio anidado.

Paso 2: Sube tus primeras memorias

Aquí es donde pertenecen tus archivos de direccionamiento manual y auto. Procedimientos de resolución de problemas, decisiones de arquitectura y las razones detrás de ellas, vocabulario del dominio, manuales de migración, las respuestas que sigues repitiendo en las revisiones.

Mantén el comportamiento en AGENTS.md. Los comandos, las convenciones y las reglas que deben aplicarse en cada ejecución son exactamente para lo que sirve la cadena de instrucciones.

Paso 3: Conecta tu IA y agentes

Apunta Codex al almacén. La guía ocasional pasa a estar disponible sin ser residente, tu archivo raíz se mantiene cómodamente por debajo del límite, y la guía que siempre debe aplicarse es lo suficientemente corta como para ser seguida realmente — que es el punto de why agents ignore your instruction files.

El primer cambio es que los 32 KiB dejan de ser una restricción de diseño. En este momento, cada hecho que deseas que un agente conozca compite con cada instrucción que deseas que siga, dentro de un mismo presupuesto.

El segundo es que perder los modos de inclusión cuesta menos. fileMatch es parcialmente recuperable mediante la ubicación en directorios; manual y auto no lo son, y un almacén es el análogo más cercano a "disponible bajo demanda" de lo que jamás fue un archivo cargado siempre.

El tercero es que tus especificaciones dejan de ser un callejón sin salida. Los archivos requirements.md, design.md y tasks.md de Kiro contienen decisiones reales y razonamientos reales. Codex no tiene nada que realice un seguimiento de ellos, pero las decisiones dentro de ellos son exactamente el tipo de conocimiento duradero que vale la pena mantener legible — el argumento presentado en turning project docs into AI memory.

• Distribuye, no concatenes. Codex incluye como máximo un archivo por directorio, así que coloca la guía en el directorio que gobierna.
• Mantén corto el archivo raíz. Solo el material de inclusion: always pertenece allí.
• Traduce fileMatch en ubicación. Un patrón de app/api/**/* se convierte en app/api/AGENTS.md.
• Usa AGENTS.override.md para reemplazar, no para extender. Codex lo busca antes de AGENTS.md en el mismo directorio.
• Registra nombres de archivo alternativos en lugar de renombrar. project_doc_fallback_filenames hace que Codex los lea; los nombres no listados se ignoran.
• Vigila el límite deliberadamente. La carga se detiene en project_doc_max_bytes, 32 KiB por defecto, sin previo aviso. Auméntalo o divídelo.
• Verifica con los comandos documentados. codex --ask-for-approval never "Summarize the current instructions." y la variante --cd subdir, además del registro TUI para una auditoría.
• No intentes portar especificaciones. Mantén los archivos como documentación; extrae las decisiones dentro de ellos a un lugar al que un agente realmente pueda acceder.

El modelo de instrucciones de Codex es más simple que el de Kiro a propósito: recorre el árbol, toma un archivo por directorio, concatena, se detiene en 32 KiB. La simplicidad es una característica, y significa que la migración es principalmente una cuestión de geografía — coloca cada pieza de guía donde vive el código que gobierna.

Lo que no sobrevive es la carga condicional, y esa es la parte sobre la cual planificar en lugar de descubrirla sobre la marcha. Distribuye lo que puedas, verifica con los comandos que te ofrece Codex y mueve el material de referencia ocasional a un lugar que no te cobre por él en cada ejecución.