Cómo dirigir a Codex, el agente de programación de OpenAI

Codex es el agente de programación de OpenAI: trabaja en la terminal sobre tu proyecto real. Puede recorrer un repositorio, entender cómo está organizado, modificar archivos, ejecutar comandos, escribir pruebas e investigar errores. Esa es la diferencia con pegarle código a un chatbot: aquí el agente actúa sobre lo que tienes en disco.

Por eso aprender a usarlo no consiste en memorizar comandos. La herramienta tiene cerca de sesenta, y con media docena se cubre el trabajo diario. Lo que de verdad cambia el resultado es otra cosa: enseñarle cómo está organizado el proyecto, acotar qué puede tocar y decirle cómo comprobar que lo que hizo funciona.

Las tres capas

Conviene pensar el trabajo con Codex en tres niveles. Están ordenados de menos a más influencia sobre el resultado, y casi todo el mundo empieza por el que menos importa.

Empezar en un proyecto

Codex se lanza desde el directorio del proyecto, porque es ahí donde va a trabajar:

cd mi-proyecto
codex

Antes de pedirle cambios de peso conviene comprobar dónde estás parado, sobre todo si trabajas con varios repositorios a la vez:

pwd
git status

Dentro de la sesión, el primer comando útil es /init, cuya descripción oficial es literalmente «crear un archivo AGENTS.md con instrucciones para Codex». Analiza el repositorio y redacta un primer borrador de las reglas.

AGENTS.md: las reglas del proyecto

Este archivo es el mecanismo más importante para personalizar el comportamiento de Codex, porque se lee en cada sesión sin que tengas que repetirlo. Una versión mínima y útil:

# AGENTS.md

## Objetivo
Qué hace este proyecto, en dos líneas.

## Arquitectura
- Backend: Python
- Frontend: React
- Base de datos: PostgreSQL

## Comandos
- Instalar: pip install -r requirements.txt
- Pruebas: pytest
- Lint: ruff check .
- Build: docker compose build

## Reglas
- Mantener los cambios dentro del alcance pedido.
- Ejecutar las pruebas después de modificar código.
- No introducir dependencias sin justificarlo.
- No guardar secretos en el repositorio.

## Seguridad
- Validar las entradas externas.
- No registrar contraseñas ni tokens.
- No desactivar la autenticación para resolver un error.

Lo más valioso de esa plantilla es la sección de comandos: si Codex sabe cómo se ejecutan las pruebas y el lint de tu proyecto, puede verificar su propio trabajo sin que se lo pidas cada vez.

Puede haber más de uno

En proyectos grandes, los archivos se acumulan por niveles: el de la raíz fija lo general y los de cada carpeta añaden lo específico. Lo más cercano al archivo que se está tocando manda.

Los comandos que de verdad usarás

La CLI tiene cerca de sesenta comandos slash; escribir / en el prompt los lista todos. Estos son los que aparecen en el trabajo diario, con la descripción que trae la propia herramienta.

Y desde la terminal, fuera de la sesión:

Qué puede hacer sin preguntar

Este es el punto que más conviene entender antes de dejarlo trabajar solo, y funciona con dos perillas independientes: dónde puede escribir y cuándo pide permiso.

Cómo pedir una tarea

Un buen encargo tiene cinco piezas: objetivo, contexto, restricciones, criterios de aceptación y forma de verificar. La diferencia se ve mejor con un ejemplo. En lugar de esto:

Haz login con JWT.

Esto otro:

Implementa autenticación con JWT.

Primero analiza la arquitectura actual y no hagas cambios.

Identifica:
- dónde está hoy la autenticación;
- qué componentes habría que modificar;
- qué dependencias harían falta;
- qué riesgos de seguridad aparecen.

Después presenta un plan.
No implementes nada hasta que el plan esté aprobado.

La segunda versión evita el problema más habitual: que el agente empiece a editar archivos antes de haber entendido el proyecto.

Plan, implementar, probar, revisar

Para cualquier tarea que no sea trivial, este es el ciclo que mejor funciona. Cada fase termina con algo que puedes mirar antes de dar paso a la siguiente.

En tareas largas ayuda mantener el plan en un archivo del repositorio, por ejemplo PLAN.md, con el objetivo, el estado actual, los archivos afectados, las fases, los criterios de aceptación y los riesgos. Así el plan sobrevive aunque la conversación se corte o se compacte.

Acotar el alcance

Un agente que explora encuentra problemas por el camino. Eso no significa que deba arreglarlos todos, y sin una instrucción explícita suele intentarlo:

Corrige únicamente el problema de autenticación.

Si encuentras otros problemas:
- no los toques;
- anótalos al final;
- sigue con la tarea original.

Esta regla de tres líneas evita que un arreglo pequeño acabe tocando medio proyecto.

Usarlo también para revisar

Codex sirve igual de bien como segundo par de ojos. Dos encargos que conviene tener a mano:

Haz una revisión de seguridad de los cambios actuales.

Busca: secretos expuestos, autenticación o autorización
insuficiente, validación de entradas, inyección SQL o de
comandos, manejo de archivos, datos sensibles en los logs
y dependencias inseguras.

No modifiques ningún archivo.
Devuelve los hallazgos ordenados por gravedad.

Revisa la arquitectura actual sin modificar código.

Analiza separación de responsabilidades, dependencias,
acoplamiento, escalabilidad, mantenibilidad y puntos
únicos de fallo.

Propón mejoras, pero no las implementes.

La plantilla que sirve para casi todo

Si tuvieras que quedarte con una sola cosa de esta guía, que sea esta estructura:

OBJETIVO      Qué quiero conseguir.
CONTEXTO      Qué necesita saber Codex del proyecto.
ALCANCE       Qué archivos o carpetas puede tocar.
RESTRICCIONES Qué no debe hacer bajo ningún concepto.
PROCESO       Qué pasos seguir y en qué orden.
VERIFICACIÓN  Cómo sabremos que terminó bien.
RESULTADO     Qué debe informarme al acabar.

Rellenarla cuesta un minuto y ahorra la mitad de las idas y venidas. Y como cada proyecto verifica de forma distinta, deja los comandos concretos en el AGENTS.md: pytest y ruff en Python, npm test y npm run build en JavaScript, go test ./... en Go, cargo test en Rust, mvn verify en Java.

Lo que no conviene delegar

La forma menos productiva de usar un agente es entregarle el proyecto y decirle «hazlo todo». Funciona mejor como colaborador que explora rápido una base de código, propone soluciones, implementa, ejecuta pruebas y documenta lo hecho, mientras tú sigues decidiendo los objetivos, las restricciones y qué se considera terminado.

Al final, dirigir a Codex se parece bastante a dirigir a alguien que acaba de entrar al equipo: es muy capaz, no conoce las costumbres de la casa y agradece que le digas dónde están los límites. Escribe eso una vez en AGENTS.md, acota cada encargo y pide siempre una forma de comprobar el resultado. El resto son comandos, y los comandos se aprenden solos.

Fuentes: repositorio oficial de Codex y la documentación para desarrolladores de OpenAI, consultadas el 30 de septiembre de 2026.