Casos de fallo con Codex: por qué la IA rompe código y cómo validar sus cambios

git diff --stat muestra de repente 18 archivos, aunque la tarea que le diste a Codex era solo “arreglar el estado de un botón”. La CI está verde. Pero al abrir el diff aparece otra historia: coverageThreshold se redujo, un flaky test quedó en skip y se generó un helper validateEmail() que duplica el emailSchema que ya existía en el repo.

Codex no rompió el código a propósito. El límite de la tarea era demasiado amplio y el proceso de validación demasiado flojo. Aquí no se trata de discutir si la IA es fiable en abstracto, sino de construir una tabla de patrones de fallo, gates de validación, flujo de rollback y checklist de review para tratar el fallo como un hueco de proceso.

Tabla de patrones de fallo: cómo la IA rompe código

Un estudio de arXiv sobre 33k agent-authored PRs en GitHub observó que las PR no mergeadas suelen ser más grandes, tocar más archivos y fallar más a menudo la validación CI/CD del proyecto. Eso no significa que los AI agents simplemente no sean inteligentes. También importan la descomposición de tareas, los criterios de aceptación y el engagement del reviewer.

Estos son 9 patrones frecuentes, con señal y primera reacción:

Patrón	Cómo se ve	Señal	Primera reacción
Diff demasiado grande	El alcance supera por mucho la petición	git diff --stat muestra muchos más archivos que la tarea, por ejemplo 10+ archivos para un “fix de botón”	Mirar primero la file list. Separar cambios esperados de cambios fuera de scope; dividir o revertir el extra
Tests falsamente verdes	Los tests pasan pero la lógica sigue mal	El diff baja coverageThreshold, pone un flaky test en skip o relaja assertions	Revisar si cambió la configuración de tests; exigir un test de regresión que falle antes del cambio
Directorio equivocado	Cambia CI config o archivos no relacionados	Cambian .github/workflows/, Makefile o package.json scripts sin relación con la tarea	Verificar si AGENTS.md prohíbe tocar CI/config; revertir y escribir la regla
Código duplicado	Se genera un helper o util ya existente	El diff agrega un helper, pero el repo ya tiene la misma función o schema	Buscar una implementación existente; si existe, revertir el duplicado y pedir a Codex que use lo existente
PR demasiado grande	Una PR grande sin plan	El PR body solo dice “fix issue”, sin implementation plan, comandos de verificación ni rollback	Pedir PR más pequeñas, cada una revisable, verificable y reversible
CI debilitada	La CI config cambia para que pasen los checks	La CI falló, pero el patch solo cambia test/CI config y no el código de negocio	Tratarlo como blocker; revertir el cambio de CI y exigir fix en código de negocio
Bug de negocio oculto	La lógica parece correcta pero viola una regla de negocio	El diff elimina un permission check o una validation que los tests no cubren	Seguir un critical path, revisar efectos secundarios y exigir approval explícito
Untrusted input	Entrada externa usada sin validación	Codex usa datos o paths de usuario sin sanitization ni validation	Revisar input validation; si falta, exigir validation tests
Cambio grande sin plan	La implementación empezó antes del plan	Codex editó código antes de listar archivos a tocar, archivos prohibidos y comandos de verificación	Exigir /plan o goal/context/constraints/done criteria explícitos antes de implementar

Estos patrones rara vez aparecen aislados. Una PR con diff demasiado grande puede mezclar directorio equivocado, código duplicado y tests falsamente verdes. La checklist de GitHub para agent PR review también menciona CI gaming, puntos ciegos de reutilización de código, problemas ocultos de correctness y PR grandes sin plan como señales de alerta.

La primera reacción es clara: no empieces preguntando si la CI está verde. Empieza revisando el scope del diff y la granularidad de rollback.

Flujo para dividir tareas: el trabajo grande no está prohibido para Codex

Las best practices de OpenAI recomiendan planificar antes de implementar cuando una tarea es compleja o ambigua. Codex produce mejor cuando puede verificar su trabajo, y las tareas pequeñas y enfocadas son más fáciles de testear y revisar.

Pero “dividir más pequeño” no es un eslogan. La granularidad correcta es el punto en el que cada paso se puede validar y revertir por separado.

Bucle de siete pasos: de scope a update rules

Usa este bucle para cambios de Codex:

scope -> plan -> patch -> verify -> review -> merge/rollback -> update rules

Cada paso tiene preguntas y condición de retorno.

1. scope

Preguntas:

• ¿La tarea es lo bastante concreta para escribirse como goal + context + constraints + done criteria?
• ¿Cruza varios subsistemas, como auth, payment y notification?
• ¿Puede afectar configuración CI, schema de base de datos o dependencias externas?

