Primeros pasos con Codex: Mejores prácticas para obtener mejores resultados

Si eres nuevo en @OpenAI Codex o en los agentes de codificación en general, esta guía te ayudará a obtener mejores resultados más rápido. Cubre los hábitos clave que hacen que Codex sea más efectivo en la CLI, las extensiones del IDE y la aplicación Codex, desde la redacción de instrucciones y la planificación hasta la validación, MCP, habilidades y automatizaciones.

Codex funciona mejor cuando lo tratas menos como un asistente puntual y más como un compañero de equipo que configuras y mejoras con el tiempo.

Un modelo mental útil es: empezar con el contexto de tarea adecuado, usar AGENTS.md para orientación duradera, configurar Codex para que se adapte a tu flujo de trabajo, conectar sistemas externos con MCP, convertir trabajos repetitivos en habilidades y automatizar flujos de trabajo estables.

1. Configura Codex para un primer uso sólido con contexto e instrucciones claras

Codex ya es lo suficientemente potente como para ser útil incluso cuando tu instrucción no es perfecta. A menudo puedes darle un problema difícil con una configuración mínima y aun así obtener un resultado sólido. Una instrucción clara no es obligatoria para obtener valor, pero sí hace que los resultados sean más fiables, especialmente en bases de código grandes o tareas de alto riesgo.

Si trabajas en un repositorio grande o complejo, el mayor avance suele ser darle a Codex el contexto de tarea adecuado y una estructura clara de lo que quieres que haga.

Un buen enfoque por defecto es incluir cuatro cosas en tu instrucción:

• Objetivo: ¿Qué quieres cambiar o construir?
• Contexto: ¿Qué archivos, carpetas, documentos, ejemplos o errores son relevantes para esta tarea? Puedes mencionar ciertos archivos con @ para dar contexto.
• Restricciones: ¿Qué estándares, arquitectura, requisitos de seguridad o convenciones debe seguir Codex?
• Listo cuando: ¿Qué debe ser cierto antes de que la tarea esté completa, como que las pruebas pasen, el comportamiento cambie o un error esté solucionado?

Esto ayuda a que Codex se mantenga dentro del alcance, haga menos suposiciones y produzca un trabajo que sea más fácil de revisar y validar.

Elige un nivel de razonamiento según la dificultad de la tarea y prueba qué funciona mejor para tu flujo de trabajo. Diferentes usuarios y tareas se benefician de diferentes configuraciones.

• Bajo para tareas rápidas y bien definidas
• Medio o Alto para cambios más complejos o depuración
• Muy Alto para tareas largas, agentivas y con mucho razonamiento

Consejo para nuevos usuarios

: La mayoría de las personas se ponen al día más rápido empezando con algunos logros básicos, como hacer preguntas a Codex sobre la base de código o usarlo para hacer una pequeña corrección concreta. Recomiendo encarecidamente usar el dictado por voz en la aplicación Codex para acelerar las iteraciones.

Niveles de razonamiento de Codex

2. Reduce errores en tareas difíciles pidiendo a Codex que planifique primero

Si la tarea es compleja, ambigua o difícil de describir con claridad, pide a Codex que planifique antes de empezar a codificar.

Hay varias formas buenas de hacerlo:

Usar el modo Plan: Para la mayoría de los usuarios, esta es la opción más fácil y efectiva. El modo Plan permite a Codex recopilar contexto, hacer preguntas aclaratorias y construir un plan más sólido antes de la implementación. Actívalo con /plan o Mayús+Tab.

Pide a Codex que te entreviste: Si tienes una idea aproximada de lo que quieres pero no estás seguro de cómo describirla bien, pídele a Codex que te haga preguntas primero. Dile que cuestione tus suposiciones y convierta la idea difusa en algo concreto antes de escribir código.

Usa una plantilla PLANS.md: Para flujos de trabajo más avanzados, puedes configurar Codex para que siga una plantilla PLANS.md o de plan de ejecución para trabajos de larga duración o de varios pasos. Para más detalles, consulta nuestra guía de planes de ejecución.

Modo Plan

3. Haz que las instrucciones exitosas sean reutilizables con AGENTS.md

Una vez que un patrón de instrucciones funciona, el siguiente paso es dejar de repetirlo manualmente. Ahí es donde entra AGENTS.md.

Piensa en AGENTS.md como un README para agentes. Es un formato abierto y simple que se carga automáticamente en el contexto y es el mejor lugar para codificar cómo quieres que Codex funcione en un repositorio, tanto tú como tu equipo.

Un buen AGENTS.md suele cubrir:

