TDD con Codex: haz que la IA escriba el test primero y luego llegue a verde

Ves en la terminal que Codex escribe “todos los tests pasaron”. Pero al mirar con calma, solo hay una conclusión. No aparece el comando, ni dice qué tests ejecutó. Abres el diff y descubres que también cambió el archivo de test: la assertion pasó de toEqual(42) a toBeTruthy(). El problema no es desconfiar de Codex. El problema es confiar en un “verde” sin evidencia. Esta guía te da una plantilla operativa, una checklist de validación y guardrails contra falsos verdes para convertir “confiar en la IA” en “revisar evidencia reproducible”.

Por qué test-first es más importante con Codex

Test-first no es solo “escribir tests antes que código”. Con Codex, los tests se convierten en criterios de aceptación ejecutables por máquina. Codex puede ejecutar comandos, leer salidas y modificar archivos, pero necesita que definas antes qué significa “terminado”.

La documentación oficial de OpenAI Codex indica que Codex produce mejor trabajo cuando puede verificarlo. Eso significa que, si le dices cómo validar, qué comando ejecutar y qué resultado esperas, es más probable que haga el cambio correcto. Las tareas vagas se procesan de forma vaga. Las tareas pequeñas son más fáciles de probar y revisar.

El ciclo red-green-refactor tiene tres fases:

No conviene saltarse estos pasos. Si saltas red, no sabes si el test realmente valida el nuevo comportamiento. Si saltas refactor, es fácil dejar código parcheado. Para la base de Codex, consulta la guía completa para empezar con Codex.

Red Phase: hacer que Codex escriba un test que pueda fallar

La Red phase se basa en una restricción: modificar solo archivos de test, sin escribir implementación. Haz que Codex liste primero los casos, que los genere uno por uno y que al final ejecute los tests para confirmar el rojo.

Plantilla de prompt

Modifica solo archivos de test. No modifiques el código de implementación.
Escribe tests para [nombre de la funcionalidad] cubriendo:
1. [comportamiento mínimo]
2. [caso límite]
3. [ruta de error]
Al terminar, ejecuta `npm test` y pega el nombre del test fallido y la assertion.

Este prompt debe incluir “No modifiques el código de implementación”. Sin esa frase, Codex puede escribir el test y de paso implementar el comportamiento, rompiendo la verificación roja.

Confirmar el rojo

Cuando Codex termine, pide la salida completa del test. El rojo debe fallar en la assertion esperada, no en un error de compilación o importación. Si ves esto:

FAIL src/utils/calculator.test.ts > add > should handle negative numbers
AssertionError: expected -1 to be 42

el test está validando el comportamiento con números negativos y falla en el lugar esperado. Si solo ves TypeError: Cannot find module 'calculator', eso es un error de compilación, no un fallo útil de test.

Ordenar la lista de tests

No pidas a Codex que genere decenas de tests de una vez. Empieza por el comportamiento mínimo, los casos límite, los bugs de regresión y las rutas de error. Avanza caso por caso. La lista puede vivir en AGENTS.md o en un documento aparte para que Codex la siga en orden.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Para bases de testing unitario, consulta Vitest, tests unitarios y TDD y la guía práctica de Vitest.

Green Phase: mínima implementación hasta llegar a verde

El guardrail duro en Green phase es simple: los archivos de test no se tocan. Si el test falla, Codex solo puede cambiar la implementación. No puede adaptar el test para que encaje con el código.

Plantilla de prompt

Modifica solo archivos de implementación. No modifiques archivos de test.
Haz la mínima modificación necesaria para que los tests pasen.
Al terminar, ejecuta `npm test` y pega el resumen de tests pasados.

Este prompt debe incluir “No modifiques archivos de test”. Sin esa frase, Codex puede cambiar assertions, borrar tests o saltar casos para hacer que el resultado parezca verde.

Revisar el resumen y el diff

Después del trabajo de Codex, pide cantidad de tests, tests pasados y duración:

PASS src/utils/calculator.test.ts (1.2s)
  add
    ✓ should add two numbers (5ms)
    ✓ should handle negative numbers (3ms)
  2 tests passed

