Buenas prácticas

Si recién empiezas a usar Codex o agentes de programación en general, esta guía te ayudará a obtener mejores resultados en menos tiempo. Encontrarás prácticas que te ayudarán a aprovechar mejor Codex en la CLI, la extensión para IDE y la app de escritorio de ChatGPT. Abarcan desde la redacción de prompts y la planificación hasta la validación, MCP, las habilidades y las tareas programadas.

Codex funciona mejor cuando lo tratas como a un integrante del equipo cuya forma de trabajar puedes configurar y mejorar con el tiempo, en vez de recurrir a él solo para consultas puntuales.

Empieza por darle el contexto adecuado para la tarea. Usa AGENTS.md para guardar instrucciones que seguirán siendo válidas, configura Codex según tu forma de trabajar, conecta sistemas externos con MCP, convierte el trabajo repetitivo en habilidades y automatiza los flujos de trabajo estables.

Primeros pasos: contexto y prompts

Codex puede ayudarte incluso si tu prompt es imperfecto. A menudo basta con plantearle un problema difícil, con muy poca preparación, para obtener un buen resultado. Puedes aprovechar Codex sin dominar la redacción de prompts, aunque dar instrucciones claras mejora la fiabilidad de los resultados, sobre todo en bases de código grandes o en tareas en las que hay más en juego.

Si trabajas en un repositorio grande o complejo, lo que más ayuda es darle a Codex el contexto adecuado para la tarea y explicarle de forma ordenada qué quieres que haga.

Como punto de partida, incluye cuatro elementos en tu prompt:

• Objetivo: ¿qué quieres cambiar o crear?
• Contexto: ¿qué archivos, carpetas, documentos, ejemplos o errores son relevantes para esta tarea? Puedes mencionar archivos específicos con @ para aportar contexto.
• Restricciones: ¿qué estándares, arquitectura, requisitos de seguridad o convenciones debe respetar Codex?
• Criterios de finalización: ¿qué condiciones deben cumplirse para dar la tarea por terminada? Por ejemplo, que pasen las pruebas, que cambie un comportamiento o que un error ya no se pueda reproducir.

Estos cuatro elementos ayudan a Codex a ceñirse a la tarea, hacer menos suposiciones y entregar un trabajo más fácil de revisar.

Usa GPT-6.1 Sol si está disponible en tu cuenta y en el cliente que usas. Empieza con el nivel de esfuerzo de razonamiento predeterminado del cliente. Para GPT-6 Luna, empieza con Alta y, para GPT-6 Astra, con Ligera (low en la configuración). Ajusta el nivel según la tarea y el resultado. Consulta los niveles de razonamiento disponibles en Modelos.

• Baja para tareas rápidas y bien delimitadas
• Media o Alta para cambios más complejos o tareas de depuración
• Muy alta para tareas prolongadas que el agente realiza de forma autónoma y que exigen mucho razonamiento

Planifica antes de abordar tareas difíciles

Si la tarea es compleja, ambigua o difícil de describir con claridad, pídele a Codex que prepare un plan antes de empezar a escribir código.

Estas opciones funcionan bien:

Usa el Modo de planificación: para la mayoría de las personas, es la opción más sencilla y eficaz. En el Modo de planificación, Codex puede recopilar contexto, hacer preguntas para aclarar dudas y preparar un plan más sólido antes de implementarlo. Activa o desactiva este modo con /plan o Shift+Tab.

Pídele a Codex que te haga preguntas: si tienes una idea general de lo que quieres, pero te cuesta describirla, pídele a Codex que primero te haga preguntas. Pídele que cuestione tus suposiciones y te ayude a concretar la idea antes de escribir código.

Usa una plantilla de PLANS.md: para flujos de trabajo más avanzados, puedes configurar Codex para que siga un archivo PLANS.md o una plantilla de plan de ejecución en tareas prolongadas o de varios pasos. Para obtener más detalles, consulta la guía de planes de ejecución.

Reutiliza instrucciones con AGENTS.md

Cuando encuentres una forma de redactar prompts que te funcione, puedes ahorrarte el trabajo de repetir las instrucciones a mano. Para eso sirve AGENTS.md.

Piensa en AGENTS.md como un README de formato abierto para agentes. Su contenido se carga automáticamente en el contexto. Es el mejor lugar para definir cómo quieren tú y tu equipo que trabaje Codex en un repositorio.

Un buen archivo AGENTS.md incluye:

• La estructura del repositorio y sus directorios importantes
• Cómo ejecutar el proyecto
• Los comandos de compilación, pruebas y lint
• Las convenciones de ingeniería y los requisitos que deben cumplir los Pull requests
• Las restricciones y las acciones que se deben evitar
• Los criterios para dar una tarea por terminada y cómo verificar el trabajo

El comando slash /init de la CLI genera un archivo AGENTS.md inicial en el directorio actual. Es un buen punto de partida. Edítalo para que refleje cómo compila, prueba, revisa y publica código tu equipo.