Retorno: si cruza varios subsistemas o afecta CI/config, divídela primero en tareas separadas.

2. plan

Preguntas:

• ¿Codex listó primero los archivos esperados, los archivos o directorios que no tocará y los comandos de verificación?
• ¿El plan incluye riesgos y condiciones de salida?
• ¿El plan describe la ruta de rollback?

Retorno: si no hay plan o faltan esos elementos, pide un nuevo /plan.

3. patch

Preguntas:

• ¿git diff --stat coincide con el scope de archivos del plan?
• ¿Codex modificó archivos fuera del scope, como CI/config o archivos sin relación?
• ¿Generó código duplicado, por ejemplo un helper que ya existía?

Retorno: si el diff no coincide con el plan o toca una alerta, vuelve al paso 2.

4. verify

Preguntas:

• ¿Se agregaron tests para el core path?
• ¿El test fallaría antes del cambio?
• ¿Los CI status checks son required y no skipped?
• ¿Pasaron lint o pre-commit?

Retorno: si no se agregó un test relevante o el cambio solo hizo pasar tests debilitando configuración, vuelve al paso 3.

5. review

Preguntas:

• ¿El scope del diff coincide con la tarea?
• ¿Alguien siguió un critical path?
• ¿Un reviewer humano approved explícitamente, en vez de confiar solo en el autorreporte de la IA?
• ¿La branch protection exige required reviews, required status checks y conversation resolution?

Retorno: si el reviewer pide cambios o encuentra una alerta, vuelve al paso 3.

6. merge/rollback

Preguntas:

• ¿El cambio cumple la checklist de evidencia de la siguiente sección?
• ¿Puede revertirse de forma independiente a nivel de hunk o archivo?
• ¿El trabajo estuvo aislado en un worktree para descartar un intento fallido y llevar uno exitoso a PR?

Retorno: si falta evidencia o el cambio no es revertible de forma independiente, rollback y vuelta al paso 1.

7. update rules

Preguntas:

• ¿El fallo vino de una regla faltante en AGENTS.md, como “no tocar CI config” o “dividir tareas con más de cinco archivos”?
• ¿El área prohibida, criterio de aceptación o rollback debería escribirse en AGENTS.md?

Acción: si el fallo vino de una regla faltante, escríbela en AGENTS.md.

Las tareas grandes siguen siendo posibles con Codex

Los refactorings grandes no están prohibidos. Solo hay que dividirlos hasta que cada paso pueda revertirse por separado. La experiencia de refactorización con IA de 10.000 líneas muestra lo mismo: pasos pequeños y red de seguridad con tests son claves.

Comprueba la granularidad así:

• ¿Cada patch puede revertirse de forma independiente a nivel de hunk o archivo?
• ¿Cada paso de verificación puede probar que el comportamiento previo fallaba?
• ¿Cada merge tiene reviewer approve explícito y status checks?

Si la respuesta es no, la tarea sigue siendo demasiado grande.

Codex review pane en la práctica: validar no es solo testear

Al revisar un cambio de Codex, lo primero no es el resultado de tests. Es el scope del diff y la granularidad de rollback. El review pane de la app de Codex ofrece tres vistas y operaciones a nivel de hunk/archivo.

Tres vistas de diff

El review pane refleja el estado Git del repositorio, no solo los cambios de Codex. Puede mostrar cambios de Codex, del usuario y otras modificaciones sin commit.

Vista	Qué muestra	Cuándo usarla
uncommitted changes	Todos los cambios sin commit, por defecto	Revisar el scope de la tarea Codex actual
all branch changes	Todos los cambios de la rama actual contra la rama base	Revisar la cadena completa de tareas, incluso varios turns
last turn changes	Los cambios del último turn de Codex	Aislar lo que Codex acaba de hacer y detectar rápido cambios fuera de scope

Empieza con uncommitted changes para confirmar el scope. Luego mira all branch changes por si hay restos de tareas anteriores. Finalmente usa last turn changes para verificar si Codex siguió el plan.

Inline comments y operaciones hunk/archivo

El review pane permite inline comments sobre líneas concretas del diff. Esos comentarios pueden convertirse en contexto para una corrección posterior de Codex.

Niveles de operación:

• entire diff: stage/unstage/revert de todo el diff
• file: stage/unstage/revert de un archivo
• hunk: stage/unstage/revert de un bloque de código, la unidad útil más pequeña

Si encuentras un cambio fuera de scope, como una eliminación de configuración CI, revierte primero ese hunk o archivo en vez de tirar todo el diff.