Luego revisa el diff. Si aparece un archivo de test en la lista de cambios, rechaza esa Green phase.

Guardrails contra falsos verdes

El falso verde es el mayor riesgo del TDD. Vigila estas seis señales:

Codex no aplica estos guardrails por ti. Debes revisarlos durante la review. Los equipos con más automatización pueden mover parte de estos controles a CI o a un pre-commit hook.

Refactor Phase: limpiar solo después del verde

La Refactor phase solo empieza después del verde. Si los tests no pasan, no refactorices. Después del refactor, hay que volver a ejecutar los tests; no basta con mirar el diff.

Plantilla de prompt

Todos los tests pasan. Ahora haz solo refactor:
- Renombrar variables para que la intención sea más clara
- Eliminar código duplicado
- Extraer funciones
No modifiques archivos de test. Luego vuelve a ejecutar `npm test`.

En esta fase Codex cambia estructura, no comportamiento. Si el refactor introduce lógica nueva, ya no es refactor: es una nueva Green phase para un comportamiento nuevo.

Volver a ejecutar tests

Después del refactor, Codex debe ejecutar otra vez el mismo conjunto de tests. Si siguen verdes, el refactor no rompió el comportamiento existente. Si un test falla, el refactor cambió comportamiento y hay que revertir o corregir.

También revisa el diff: los archivos de test no deberían aparecer en la lista de cambios. Si aparecen, el refactor cruzó el límite.

Para un ejemplo de refactorización, consulta Refactorización con IA y red de seguridad de tests.

Paquete de evidencia: hacer que Codex entregue pruebas revisables

Antes de cerrar cada fase, Codex debe entregar esta evidencia:

Checklist de aceptación antes de terminar

• Comando de test y exit code
• Resumen de fallo o éxito
• Lista de archivos modificados
• Si se modificaron archivos de test
• CI status checks, si existen

Plantilla de respuesta final

Haz que Codex responda con este formato:

### Resultado de tests
- Comando: `npm test`
- Exit code: 0
- Pasaron: 42 tests
- Fallaron: 0
- Duración: 1.2s

### Archivos modificados
- src/utils/calculator.ts
- (no se modificaron archivos de test)

### Riesgo restante
- Caso límite sin cubrir: entrada negativa

Este formato hace que la evidencia sea legible, comparable y fácil de archivar. Si Codex solo responde “los tests pasaron”, no puedes saber si realmente los ejecutó, si cambió archivos de test o si dejó fuera un caso límite.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Elegir la capa de test y comandos de ejemplo

Cada capa de test sirve para verificar riesgos distintos. No empieces siempre con E2E completo, y no te apoyes solo en snapshot tests.

Tabla de decisión de capas de test

Estos comandos son ejemplos: reemplázalos por los de tu proyecto. Cada stack puede usar Jest, Vitest, Pytest, Playwright o GitHub Actions. Para más contexto, consulta la guía de testing con Jest en Next.js.

Los tests unitarios suelen ser la primera capa de verificación para Codex. Corren rápido, dan errores claros y son fáciles de documentar en AGENTS.md. Los tests de integración y E2E sirven para interacciones entre módulos y flujos de usuario, pero los fallos son más difíciles de diagnosticar. Typecheck y lint complementan la verificación capturando errores de compilación y estilo. CI es el último gate del equipo: aunque todo pase en local, los CI status checks deben pasar antes del merge.

Fijar reglas en AGENTS.md y prompts

Escribe las reglas TDD en AGENTS.md para que Codex las lea antes de cada trabajo. Así no repites el mismo prompt cada vez.

Ejemplo pequeño de AGENTS.md

Coloca algo así en la raíz del proyecto o en un directorio local:

## Test commands
- Run tests: `npm test`
- Run unit tests: `npm run test:unit`
- Run typecheck: `npm run typecheck`

## TDD rules
- Red phase: only modify test files
- Green phase: only modify implementation files
- Refactor phase: must re-run tests after cleanup

## Done when
- All tests pass
- Test files are not modified in green/refactor phase
- Diff contains only expected changes