Puedes crear archivos AGENTS.md en distintos niveles: un AGENTS.md global en ~/.codex para tus preferencias personales, un archivo en el nivel del repositorio para los estándares compartidos y archivos más específicos en los subdirectorios para las reglas locales. Si hay un archivo más específico y más cercano al directorio actual, sus instrucciones tienen prioridad.

Incluye instrucciones prácticas. Un AGENTS.md breve y preciso es más útil que un archivo largo lleno de reglas vagas. Empieza por lo básico y agrega reglas solo cuando detectes errores recurrentes.

Si AGENTS.md empieza a crecer demasiado, mantén el archivo principal conciso y agrega referencias a archivos Markdown específicos para tareas como la planificación, la revisión de código o el diseño de la arquitectura.

Configura Codex para que trabaje de forma consistente

La configuración es una de las principales formas de lograr que Codex trabaje de manera consistente entre sesiones e interfaces. Por ejemplo, puedes definir valores predeterminados para el modelo, el esfuerzo de razonamiento, el modo de sandbox, la política de aprobación, los perfiles y la configuración de MCP.

Para empezar:

• Guarda tus preferencias personales en ~/.codex/config.toml (Configuración > Configuración > Abrir config.toml en la app de escritorio de ChatGPT)
• Define el comportamiento específico del repositorio en .codex/config.toml
• Si usas la CLI, sobrescribe los valores desde la línea de comandos solo para situaciones puntuales

En config.toml defines preferencias que se mantienen entre sesiones, como los servidores MCP, la configuración de varios agentes y las opciones que activan o desactivan funciones. Los ajustes específicos de cada perfil se guardan en archivos $CODEX_HOME/profile-name.config.toml separados.

Codex incluye un entorno aislado a nivel del sistema operativo y ofrece dos ajustes principales. El modo de aprobación determina cuándo Codex te pide permiso para ejecutar un comando. El modo de sandbox determina si Codex puede leer o escribir en el directorio y a qué archivos puede acceder el agente.

Si recién empiezas a usar agentes de programación, usa los permisos predeterminados. Mantén reglas estrictas de aprobación y restricciones en el entorno aislado. Amplía los permisos solo para repositorios de confianza o flujos de trabajo específicos cuando esté claro que lo necesitan.

La CLI, la extensión para IDE y la app de escritorio de ChatGPT comparten las mismas capas de configuración. Consulta la página de configuración de ejemplo para obtener más información.

Mejora la fiabilidad con pruebas y revisiones

Además de pedirle a Codex que haga un cambio, pídele que cree pruebas cuando hagan falta, ejecute las verificaciones pertinentes, confirme el resultado y revise el trabajo antes de que lo aceptes.

Codex puede encargarse de todo el proceso, siempre que sepa qué consideras un “buen resultado”. Puedes especificar esos criterios en el prompt o en AGENTS.md.

Por ejemplo, puedes pedirle que realice estas tareas:

• Escribir o actualizar pruebas para el cambio
• Ejecutar los conjuntos de pruebas pertinentes
• Verificar el código con el linter, comprobar el formato o ejecutar las verificaciones de tipos
• Confirmar que el comportamiento final coincida con lo que pediste
• Revisar el diff en busca de errores, regresiones o patrones de riesgo

El comando slash /review te ofrece varias formas de revisar el código:

• Comparar los cambios con una rama base, como en la revisión de un Pull request
• Revisar cambios pendientes de commit
• Revisar un commit
• Usar instrucciones de revisión personalizadas

Si tu equipo tiene un archivo code_review.md y lo referencia desde AGENTS.md, Codex también puede seguir esas instrucciones durante la revisión. Esta práctica ayuda a los equipos a aplicar los mismos criterios de revisión en distintos repositorios y entre distintos colaboradores.

Codex puede hacer más que generar código. Con las instrucciones adecuadas, también puede ayudarte a probarlo, verificarlo y revisarlo.

Si usas GitHub Cloud, puedes configurar Codex para que haga revisiones de código en tus Pull requests. En OpenAI, Codex revisa el 100 % de los Pull requests. Puedes activar las revisiones automáticas o pedir una revisión mencionando a @Codex.

Usa servidores MCP para aportar contexto externo

Usa servidores MCP cuando el contexto que necesita Codex esté fuera del repositorio. Así, Codex puede conectarse a las herramientas y los sistemas que ya usas sin que tengas que copiar y pegar información actualizada en los prompts una y otra vez.

El Model Context Protocol, o MCP, es un estándar abierto para conectar Codex a herramientas y sistemas externos.

Usa MCP cuando:

• El contexto que necesitas esté fuera del repositorio
• Los datos cambien con frecuencia
• Quieras que Codex use una herramienta en vez de depender de instrucciones que pegues en el prompt
• Necesites una integración que puedas reutilizar con distintos usuarios o proyectos

Codex admite servidores STDIO y servidores Streamable HTTP con OAuth.

En la app de escritorio de ChatGPT, ve a Configuración > Servidores MCP para ver los servidores personalizados y recomendados. A menudo, Codex puede ayudarte a instalar los servidores que necesitas. Solo tienes que pedírselo. También puedes usar el comando codex mcp add en la CLI para agregar tus servidores personalizados con un nombre, una URL y otros detalles.

