Cómo usar Codex: guía práctica para programar con el agente de OpenAI
Aprende
cómo usar OpenAI Codex
correctamente en un proyecto real:
abrir un repositorio,
darle contexto,
investigar el código,
planificar cambios,
implementar funcionalidades,
corregir bugs,
ejecutar tests,
revisar el diff,
utilizar
/review
y preparar cambios
para Git
sin perder el control
del proyecto.
¿Cómo se usa Codex para programar?
La forma más efectiva
de usar Codex
es abrirlo
dentro del repositorio correcto,
darle un objetivo concreto,
permitir que investigue
primero el código,
pedir un plan
cuando el cambio sea complejo,
implementar solamente
después de entender
la arquitectura
y terminar siempre
con tests,
revisión del diff
y una revisión independiente
mediante
/review
cuando el cambio
sea importante.
El workflow de Codex en seis pasos
Contexto
Abre el proyecto correcto y carga sus instrucciones.
Explorar
Pide que entienda el flujo antes de editar.
Planificar
Define archivos, riesgos y pruebas.
Implementar
Modifica solamente lo necesario.
Verificar
Tests, lint, build y comportamiento.
Revisar
Diff,
/review,
Git
y entrega.
No empieces pidiendo código cuando primero necesitas entender el problema
¿Cómo funciona?
Arquitectura, dependencias, archivos y flujo actual.
¿Qué cambiaremos?
Alcance, riesgos, tests y estrategia.
Implementa
Solución mínima siguiendo patrones existentes.
Demuestra
Pruebas, diff y evidencia del resultado.
Abre Codex dentro del proyecto correcto
cd mi-proyecto
codexCodex CLI considera el directorio desde el que se inicia como el proyecto del chat.
También puedes establecerlo explícitamente:
codex --cd /ruta/mi-proyectoComprueba el estado de Git
git statusSi ya existen cambios sin commit, Codex puede encontrarlos en el mismo diff que sus propias modificaciones.
Haz que Codex entienda el proyecto antes de programar
Analiza este proyecto antes de modificar nada.
Quiero entender:
- propósito
- arquitectura
- punto de entrada
- módulos principales
- dependencias
- almacenamiento de datos
- autenticación
- APIs
- tests
- build
- configuración
Después crea
un mapa del proyecto
y explícame
cómo fluye una petición típica.
No hagas cambios todavía.Pide rutas, funciones y evidencia concreta
Encuentra cómo funciona el sistema de login.
Indica:
1. archivos involucrados
2. funciones principales
3. dónde se validan credenciales
4. dónde se crea la sesión
5. cómo se manejan errores
6. qué tests cubren este flujo
Incluye rutas de archivos
y nombres de funciones.
No modifiques nada.Pedir archivos y símbolos concretos obliga a relacionar la explicación con el repositorio real.
Usa AGENTS.md para reglas que se repiten
Si siempre tienes que decirle a Codex qué stack utilizas, cómo ejecutar tests o qué convenciones debe respetar, esa información debería vivir en AGENTS.md.
# AGENTS.md
## Stack
PHP 8.2
MySQL
JavaScript
## Reglas
- Usa PDO.
- Usa prepared statements.
- Mantén compatibilidad con PHP 8.2+.
- No añadas dependencias sin necesidad.
- No modifiques APIs públicas sin aprobación.
## Verificación
composer test
vendor/bin/phpcs
También pueden existir
distintos
AGENTS.md
según
la carpeta
del repositorio.
Escribe la tarea como si fuera un buen GitHub Issue
OBJETIVO
Añadir recuperación de contraseña.
COMPORTAMIENTO ACTUAL
El usuario puede iniciar sesión,
pero no existe flujo de recuperación.
COMPORTAMIENTO ESPERADO
El usuario debe poder:
1. solicitar recuperación
2. recibir un token
3. abrir una URL de reset
4. establecer nueva contraseña
RESTRICCIONES
- reutiliza el sistema de email existente
- no cambies el login actual
- no añadas nuevas dependencias
- los tokens deben caducar
ACEPTACIÓN
- usuario válido recibe email
- email inexistente no revela si la cuenta existe
- token expirado no funciona
- contraseña cambia correctamente
- tests pasan“Hazlo mejor” deja demasiado espacio de interpretación. Un criterio de aceptación concreto permite a Codex verificar su propio trabajo.
Divide proyectos grandes en tareas razonables
En vez de pedir “reescribe toda la plataforma”, divide el trabajo en resultados independientes que puedan entenderse, implementarse y verificarse.
Rehaz el ecommerce
Objetivo demasiado ambiguo y difícil de verificar.
Añade cupones al checkout
Scope concreto, verificable y aislable.
Pide un plan antes de cambios complejos
Investiga cómo implementar esta feature.
Antes de escribir código:
1. encuentra los archivos relacionados
2. identifica patrones existentes
3. determina qué datos deben cambiar
4. identifica efectos secundarios
5. revisa seguridad
6. identifica tests existentes
7. define tests nuevos necesarios
Después crea un plan.
Para cada paso indica:
- archivo
- cambio
- motivo
- riesgo
- forma de verificarlo
No implementes todavía.Cuándo planificar y cuándo ir directamente al cambio
Cuando el plan esté claro, pide la implementación
Implementa el plan.
Restricciones:
- sigue la arquitectura existente
- reutiliza patrones actuales
- no hagas refactors no relacionados
- no cambies APIs públicas
- no añadas dependencias salvo necesidad real
Después:
1. ejecuta los tests relevantes
2. ejecuta lint y typecheck si existen
3. corrige errores introducidos por el cambio
4. revisa git diff
5. confirma que no modificaste nada fuera del alcance.No des más acceso del necesario
Para desarrollo normal, mantén Codex dentro del workspace y permite que solicite autorización cuando necesite acceso adicional.
/permissionsEl sandbox controla a qué recursos puede acceder un comando. Las aprobaciones determinan cuándo Codex debe detenerse y pedirte permiso.
Activa la red solamente cuando la tarea la necesite
Instalar una dependencia.
Consultar documentación actual.
Probar una API externa.
Refactorizar código completamente local.
Puedes utilizar las capacidades de búsqueda sin necesariamente dar acceso de red general a todos los comandos.
No termines en “el código parece correcto”
Una tarea debería terminar con una forma reproducible de comprobar que funciona.
| Cambio | Verificación |
|---|---|
| Backend | Tests automatizados |
| TypeScript | Typecheck + tests |
| Frontend | Build + navegador |
| API | Requests reales |
| PHP | Lint + tests |
| Bug | Test de regresión |
Pide evidencia de que la implementación funciona
Verifica la implementación.
Ejecuta:
- tests relevantes
- lint
- typecheck
- build
si existen en este proyecto.
Después revisa git diff.
No me digas solamente
que funciona.
Entrégame:
- comandos ejecutados
- resultados
- archivos modificados
- tests añadidos
- cualquier limitación pendiente.Cómo usar Codex para corregir un bug
Tenemos este bug:
[ERROR]
Pasos para reproducir:
[PASOS]
Quiero que:
1. reproduzcas el problema
2. identifiques la causa raíz
3. traces el flujo relacionado
4. escribas un test que falle
5. implementes la corrección mínima
6. ejecutes el test
7. ejecutes tests relacionados
8. revises el diff
No ocultes el error
ni elimines validaciones
para que el test pase.Si no conoces la causa, prohíbe temporalmente las ediciones
Investiga este bug,
pero NO modifiques archivos todavía.
Síntoma:
[PROBLEMA]
Determina:
- dónde comienza
- causa raíz
- funciones involucradas
- si existe regresión
- qué cambios recientes podrían relacionarse
- otros módulos afectados
Propón después
la corrección mínima.Cómo pedir un refactor sin cambiar comportamiento
Refactoriza este módulo.
Objetivo:
[OBJETIVO]
Restricciones:
- no cambies comportamiento externo
- conserva APIs públicas
- evita dependencias nuevas
- mantén compatibilidad
Antes de editar:
1. identifica tests relevantes
2. ejecútalos
3. confirma el comportamiento actual
Después del refactor:
4. ejecuta los mismos tests
5. ejecuta lint/typecheck
6. revisa git diff.Usa imágenes cuando el resultado sea visual
codex --image referencia.pngUsa esta imagen
como referencia visual.
Primero identifica
qué componentes existentes
podemos reutilizar.
Implementa la interfaz
sin introducir
un sistema de estilos nuevo.
Después ejecuta el proyecto
y compara visualmente
el resultado.Usa Web Search cuando el conocimiento pueda haber cambiado
codex --searchDocumentación actual.
APIs que cambian rápido.
Versiones de librerías.
Errores de herramientas recientes.
Usa /review antes de integrar cambios importantes
/reviewRevisar cambios sin commit.
Comparar con una rama base.
Revisar un commit concreto.
Definir criterios personalizados.
Devuelve hallazgos priorizados para que puedas decidir cuáles corregir antes de hacer commit.
También puedes orientar la revisión
Revisa el diff actual.
Prioriza únicamente:
- bugs
- regresiones
- seguridad
- concurrencia
- pérdida de datos
- incompatibilidades
- requisitos incumplidos
Para cada hallazgo:
- severidad
- archivo
- línea
- impacto
- corrección sugerida
No reportes preferencias
de estilo sin impacto real.Revisa git diff antes de cerrar la tarea
git status
git diffSi tú ya tenías modificaciones sin commit, también aparecerán. No atribuyas automáticamente todo el diff al agente.
Pide una última revisión de cambios accidentales
Antes de terminar,
revisa todos los cambios actuales.
Busca:
- console.log
- var_dump
- print_r
- debugging temporal
- TODO accidentales
- archivos generados
- cambios de formato no relacionados
- secretos
- credenciales
- dependencias añadidas accidentalmente
No cambies nada
que no esté claramente relacionado
con esta tarea.Haz commit solamente después de verificar
Revisa nuevamente:
- git status
- git diff
- tests
- lint
- build
Si todo está correcto:
1. prepara únicamente los archivos relacionados
2. crea un commit descriptivo
Al terminar,
muéstrame:
- commit creado
- archivos incluidos
- tests ejecutados.Retoma un chat cuando el objetivo siga siendo el mismo
codex resumeDentro de Codex CLI también puedes usar:
/resumeSin embargo, Codex vuelve a leer el árbol de trabajo actual, que puede haber cambiado desde la sesión original.
Usa /new cuando la tarea ya no tenga relación
/newMismo objetivo
Continúa debugging, implementación o revisión relacionada.
Objetivo nuevo
Inicia otro chat para una tarea independiente.
No metas cinco objetivos independientes en el mismo chat
Esta separación mantiene el contexto más enfocado y facilita revisar exactamente qué produjo cada tarea.
Corregir login.
Migrar base de datos.
Refactorizar emails.
Crear dashboard.
Para tareas paralelas, utiliza chats separados y, cuando corresponda, worktrees.
Aísla trabajos simultáneos
Los worktrees permiten que distintas tareas de Codex trabajen sobre el mismo repositorio sin compartir exactamente el mismo checkout.
Un agente puede trabajar en autenticación mientras otro implementa una nueva API, sin mezclar los cambios.
Cuando el workflow ya es repetible, usa codex exec
codex exec "Revisa los cambios actuales y resume riesgos"También puedes encadenar herramientas:
npm test 2>&1 \
| codex exec "Resume los tests fallidos y propone la corrección mínima"Si el trabajo necesita escribir archivos, debes conceder el sandbox apropiado explícitamente.
Ejemplo de workflow con un plugin WordPress
Analiza este plugin WordPress.
Primero identifica:
- archivo principal
- clases
- actions
- filters
- shortcodes
- AJAX
- REST API
- cron
- tablas
- WooCommerce
- permisos
- nonces
Después investiga este problema:
[PROBLEMA]
No modifiques nada
hasta entender
la causa raíz.
Cuando la encuentres:
1. crea un plan
2. implementa la corrección mínima
3. ejecuta php -l
4. ejecuta tests configurados
5. revisa seguridad
6. revisa git diff.Por qué Codex puede dar malos resultados
Tarea demasiado amplia.
Objetivo ambiguo.
Falta contexto.
No hay criterios de aceptación.
No existen tests ejecutables.
Entorno mal configurado.
Se mezclan varias tareas en el mismo chat.
Se acepta el resultado sin revisar.
Si Codex falla repetidamente, quizá el problema no sea el prompt
Codex necesita un entorno donde pueda instalar dependencias, ejecutar tests y reproducir el comportamiento del proyecto.
Variables necesarias.
Dependencias instaladas.
Base de datos de desarrollo.
Tests ejecutables.
Si Codex siempre tropieza con el mismo problema de configuración, corrígelo en el entorno en vez de explicarlo manualmente en cada sesión.
Prompt maestro para trabajar con Codex
OBJETIVO
Quiero:
[RESULTADO]
CONTEXTO
Área del proyecto:
[RUTAS / MÓDULOS]
ANTES DE MODIFICAR
1. investiga cómo funciona actualmente
2. identifica archivos relacionados
3. encuentra patrones existentes
4. detecta riesgos
5. identifica tests relevantes
PLAN
Si el cambio afecta varios archivos,
crea primero un plan.
Para cada paso indica:
- archivo
- cambio
- motivo
- verificación
RESTRICCIONES
- no cambies comportamiento no relacionado
- evita dependencias nuevas
- conserva APIs públicas
- sigue las convenciones existentes
IMPLEMENTACIÓN
Implementa solamente
cuando entiendas el flujo actual.
VERIFICACIÓN
Después:
- ejecuta tests
- ejecuta lint/typecheck/build si existen
- revisa git diff
- comprueba edge cases
REVISIÓN
Busca:
- bugs
- regresiones
- seguridad
- cambios accidentales
ENTREGA
Resume:
- archivos modificados
- comandos ejecutados
- tests realizados
- resultados
- riesgos pendientes.Workflow completo recomendado
Abre el proyecto
Inicia Codex desde el directorio correcto.
Comprueba Git
Empieza desde un estado conocido.
Explora
Comprende el sistema antes de editar.
Planifica
Para cambios complejos o multiarchivo.
Implementa
Solución mínima y coherente.
Prueba
Tests, lint, build y ejecución.
/review
Revisión independiente del diff.
Git
Commit solamente después de verificar.
Continúa aprendiendo Codex
Documentación recomendada
Cómo OpenAI usa Codex
Casos de uso y buenas prácticas de equipos internos.
Ver guía →Proyectos y chats
Contexto, proyectos, /new y resume.
Ver documentación →Code Review
Revisiones, ramas, commits y cambios sin commit.
Ver Code Review →Sandbox
Permisos, aprobaciones y aislamiento.
Ver Sandbox →FAQ sobre cómo usar Codex
Abre Codex dentro del directorio del proyecto que quieres trabajar. Después describe una tarea concreta o pide primero que analice la arquitectura del repositorio.
Para cambios complejos, bugs desconocidos o repositorios que no conoces, suele ser conveniente pedir primero que Codex investigue el flujo actual y localice los archivos relevantes.
Define el objetivo, describe el comportamiento actual y esperado, añade restricciones y termina con criterios de aceptación que Codex pueda comprobar.
Cuando una tarea afecta varios archivos, tiene riesgos importantes, implica una migración o todavía no está clara la solución. Los cambios simples pueden implementarse directamente.
AGENTS.md permite guardar instrucciones persistentes para Codex, como arquitectura, comandos de test, convenciones y reglas específicas del repositorio.
Define verificaciones ejecutables: tests, lint, typecheck, build, requests reales o comprobaciones visuales. Pide además los comandos ejecutados y sus resultados.
/review inicia una revisión especializada del código. Puede analizar cambios sin commit, un commit o diferencias respecto de una rama base y reporta hallazgos priorizados.
Es recomendable iniciar chats distintos para resultados independientes. Mantén el mismo chat cuando las tareas formen parte del mismo objetivo.
Desde terminal puedes ejecutar codex resume. Dentro de Codex CLI también puedes utilizar /resume para volver a una conversación guardada.
Sí. Puedes adjuntar screenshots, diagramas y referencias visuales para debugging o desarrollo de interfaces.
Sí. Puedes separar tareas en chats y worktrees diferentes para evitar que agentes paralelos modifiquen el mismo checkout.
codex exec es el modo no interactivo de Codex. Permite ejecutar tareas desde scripts, terminal, pipes y pipelines CI/CD.
Cómo instalar Codex CLI
Ya sabes cómo trabajar con Codex. Ahora veremos todas las formas de instalarlo correctamente en Windows, macOS y Linux, además de npm, Homebrew, WSL2, actualización y solución de errores comunes.
Instalar Codex CLI →