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 de uso único y más como un compañero de equipo que configuras y mejoras con el tiempo.
Un modelo mental útil es: empieza con el contexto de tarea correcto, usa AGENTS.md para orientación duradera, configura Codex para que coincida con tu flujo de trabajo, conecta sistemas externos con MCP, convierte el trabajo repetido en habilidades y automatiza los flujos de trabajo estables.
1. Prepara Codex para un primer uso sólido con contexto claro y prompts
Codex ya es lo suficientemente potente como para ser útil incluso cuando tu prompt no es perfecto. A menudo puedes darle un problema difícil con una configuración mínima y aun así obtener un buen resultado. Un prompting claro no es necesario 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 deseas que haga.
Un buen punto de partida es incluir cuatro cosas en tu prompt:
- Objetivo: ¿Qué estás tratando de cambiar o construir?
- Contexto: ¿Qué archivos, carpetas, documentos, ejemplos o errores son relevantes para esta tarea? Puedes mencionar ciertos archivos con @ como contexto.
- Restricciones: ¿Qué estándares, arquitectura, requisitos de seguridad o convenciones debe seguir Codex?
- Finalizado cuando: ¿Qué debe ser cierto antes de que la tarea esté completa, como que las pruebas pasen, el comportamiento cambie o un error esté corregido?
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 lo que mejor funcione para tu flujo de trabajo. Diferentes usuarios y tareas se benefician de diferentes configuraciones.
- Bajo para tareas más 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 comenzando con algunos logros básicos, como hacerle preguntas a Codex sobre la base de código o usarlo para hacer una pequeña corrección bien definida. Recomiendo encarecidamente usar el dictado por voz en la aplicación Codex para acelerar las iteraciones.
Esfuerzos de razonamiento de Codex
2. Reduce errores en tareas difíciles pidiéndole a Codex que planifique primero
Si la tarea es compleja, ambigua o difícil de describir con claridad, pídele a Codex que planifique antes de empezar a codificar.
Hay algunas formas buenas de hacerlo:
Usa 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 que Codex recopile contexto, haga preguntas aclaratorias y construya un plan más sólido antes de la implementación. Actívalo con /plan o Shift+Tab.
Pídele 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 la orientación exitosa sea reutilizable con AGENTS.md
Una vez que un patrón de prompt 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 simple y abierto que se carga en el contexto automáticamente y es el mejor lugar para codificar cómo tú y tu equipo quieren que Codex funcione en un repositorio.
Un buen AGENTS.md generalmente cubre:
- Diseño del repositorio y directorios importantes
- Cómo ejecutar el proyecto
- Comandos de compilación, prueba y lint
- Convenciones de ingeniería y expectativas de PR
- Restricciones y reglas de no hacer
- Qué significa "finalizado" 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 inicial 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 construye, prueba, revisa y envía 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. Comienza con lo básico, luego agrega nuevas reglas solo después de notar errores repetidos.
Si AGENTS.md comienza 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 en todas las 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 inicial es:
- Mantén los valores predeterminados personales en ~/.codex/config.toml (Configuración → Configuración → Abrir config.toml desde la aplicación Codex)
- Mantén el comportamiento específico del repositorio en .codex/config.toml
- Usa 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 de múltiples agentes 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 controles clave que puedes gestionar. El modo de aprobación determina cuándo Codex pide tu 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 comenzar de manera conservadora con permisos predeterminados. Mantén la aprobación y el sandboxing ajustados por defecto, luego afloja los permisos solo para repositorios de confianza o flujos de trabajo específicos una vez que la necesidad esté 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 permisos 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, que ejecute las comprobaciones relevantes, que valide el resultado y que revise el trabajo antes de que lo aceptes.
Codex puede hacer este ciclo por ti, pero solo si sabe cómo se ve "bueno". Esa orientación puede provenir del prompt o de AGENTS.md.
Eso puede incluir:
- Escribir o actualizar pruebas para el cambio
- Ejecutar las suites de pruebas adecuadas
- Verificar lint, formato o comprobaciones de tipos
- Confirmar que el comportamiento final coincida 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 alimentarán como contexto para 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 estilo PR
- Revisar cambios no confirmados
- Revisar un commit
- Usar instrucciones de revisión personalizadas
Si tú y tu equipo tienen 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 en todos los repositorios y contribuyentes.
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, Codex revisa el 100% de los PRs. Tienes la opción de habilitar revisiones automáticas o hacer que Codex revise de forma reactiva cuando lo menciones con @Codex.
/review en Codex CLI
6. Trae 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 seguir copiando y pegando información en vivo en los prompts.
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 necesitas hacer es pedírselo. También puedes usar el comando codex mcp add en la CLI para agregar tus servidores personalizados con un nombre, URL y cualquier información adicional.
Consejo
: Agrega herramientas solo cuando desbloqueen un flujo de trabajo real. No empieces conectando todas las herramientas que usas. Comienza con una o dos herramientas que claramente eliminen un bucle manual que ya haces a menudo, luego expande desde allí.
Gestión de servidores MCP
7. Convierte flujos de trabajo repetidos en habilidades reutilizables
Una vez que un flujo de trabajo se vuelve repetitivo, deja de depender de prompts largos o de idas y vueltas constantes. Usa una Skill para empaquetar las instrucciones en un archivo SKILL.md, contexto y lógica de soporte que Codex deba 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 una tarea. Comienza 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 los tipos de frases de activación que un usuario diría realmente.
No intentes cubrir todos los casos extremos desde el principio. Comienza con una tarea representativa, haz que funcione bien, luego convierte ese flujo de trabajo en una habilidad y mejora desde allí. Incluye scripts o activos adicionales solo cuando mejoren significativamente la fiabilidad.
Una buena regla general: si sigues reutilizando el mismo prompt o corrigiendo el mismo flujo de trabajo, probablemente debería convertirse en una habilidad.
Las habilidades son especialmente útiles para trabajos recurrentes como:
- Triage 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 agregar a .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, el prompt, la cadencia y el entorno de ejecución para una tarea recurrente.
Cuando 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, el prompt 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 worktree de git dedicado o en tu entorno local. Obtén más información sobre git worktrees.
Buenos candidatos incluyen:
- Resumir commits recientes
- Escanear en busca de posibles errores
- Redactar notas de versión
- Verificar fallos de CI
- Producir resúmenes de reuniones diarias
- 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 en una habilidad primero. Una vez que sea predecible, la automatización se convierte en un multiplicador de fuerza.
Consejo
: Usa automatizaciones para la reflexión y el mantenimiento, no solo para la ejecución. Revisa sesiones recientes, resume la fricción repetida y mejora los prompts, las instrucciones 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 posibilidad de fijar hilos y crear worktrees. Pero si estás usando la CLI, estos comandos de barra son especialmente útiles:
- /experimental para activar funciones experimentales y agregarlas a tu config.toml
- /resume para reanudar una conversación guardada
- /fork para crear un nuevo hilo manteniendo 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 quedarse en el mismo hilo porque preserva el rastro de razonamiento. Haz fork solo cuando el trabajo realmente se bifurque.
Consejo
:
Usa los flujos de trabajo
multi-agente 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 triage.
10. Errores comunes que debes evitar
Algunos errores comunes que debes evitar al usar Codex por primera vez:
- Sobrecargar el prompt 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 los comandos de compilación y prueba de la mejor manera
- Saltarse la planificación en tareas de varios pasos y complejas
- Darle a Codex permiso completo a tu computadora antes de que el flujo de trabajo esté comprendido
- Ejecutar múltiples hilos en vivo sobre los mismos archivos sin usar git worktrees
- 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
- Dale a Codex el objetivo, contexto, restricciones y "finalizado cuando" correctos
- Para tareas difíciles, pídele a Codex que planifique primero
- Crea un AGENTS.md inicial
- Dile a Codex cómo compilar, probar, validar y revisar
- Establece valores predeterminados de configuración que coincidan con tu flujo de trabajo
- Agrega MCP para herramientas externas de alto valor
- Convierte flujos de trabajo repetidos en habilidades
- 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 realmente puede hacer. ¡Empieza hoy mismo!