Convierte el trabajo repetitivo en habilidades

Cuando puedas repetir un flujo de trabajo, ya no tendrás que depender de prompts largos ni de múltiples intercambios. Usa una habilidad para reunir las instrucciones en un archivo SKILL.md junto con el contexto y la lógica de apoyo que Codex debe aplicar de manera consistente. Las habilidades funcionan en la CLI, la extensión para IDE y la app de escritorio de ChatGPT.

Dedica cada habilidad a una sola tarea. Empieza con dos o tres casos de uso concretos, define con claridad las entradas y salidas, y explica en la descripción qué hace la habilidad y cuándo usarla. Incluye ejemplos de frases que alguien usaría para pedir esa tarea.

Evita intentar cubrir todos los casos especiales desde el principio. Empieza con una tarea representativa. Una vez que funcione bien, convierte ese flujo de trabajo en una habilidad y mejórala con el tiempo. Incluye scripts o recursos adicionales solo si mejoran la fiabilidad.

Si reutilizas el mismo prompt o corriges el mismo flujo de trabajo una y otra vez, probablemente convenga crear una habilidad.

Las habilidades son especialmente útiles para tareas recurrentes como estas:

• Clasificar y priorizar problemas detectados en los registros
• Redactar notas de la versión
• Revisar Pull requests con una lista de verificación
• Planificar migraciones
• Resumir datos de telemetría o incidentes
• Seguir procedimientos habituales de depuración

La habilidad $skill-creator es el mejor punto de partida para crear la estructura inicial de una habilidad. Trabaja en la primera versión de forma local mientras la perfeccionas. Cuando esté lista para compartirla con más personas, distribúyela como un complemento. La descripción es una de las partes más importantes de una habilidad. Debe explicar qué hace y cuándo usarla.

Usa tareas programadas para el trabajo repetitivo

Una vez que un flujo de trabajo sea estable, puedes programar Codex para que lo ejecute en segundo plano. En la app de escritorio de ChatGPT, las tareas programadas te permiten elegir el proyecto, el prompt, la frecuencia y el entorno de ejecución para el trabajo recurrente.

Crea una tarea programada desde la página Programadas. Elige el proyecto, el prompt, la frecuencia y si la tarea se ejecutará en un worktree de Git dedicado o en tu entorno local. El prompt puede invocar habilidades. Obtén más información sobre los worktrees de Git.

Algunas tareas que conviene programar:

• Resumir commits recientes
• Buscar posibles errores
• Redactar notas de la versión
• Revisar fallos de integración continua
• Preparar resúmenes para las reuniones diarias
• Ejecutar flujos de análisis repetibles con una frecuencia determinada

Las habilidades definen cómo se hace el trabajo y las tareas programadas definen cuándo se hace. Si un flujo de trabajo todavía requiere mucha orientación, conviértelo primero en una habilidad. Cuando dé resultados predecibles, programarlo puede ahorrarte tiempo.

Organiza los chats de larga duración

Los chats acumulan contexto, decisiones y acciones con el tiempo. La forma en que los organizas influye mucho en la calidad de los resultados.

La app de escritorio de ChatGPT te permite fijar chats y crear worktrees. Si usas la CLI, estos comandos slash son especialmente útiles:

• /experimental para activar o desactivar funciones experimentales y agregarlas a tu config.toml
• /resume para reanudar un chat guardado
• /fork para crear un chat nuevo y conservar la transcripción original
• /compact para resumir el contexto anterior cuando el chat se alarga. Codex también compacta los chats automáticamente
• /subagents para alternar entre los hilos de los subagentes del chat actual
• /theme para elegir un tema de resaltado de sintaxis
• /apps para usar apps de ChatGPT directamente en Codex
• /status para consultar el estado de la sesión actual

Usa un chat por cada conjunto de tareas que persigan un mismo objetivo. Si sigues trabajando en el mismo problema, suele convenir continuar en el mismo chat para conservar el hilo del razonamiento. Crea un fork solo cuando el trabajo realmente se divida en líneas distintas.

Errores comunes

Evita estos errores al empezar a usar Codex:

• Sobrecargar el prompt con reglas permanentes en vez de trasladarlas a AGENTS.md o a una habilidad
• Impedir que el agente compruebe su trabajo por falta de detalles sobre cómo ejecutar los comandos de compilación y de pruebas
• Omitir la planificación en tareas complejas o de varios pasos
• Darle a Codex acceso completo a tu computadora antes de entender el flujo de trabajo
• Ejecutar tareas simultáneas sobre los mismos archivos sin usar worktrees de Git
• Programar una tarea recurrente antes de que funcione de forma fiable al ejecutarla manualmente
• Supervisar a Codex paso a paso en vez de usarlo en paralelo mientras avanzas con tu propio trabajo
• Usar un solo chat para todo un proyecto en vez de dedicar un chat a cada resultado concreto. Esto hace que se acumule contexto en exceso y que los resultados empeoren con el tiempo