Carga de PR context

En una PR branch, si hay acceso a GitHub o gh auth login, el review pane puede cargar PR context, review comments y changed files. Así pasas de “ver diff local” a “ver PR diff más comentarios del reviewer”.

Recordatorio sobre hechos volátiles: los detalles de UI y slash commands pueden cambiar. Reabre la página oficial antes de publicar si ese comportamiento exacto importa.

Principio central de la review

Validar no es solo mirar tests:

1. Primero comprueba si el scope del diff coincide con el plan
2. Luego comprueba si la granularidad de rollback es lo bastante pequeña, como hunk o archivo
3. Por último, comprueba si se agregaron tests y cubren el critical path

Si fallan las dos primeras comprobaciones, tests que pasan no prueban que el código sea correcto.

Checklist de evidencia: tests que pasan no bastan

GitHub Docs explica que required status checks deben estar successful, skipped o neutral antes de mergear en una protected branch. En GitHub Actions, un check skipped puede tratarse como success y no bloquear el merge.

Por eso “CI verde” no equivale a “el código está bien”. Necesitas un conjunto de evidencias, no una sola señal.

Usa esta checklist.

Evidencia a nivel de código

• El scope del diff coincide con la tarea, sin cambios fuera de scope
• No se agregó código duplicado; se buscó si ya existía un equivalente
• No se cambió CI/config salvo que la tarea lo permitiera explícitamente

Evidencia a nivel de tests

• Se agregaron tests para el core path
• Los tests fallarían antes del cambio, no solo pasan después
• La configuración de tests no se debilitó: sin coverage threshold reducido, sin skip, sin assertion más blanda

Evidencia a nivel de CI

• lint y pre-commit pasaron
• Los CI status checks son required y no skipped
• La configuración CI no cambió solo para hacer pasar el check

Evidencia a nivel de PR

• El PR body incluye implementation plan, comandos de verificación y notas de rollback
• Un reviewer humano approved explícitamente, en vez de confiar en el autorreporte de la IA
• La branch protection cubre required reviews, required status checks y conversation resolution

Evidencia a nivel de rollback

• Cada patch puede revertirse de forma independiente a nivel de hunk o archivo
• La tarea estuvo aislada en un worktree, para descartar un intento fallido y llevar uno exitoso a PR

Branch protection y status checks

Las protected branches de GitHub pueden exigir:

• required reviews: cierto número de approvals antes del merge
• required status checks: checks en estado passed, skipped o neutral antes de entrar a la rama protegida
• conversation resolution: todas las conversaciones resolved antes del merge

Estos son gates de merge fuera de la IA. No se reemplazan porque la IA diga que terminó.

Orden de review

Usa este orden:

1. Revisar primero el scope del diff, incluida la file list y el tamaño del diff
2. Revisar si cambió CI o configuración de tests
3. Revisar si se agregaron tests y cubren el core path
4. Revisar si un reviewer approved explícitamente

No inviertas el orden. Si empiezas por tests, es fácil perder cambios fuera de scope y CI debilitada.

Rollback y retrospectiva: qué hacer después de un mal cambio

Cuando la review encuentra un cambio fuera de scope o un test falsamente verde, el primer movimiento es rollback, no pedir a Codex que siga corrigiendo el mismo diff confuso.

Granularidad de rollback: de hunk a rama

Elige el nivel de rollback según el alcance y la causa del fallo:

Granularidad	Cuándo usarla	Operación
Revert a nivel hunk	Un bloque de código contiene un cambio fuera de scope, como una eliminación de CI	Seleccionar ese hunk en el review pane -> revert
Revert a nivel archivo	Un archivo entero contiene código duplicado o cambios fuera de scope	Seleccionar ese file en el review pane -> revert
Descartar rama	La dirección de la tarea está mal y hay que tirar varios archivos	git checkout main -> eliminar la rama

Prefiere la granularidad útil más pequeña. Solo descarta una rama cuando varios hunks o archivos están mal.

Aislamiento con worktree: los intentos fallidos se pueden tirar

El artículo de Codex Worktree de esta serie usa worktrees para aislar tareas paralelas. Un intento fallido se descarta; uno exitoso pasa a PR.

Si una tarea rompe código dentro de su worktree, elimina ese worktree y mantén limpio el workspace principal. Es más seguro que hacer revert una y otra vez en la misma rama.

Después del rollback: escribir en AGENTS.md

Después del rollback, decide si el fallo vino de una regla faltante. Si fue así, escríbela en AGENTS.md.

Haz estas preguntas:

• ¿Faltaba una convención de proyecto, como “no tocar CI config” o “dividir tareas con más de cinco archivos”?
• ¿Faltaban criterios de aceptación, como “los tests deben probar el fallo antes del cambio”?
• ¿Faltaba una regla de rollback, como “cada patch debe poder revertirse de forma independiente”?

Si la respuesta es sí, escribe la regla en el lugar correcto de AGENTS.md, como se describe en la siguiente sección.

Después de la retrospectiva: convertir flujos repetidos en skills

Decide si un fallo debería convertirse en skill con estas preguntas:

• ¿El fallo vino de un límite de Codex, como malentender una restricción de negocio?
• ¿Vino de un workflow complejo en varios pasos, como coordinación multi-agent?
• ¿Vino de un flujo de review que repites a menudo, como revisar scope de diff, CI config y tests agregados cada vez?

Si sí, conviértelo en skill, como se cubre en el artículo Codex Skills/plugins de esta serie.

Dónde poner reglas en AGENTS.md

Antes de cada run o session, Codex construye una instruction chain y lee los AGENTS.md globales y de proyecto. A nivel de proyecto, lee desde el Git root hasta el directorio actual. El archivo más cercano es más específico.

Eso significa que AGENTS.md puede vivir en la raíz del repositorio, en un submódulo o en un directorio de funcionalidad. Codex debería preferir la regla más específica cuando los paths se solapan.

Ubicaciones y contenido habituales de AGENTS.md

La guía de inicio de Codex de esta serie cubre una plantilla típica de AGENTS.md:

Ubicación	Contenido típico	Ejemplo
repo root	repo layout, build/test/lint commands, engineering conventions	Project structure: src/frontend, src/backend, src/shared; build: npm run build; test: npm test; lint: npm run lint
src/frontend	frontend-specific conventions y PR expectations	frontend usa solo React hooks, no class components; las PR deben incluir Storybook stories
src/backend	backend-specific conventions y do-not rules	backend no debe acceder directo a la base de datos; usar ORM; no escribir SQL en controllers
src/shared	shared utility conventions	shared contiene solo pure functions, sin side effects

Dónde escribir las lecciones de fallo

Después de un fallo, coloca la regla según la causa:

Causa del fallo	Dónde escribirla	Ejemplo
Config CI eliminada por error	repo root -> PR expectations -> do-not rules	No modificar .github/workflows/, Makefile o package.json scripts sin aprobación explícita
Más de cinco archivos cambiados	repo root -> PR expectations -> do-not rules	Los cambios que toquen más de cinco archivos deben dividirse; cada tarea debería tocar como máximo tres archivos
Tests falsamente verdes	repo root -> what done means	Los tests deben cubrir el core path y probar que el comportamiento previo falla, no solo que el nuevo pasa
Código duplicado	repo root -> engineering conventions	Antes de agregar un helper bajo src/lib, buscar un equivalente existente; si existe, usarlo
Cambio grande sin plan	repo root -> PR expectations	Cambios que toquen más de tres archivos requieren /plan primero, con archivos a editar, archivos prohibidos y comandos de verificación
Untrusted input	src/backend -> engineering conventions	Toda entrada de usuario debe validarse; no usar datos o paths de usuario directamente
Bug de negocio oculto	src/backend -> engineering conventions	Después de cambiar permission checks o validation, seguir un critical path y revisar efectos secundarios

Descubrimiento de reglas: el archivo más cercano gana

La documentación de OpenAI AGENTS.md describe las instrucciones de proyecto como una cadena desde el Git root hasta el directorio actual, donde los archivos más cercanos son más específicos.

En la práctica:

• AGENTS.md en repo root guarda reglas generales, como build/test/lint commands y “no tocar CI”
• AGENTS.md en un submódulo guarda reglas específicas, como hooks solo en frontend o prohibición de SQL en backend
• AGENTS.md en un directorio de funcionalidad guarda las reglas más específicas, como restricciones de negocio de una API

Al escribir una lección:

• Convenciones globales como “no tocar CI” van en repo root
• Convenciones de submódulo como reglas frontend van bajo src/frontend
• Restricciones de funcionalidad como una regla de API van bajo src/backend/api/xxx

El límite de AGENTS.md

AGENTS.md reduce cambios fuera de scope y errores accidentales, pero no prueba corrección. Codex puede seguir AGENTS.md y aun así producir lógica incorrecta.

El último gate sigue siendo un approval explícito de un reviewer humano, no la mera existencia de un archivo de reglas.

Checklist de review humana para PR de IA

El consejo de GitHub para revisar agent-generated PRs empieza por la file list y el tamaño del diff, luego revisa si cambió CI/test config, busca helpers duplicados, sigue un critical path y pide un test que pruebe que el comportamiento previo fallaba.