• La estructura del repositorio y los directorios importantes
• Cómo ejecutar el proyecto
• Comandos de compilación, prueba y linting
• Convenciones de ingeniería y expectativas para las PRs
• Restricciones y reglas de "no hacer"
• Qué significa "listo" y cómo verificar el trabajo

El comando de barra /init en la CLI es el comando de inicio rápido para crear un AGENTS.md básico en el directorio actual. Es un excelente punto de partida, pero debes editar el resultado para que coincida con la forma en que tu equipo realmente compila, prueba, revisa y publica código.

Puedes crear archivos AGENTS.md en varios niveles: un AGENTS.md global para valores predeterminados personales que se encuentra en ~/.codex, un archivo a nivel de repositorio para estándares compartidos, y archivos más específicos en subdirectorios para reglas locales. Si hay un archivo más específico más cercano a tu directorio actual, esa orientación prevalece.

Mantenlo práctico. Un AGENTS.md corto y preciso es más útil que un archivo largo lleno de reglas vagas. Empieza con lo básico, luego añade nuevas reglas solo después de notar errores repetidos.

Si AGENTS.md empieza a ser demasiado grande, mantén el archivo principal conciso y referencia archivos markdown específicos de la tarea para cosas como planificación, revisión de código o arquitectura.

Consejo

: Cuando Codex cometa el mismo error dos veces, pídele una retrospectiva y actualiza AGENTS.md. La orientación se mantiene práctica y basada en fricciones reales.

Sitio web de AGENTS.md

4. Obtén un comportamiento más consistente configurando Codex para que coincida con tu flujo de trabajo

La configuración es una de las principales formas de hacer que Codex se comporte de manera más consistente entre sesiones y superficies. Por ejemplo, puedes establecer valores predeterminados para la elección del modelo, el esfuerzo de razonamiento, el modo sandbox, la política de aprobación, los perfiles y la configuración de MCP.

Un buen patrón de inicio es:

• Mantener los valores predeterminados personales en ~/.codex/config.toml (Configuración → Configuración → Abrir config.toml desde la aplicación Codex)
• Mantener el comportamiento específico del repositorio en .codex/config.toml
• Usar anulaciones de línea de comandos solo para situaciones puntuales (si usas la CLI)

Config.toml es donde defines preferencias duraderas como servidores MCP, perfiles, configuración multiagente y funciones experimentales. Puedes editarlo directamente o pedirle a Codex que lo actualice por ti.

Codex viene con sandboxing a nivel de sistema operativo y tiene dos parámetros clave que puedes controlar. El modo de aprobación determina cuándo Codex te pide permiso para ejecutar un comando, y el modo sandbox determina si Codex puede leer o escribir en el directorio y a qué archivos puede acceder el agente.

Si eres completamente nuevo en los agentes de codificación, la recomendación es empezar de forma conservadora con permisos predeterminados. Mantén la aprobación y el sandboxing estrictos por defecto, y solo relaja los permisos para repositorios de confianza o flujos de trabajo específicos una vez que la necesidad sea clara.

Ten en cuenta que la CLI, el IDE y la aplicación Codex comparten las mismas capas de configuración. Obtén más información en nuestra página de documentación de configuración de ejemplo.

Consejo

: Configura Codex para tu entorno real desde el principio. Muchos problemas de calidad son en realidad problemas de configuración, como el directorio de trabajo incorrecto, falta de acceso de escritura, valores predeterminados de modelo incorrectos o herramientas y conectores faltantes.

5. Mejora la fiabilidad haciendo que Codex pruebe, valide y revise el trabajo

No te limites a pedirle a Codex que haga un cambio. Pídele que cree pruebas cuando sea necesario, ejecute las comprobaciones pertinentes, valide el resultado y revise el trabajo antes de que lo aceptes.

Codex puede hacer este ciclo por ti, pero solo si sabe cómo se ve "bien". Esa orientación puede provenir de la instrucción o de AGENTS.md.

Eso puede incluir:

• Escribir o actualizar pruebas para el cambio
• Ejecutar los conjuntos de pruebas adecuados
• Verificar linting, formato o comprobaciones de tipos
• Confirmar que el comportamiento final coincide con la solicitud
• Revisar el diff en busca de errores, regresiones o patrones arriesgados

Consejo:

Activa el panel de diferencias en la aplicación Codex para

revisar cambios localmente. Haz clic en una fila específica para proporcionar comentarios que se alimenten como contexto en el siguiente turno de Codex.

Una opción útil aquí es el comando de barra /review, que te ofrece varias formas diferentes de revisar código:

• Revisar contra una rama base para una revisión tipo PR
• Revisar cambios no confirmados
• Revisar un commit
• Usar instrucciones de revisión personalizadas

Si tú y tu equipo tenéis un archivo code_review.md que se referencia en AGENTS.md, Codex puede seguir esa orientación durante la revisión también. Este es un patrón sólido para equipos que quieren que el comportamiento de revisión se mantenga consistente entre repositorios y colaboradores.

Codex no debería solo generar código. Con las instrucciones adecuadas, también puede ayudar a probarlo, validarlo y revisarlo.

Si usas GitHub Cloud, puedes configurar fácilmente Codex para que ejecute revisiones de código para tus PRs. En OpenAI, hacemos que Codex revise el 100 % de las PRs. Tienes la opción de habilitar revisiones automáticas o que Codex revise de forma reactiva cuando lo menciones con @Codex.

/review en Codex CLI

6. Lleva herramientas externas y contexto en vivo a Codex con MCPs

Usa MCPs cuando el contexto que Codex necesita esté fuera del repositorio. Permite que Codex se conecte a las herramientas y sistemas que ya usas, para que no tengas que estar copiando y pegando información en vivo en las instrucciones.

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

Usa MCP cuando:

• El contexto necesario esté fuera del repositorio
• Los datos cambien con frecuencia
• Quieras que Codex use una herramienta en lugar de depender de instrucciones pegadas
• Necesites una integración repetible entre usuarios o proyectos

Codex admite servidores STDIO y HTTP Streamable con OAuth.

En la aplicación Codex, ve a Configuración → Servidores MCP para ver servidores personalizados y recomendados. A menudo, Codex puede ayudarte a instalar los servidores necesarios. Todo lo que tienes que hacer es pedírselo. También puedes usar el comando codex mcp add en la CLI para añadir tus servidores personalizados con un nombre, URL e información adicional.

Consejo

: Añade herramientas solo cuando desbloqueen un flujo de trabajo real. No empieces conectando todas las herramientas que usas. Empieza con una o dos herramientas que eliminen claramente un bucle manual que ya haces a menudo, y luego expande desde ahí.

Gestión de servidores MCP

7. Convierte flujos de trabajo repetitivos en habilidades reutilizables

Una vez que un flujo de trabajo se vuelve repetitivo, deja de depender de instrucciones largas o de idas y vueltas constantes. Usa una Habilidad para empaquetar las instrucciones en un archivo SKILL.md, el contexto y la lógica de apoyo que Codex debe aplicar de manera consistente. Las habilidades funcionan en la CLI, la extensión del IDE y la aplicación Codex.

Mantén cada habilidad estrictamente enfocada en un trabajo. Empieza con 2 o 3 casos de uso concretos, define entradas y salidas claras, y escribe la descripción de manera que diga claramente qué hace la habilidad y cuándo usarla. Incluye el tipo de frases desencadenantes que un usuario diría realmente.

No intentes cubrir todos los casos extremos desde el principio. Empieza con una tarea representativa, haz que funcione bien, luego convierte ese flujo de trabajo en una habilidad y mejórala a partir de ahí. Incluye scripts o recursos adicionales solo cuando mejoren significativamente la fiabilidad.

Una buena regla general: si sigues reutilizando la misma instrucción o corrigiendo el mismo flujo de trabajo, probablemente debería convertirse en una habilidad.

Las habilidades son especialmente útiles para trabajos recurrentes como:

• Clasificación de registros
• Redacción de notas de versión
• Revisión de PRs contra una lista de verificación
• Planificación de migraciones
• Resúmenes de telemetría o incidentes
• Flujos de depuración estándar

La habilidad $skill-creator es el mejor lugar para empezar a crear la primera versión de una habilidad, y usar la habilidad $skill-installer para instalarla localmente. Una de las partes más importantes de una habilidad es la descripción. Debe decir claramente qué hace la habilidad y cuándo usarla.

Consejo

: Las habilidades personales se almacenan en

$HOME /.agents/skills, y las habilidades compartidas del equipo se pueden incluir en .agents/skills dentro de un repositorio. Esto es especialmente útil para incorporar nuevos miembros al equipo.

Creación e instalación de habilidades

Interfaz de habilidades de la aplicación Codex

8. Ahorra tiempo en trabajos recurrentes con automatizaciones

Una vez que un flujo de trabajo es estable, puedes programar Codex para que lo ejecute en segundo plano por ti. En la aplicación Codex, las automatizaciones te permiten elegir el proyecto, la instrucción, la cadencia y el entorno de ejecución para una tarea recurrente.