Este archivo le dice a Codex qué comandos de test existen, qué puede cambiar en cada fase y qué cuenta como terminado. Para más detalles sobre AGENTS.md, revisa el artículo de reglas de proyecto Codex de esta serie.

Los directorios locales pueden tener reglas más específicas. Por ejemplo, src/utils/AGENTS.md puede listar escenarios de test, casos límite y bugs conocidos de src/utils/.

No pongas secretos, tokens ni configuración sensible en AGENTS.md. Codex leerá este archivo, pero no filtra automáticamente información sensible.

Del local al equipo: gates de CI

Tests verdes en local no significan que puedas hacer merge. En equipos existe un gate de CI: los required status checks deben pasar y la PR review debe completarse.

Checklist del flujo

1. Tests locales verdes: Codex completa las tres fases y entrega el paquete de evidencia
2. Revisión del diff en review pane: comprobar si se modificaron archivos de test
3. Crear PR: push a una feature branch
4. Required status checks obligatorios: CI ejecuta test completo, typecheck y lint
5. Review humana: revisar diff, paquete de evidencia y riesgos restantes

Tests verdes no significan merge automático

GitHub Docs explica que los required status checks deben pasar antes de hacer merge a una protected branch. Pero hay un riesgo: un job skipped reporta success y no bloquea el merge del PR, aunque sea required check. Eso significa que un PR puede parecer mergeable aunque algunos checks no se hayan ejecutado.

Para evitar falsos verdes por workflows omitidos, abre la página GitHub Checks y confirma que todos los required checks se ejecutaron realmente, en lugar de aparecer como skipped.

Usar el review pane

El review pane de la Codex app permite ver si el diff incluye cambios en archivos de test. Puedes stage, unstage o revert por archivo o hunk. Si se cambió un archivo de test, revierte ese cambio y conserva solo el cambio de implementación.

Para más contexto de CI, consulta GitHub Actions CI y conceptos básicos de workflows en GitHub Actions. El flujo de PR review se trata en el artículo de code review con Codex AI de esta serie.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Límites para corregir fallos de CI automáticamente

codex exec y Codex GitHub Action pueden ayudar con tests de CI fallidos, pero necesitan límites de seguridad.

Flujo de autocorrección de fallos

Según la documentación de Codex non-interactive, un flujo para corregir fallos de CI sería:

1. Ejecutar primero el test para reproducir el fallo
2. Pedir a Codex la mínima corrección
3. Generar un patch artifact
4. Abrir un PR que separe el fix del job original

Con npm test 2>&1 | codex exec "resume la causa del fallo y sugiere la mínima corrección" puedes pasar la salida del test a Codex para que resuma el fallo y proponga una reparación mínima.

Principios de seguridad

No des a Codex acceso de escritura al repositorio y acceso a secretos en el mismo job. Usa el sandbox de menor privilegio: read-only por defecto, workspace-write solo para el directorio de trabajo, y danger-full-access solo en entornos controlados.

Separa la generación del patch artifact de la creación del PR para no exponer API keys a código no confiable.

No hace falta desarrollar aquí un YAML completo de GitHub Actions. El principio es simple: mínimo privilegio, patch separado y merge humano. La automatización con codex exec se trata en otro artículo de esta serie.

Resumen

El desarrollo guiado por tests con Codex se reduce a una plantilla de tres fases: Red solo escribe tests, Green solo toca implementación y Refactor limpia después de volver a ejecutar los tests. Cada fase debe entregar evidencia revisable: comando, resumen de fallo o éxito y lista de archivos modificados.

Los guardrails contra falsos verdes son la diferencia importante: revisar si se tocaron archivos de test, si se relajaron assertions, si se skippearon tests, si cambiaron fixtures, si solo se ejecutaron unit tests cuando importaba integración, o si el workflow de CI fue skipped.

En equipos, el verde local no basta. Los CI status checks, la PR review y las reglas de protected branch deciden si el cambio puede mergearse.

La próxima vez que pidas a Codex cambiar código, haz que escriba primero el test, confirma el rojo y luego revisa la evidencia. No te detengas en las palabras “los tests pasaron”.