Usa esta checklist de señales rojas.

Señales rojas a nivel de código

• La file list y el tamaño del diff superan por mucho la descripción de la tarea
• Cambió CI/test config, como .github/workflows/, Makefile o package.json scripts
• Un nuevo helper duplica un helper existente
• El PR body solo dice “fix issue”, sin implementation plan, comandos de verificación ni rollback
• La PR es demasiado grande, por ejemplo más de 10 archivos

Señales rojas a nivel de tests

• No se agregó ningún test
• El test solo verifica el comportamiento post-change y no prueba que el anterior fallaba
• La configuración de tests se debilitó: coverage threshold reducido, flaky test en skip o assertion más blanda

Señales rojas a nivel de CI

• La CI falló, pero el patch solo cambió tests o CI config en lugar de código de negocio
• Los CI status checks están skipped o neutral, no passing
• La configuración CI cambió para hacer pasar el check

Señales rojas a nivel de PR

• PR body vacío
• Sin implementation plan
• Sin reviewer approval, solo reporte de la IA
• Conversaciones unresolved

Blockers vs señales de división

Tipo	Señal roja	Respuesta
Blocker	La CI falló, pero solo cambió test/CI config	Request changes, revertir el cambio de CI y exigir fix en código de negocio
Blocker	Tests falsamente verdes, como coverageThreshold reducido o skip	Request changes, revertir la configuración de test y exigir un nuevo test
Blocker	Untrusted input sin validation	Request changes y exigir validation tests
Señal de división	PR grande, por ejemplo más de 10 archivos	Request changes y dividir en PR más pequeñas
Señal de división	PR body vacío sin implementation plan	Request changes y agregar plan, comandos de verificación y rollback

Principio central del reviewer

El reviewer no juzga si la IA es fiable en abstracto. Revisa:

1. si el scope del diff coincide con la descripción de la tarea
2. si cambió CI/test config
3. si se agregaron tests y cubren el core path
4. si se revisaron efectos secundarios ocultos siguiendo un critical path

No inviertas el orden. Empezar por tests facilita pasar por alto CI debilitada y cambios fuera de scope.

Conclusión

Cuando Codex rompe código, la causa normalmente no es que sea “poco fiable” en abstracto. El límite de la tarea era demasiado amplio y el proceso de aceptación demasiado flojo. La checklist práctica es:

• Tabla de patrones de fallo: reconocer formas comunes en que los cambios de Codex salen mal
• Bucle de siete pasos: de scope a update rules como flujo completo de aceptación
• Review pane en la práctica: no quedarse en tests; revisar primero scope del diff y granularidad de rollback
• Checklist de evidencia: tests que pasan no bastan; también revisar scope del diff, tests agregados, estado CI, review humana y branch protection
• Rollback y retrospectiva: revert a nivel hunk/archivo, aislamiento con worktree y escritura en AGENTS.md o en un skill
• Ubicaciones de AGENTS.md: colocar reglas en repo root, submódulo o directorio de funcionalidad según el scope
• Señales rojas de review humana: empezar por file list y diff size, luego CI/test config, tests agregados y reviewer approval

Convierte esta lista en una herramienta real de review. Cada vez que revises un cambio de Codex, recórrela. Si el mismo flujo de review se repite, considera convertirlo en un skill, como en el artículo Codex Skills/plugins.

El fallo no es una sorpresa. Es un hueco de proceso.

Próximos pasos y lecturas recomendadas

Artículos publicados

• Refactorización con IA de 10.000 líneas: retrospectiva real y red de seguridad de tests — lecciones prácticas sobre pasos pequeños y red de tests
• Guía de refactorización con Cursor — principios de review aplicables a otras herramientas de coding con IA
• GitHub Actions CI workflow — fundamentos de status checks
• GitHub Actions workflow — fundamentos de PR workflow
• Flujo de trabajo de agente en Codex Cloud — ejecución remota, aceptación de PR y ciclos de tareas largas

Misma serie: Guía práctica de Codex

• Guía completa para empezar con Codex — CLI, IDE, Cloud y desktop
• Seguridad y permisos de Codex — sandbox y approval reducen riesgo
• Revisión de código con Codex — review como gate de aceptación
• Tareas de automatización con Codex — los patches generados por exec aún necesitan review humana
• Codex Worktree en la práctica — aislar tareas paralelas
• Codex Skills/plugins — convertir workflows de review en skills
• Desarrollo guiado por tests con Codex — TDD + Codex
• Optimización de costos de Codex
• Codex en flujos empresariales