Una vez que una tarea se vuelve repetitiva para ti, puedes crear fácilmente una automatización en la pestaña Automatizaciones de la aplicación Codex. Puedes elegir en qué proyecto se ejecuta, la instrucción que ejecuta (puedes invocar habilidades) y la cadencia con la que se ejecutará. También puedes elegir si la automatización se ejecuta en un árbol de trabajo de git dedicado o en tu entorno local. Obtén más información sobre los árboles de trabajo de git.

Buenos candidatos incluyen:

• Resumir commits recientes
• Escanear en busca de posibles errores
• Redactar notas de versión
• Revisar fallos de CI
• Producir resúmenes diarios
• Ejecutar flujos de trabajo de análisis repetibles en un horario

Una regla útil es que las habilidades definen el método, las automatizaciones definen el horario. Si un flujo de trabajo aún necesita mucha dirección, conviértelo primero en una habilidad. Una vez que sea predecible, la automatización se convierte en un multiplicador de fuerza.

Consejo

: Usa las automatizaciones para la reflexión y el mantenimiento, no solo para la ejecución. Revisa sesiones recientes, resume la fricción repetida y mejora las instrucciones, la orientación o la configuración del flujo de trabajo con el tiempo.

Creación de automatizaciones en la aplicación Codex

9. Mantente organizado en trabajos de larga duración con controles de sesión

Las sesiones de Codex no son solo un historial de chat. Son hilos de trabajo que acumulan contexto, decisiones y acciones con el tiempo, por lo que gestionarlos bien tiene un gran impacto en la calidad.

Gestionar múltiples hilos es más fácil en la interfaz de la aplicación Codex, con la capacidad de fijar hilos y crear árboles de trabajo. Pero si usas la CLI, estos comandos de barra son especialmente útiles:

• /experimental para activar funciones experimentales y añadirlas a tu config.toml
• /resume para reanudar una conversación guardada
• /fork para crear un nuevo hilo mientras se conserva la transcripción original
• /compact cuando el hilo se está alargando y quieres una versión resumida del contexto anterior. Ten en cuenta que Codex compacta automáticamente las conversaciones por ti
• /agent cuando estás ejecutando múltiples agentes y quieres cambiar entre el hilo del agente activo
• /theme para elegir un tema de resaltado de sintaxis
• /apps para usar aplicaciones de ChatGPT directamente en Codex
• /status para inspeccionar el estado actual de la sesión

Mantén un hilo por unidad de trabajo coherente. Si el trabajo sigue siendo parte del mismo problema, a menudo es mejor permanecer en el mismo hilo porque conserva la cadena de razonamiento. Haz un fork solo cuando el trabajo realmente se ramifique.

Consejo

:

Usa los flujos de trabajo

multiagente de Codex para delegar trabajo acotado del hilo principal. Mantén el agente principal enfocado en el problema central, y usa subagentes para tareas como exploración, pruebas o clasificación.

10. Errores comunes a evitar

Algunos errores comunes que debes evitar al usar Codex por primera vez:

• Sobrecargar la instrucción con reglas duraderas en lugar de moverlas a AGENTS.md o a una habilidad
• No dejar que el agente vea su trabajo al no dar detalles sobre cómo ejecutar mejor los comandos de compilación y prueba
• Saltarse la planificación en tareas complejas y de varios pasos
• Darle a Codex permiso completo sobre tu computadora antes de que el flujo de trabajo esté entendido
• Ejecutar múltiples hilos en vivo sobre los mismos archivos sin usar árboles de trabajo de git
• Convertir una tarea recurrente en una automatización antes de que sea confiable manualmente
• Usar Codex en paralelo con tu propio trabajo en lugar de tratarlo como algo que tienes que supervisar paso a paso

Lista de verificación para empezar

1. Dale a Codex el objetivo, contexto, restricciones y criterio de "listo" adecuados
2. Para tareas difíciles, pídele a Codex que planifique primero
3. Crea un AGENTS.md inicial
4. Dile a Codex cómo compilar, probar, validar y revisar
5. Establece valores de configuración predeterminados que coincidan con tu flujo de trabajo
6. Añade MCP para herramientas externas de alto valor
7. Convierte flujos de trabajo repetitivos en habilidades
8. Usa automatizaciones una vez que un flujo de trabajo sea estable

Cuanto más conviertas tu flujo de trabajo, estándares y contexto en algo que Codex pueda usar, más verás lo que el agente puede realmente hacer. ¡Empieza hoy!