Mejores prácticas de prompts de Codex

Domina las técnicas de prompts para que Codex comprenda tu intención con mayor precisión y complete tareas de manera eficiente.


Estructura básica de un prompt

Un buen prompt incluye los siguientes elementos:

Elementos básicos

ElementoDescripciónEjemplo
Descripción de la tareaQué quieres hacer"Implementar la funcionalidad de inicio de sesión de usuario"
ContextoInformación de antecedentes relevante"Usar el módulo auth existente"
RestriccionesRestricciones y requisitos"Debe ser compatible con la API existente"
Resultado esperadoResultado concreto"Devolver token JWT"

Prompts estructurados

Ejemplo de prompt completo

# Descripción de la tarea
Implementar un endpoint de API para inicio de sesión de usuario

# Contexto
- El proyecto usa el framework FastAPI
- El módulo auth existente maneja la lógica de autenticación
- La base de datos usa PostgreSQL

# Restricciones
- Usar la herramienta JWT existente para generar el token
- Verificar la contraseña con bcrypt
- Se deben agregar registros de solicitudes

# Resultado esperado
- Ruta: POST /api/auth/login
- Cuerpo de la solicitud: {"email": "...", "password": "..."}
- Respuesta exitosa: {"token": "...", "user": {...}}
- Respuesta de error: {"error": "..."}

Principios de desglose de tareas

Las tareas complejas deben desglosarse en pasos pequeños y completarse gradualmente.

Principios de desglose

  • Cada paso tiene un objetivo claro
  • Las dependencias entre pasos son claras
  • Verificar el resultado al completar cada paso
  • Se puede retroceder si surgen problemas

Ejemplo de desglose

Desglose de tareas

# Tarea grande
"Implementar un sistema completo de autenticación de usuarios"

# Desglosar en tareas pequeñas
Paso1:"Diseñar la estructura de datos del sistema de autenticación, incluyendo la tabla de usuarios y la tabla de tokens"
Paso2:"Implementar la funcionalidad de registro de usuarios, incluyendo cifrado y verificación de contraseña"
Paso3:"Implementar la funcionalidad de inicio de sesión, generando un token JWT"
Paso4:"Implementar el middleware de verificación de tokens"
Paso5:"Implementar la funcionalidad de cierre de sesión de usuario"
Paso6:"Escribir las pruebas del sistema de autenticación"
Paso7:"Actualizar la documentación de la API"

Usar el modo /plan puede ayudar a Codex a desglosar automáticamente tareas complejas.


Proporcionar información de contexto

Un contexto suficiente permite que Codex comprenda con mayor precisión el estado del proyecto.

Contexto clave

TipoDescripciónCuándo proporcionarlo
Stack tecnológicoFramework, lenguaje, versiones de bibliotecasPrimera tarea o módulo nuevo
Estructura del proyectoUbicación de módulos, convenciones de nomenclaturaCuando implica modificar varios archivos
Código existenteFunciones, clases, módulos relevantesCuando se necesita compatibilidad o extensión
RestriccionesRequisitos de compatibilidad y rendimientoCuando hay limitaciones especiales

Formas de proporcionar contexto

Proporcionar contexto

# Descripción directa
"El proyecto usa Django 4.2, la base de datos es PostgreSQL 15"

# Referenciar código existente
"Consulta la lógica de validación de src/utils/validator.py"

# Especificar archivos
"Modifica src/api/users.py, manteniendo un estilo coherente con las demás API"

# AGENTS.md se proporciona automáticamente
Crea un archivo AGENTS.md; Codex leerá automáticamente las normas del proyecto

Manejo de mensajes de error

Codex puede localizar rápidamente problemas a partir del mensaje de error.

Proporcionar el mensaje de error completo

Manejo de errores

# Proporcionar el error completo
"Se produjo un error al ejecutar las pruebas:

AssertionError: Expected status 200 but got 500
  at test_login.py:45
  in test_successful_login
  Full traceback:
  ...

Analiza la causa y corrígelo"


# Ayuda con capturas de pantalla
Adjunta capturas de pantalla del error; Codex puede verlas directamente

Elementos del mensaje de error

  • Tipo de error y mensaje
  • Traza de pila completa
  • Condición que lo desencadenó (qué operación se realizó)
  • Resultado esperado vs. resultado real

Entrada de imágenes

Codex admite entrada de imágenes, ideal para transmitir información visual.

Escenarios aplicables

EscenarioDescripción
Captura de errorCaptura que muestra la interfaz de error o los registros
Diseño (mockup)Convertir el diseño de UI en código
Diagrama de arquitecturaExplicar el diagrama de arquitectura e implementarlo
Gráficos de datosAnalizar los datos de los gráficos

Formas de entrada de imágenes

Uso de imágenes

# CLI
codex -i screenshot.png
codex --image design.png "Implementa la página según el diseño (mockup)"

# App/IDE
Pega o arrastra la imagen directamente a la zona de conversación

# Varias imágenes
codex -i img1.png -i img2.png "Compara las diferencias entre estos dos diseños"

Optimización iterativa

Mejora gradualmente la calidad del código mediante iteraciones.

Proceso iterativo

  1. Codex realiza una implementación inicial
  2. Revisar el resultado y proponer mejoras
  3. Codex se ajusta según los comentarios
  4. Verificar el efecto de las mejoras
  5. Repetir hasta quedar satisfecho

Optimización iterativa

# Implementación inicial
"Implementa una API de lista de usuarios con soporte de paginación"

# Revisar y proponer mejoras
"Agrega funcionalidad de ordenación, que permita ordenar por fecha de creación"

# Continuar optimizando
"Agrega funcionalidad de búsqueda, que permita buscar por nombre de usuario"

# Optimización de rendimiento
"Optimiza el rendimiento de las consultas, agrega índices"

Evitar ambigüedad

Los prompts claros reducen malentendidos y retrabajo.

Ejemplo de ambigüedad

Evitar ambigüedad

# Prompt ambiguo (malo)
"Modifica esa función"

# Prompt claro (bueno)
Modifica la función `format_date` en `src/utils/helper.py`

# Prompt vago (malo)
"Hazlo más rápido"

# Prompt específico (bueno)
"Optimiza la función `query_users` para reducir el tiempo de consulta de 500 ms a menos de 100 ms"

# Prompt vago (malo)
"Añade una funcionalidad"

# Prompt específico (bueno)
"Agrega una funcionalidad de eliminación por lotes en la API de usuarios, que reciba una lista de IDs de usuario"

Uso de ejemplos de referencia

Proporciona código o documentación de referencia para ayudar a Codex a entender el estilo esperado.

Proporcionar referencias

# Referencia al estilo de código existente
"Usa como referencia el estilo de `src/api/products.py` para implementar la API de usuarios"

# Documentación de referencia
"Implementa según el documento de especificación OpenAPI `docs/api-spec.yaml`"

# Ejemplo de referencia
"Devuelve la respuesta con este formato:"
{
  'success': true,
  'data': {...},
  'message': '...'
}"


Plantillas comunes de prompts

Plantilla de desarrollo de funciones

Desarrollo de funciones

En [ruta del módulo], agrega la funcionalidad [nombre de la funcionalidad]

Requisitos:
- Usa [tecnología/biblioteca]
- Compatible con [sistema existente]
- Incluye [manejo de casos límite]
- Devuelve [formato de respuesta]

Referencia: [ruta de funcionalidad existente similar]

Plantilla de corrección de errores (Bug)

Corrección de errores

Descripción del problema: [comportamiento del bug]

Condiciones de activación: [cuándo ocurre]

Mensaje de error:
[Stack trace completo]

Comportamiento esperado: [cuál debería ser el resultado correcto]

Por favor, analiza la causa y arréglalo sin afectar otras funcionalidades.

Plantilla de revisión de código

Revisión de código

/review [Alcance] for [Puntos clave]

# Ejemplo
/review src/auth/ for security issues
/review HEAD~5..HEAD for performance regressions

Resumen de mejores prácticas

Principios fundamentales

  • Sé claro y específico, evita expresiones vagas.
  • Proporciona contexto suficiente
  • Divide y ejecuta tareas complejas
  • Itera y optimiza, mejora progresivamente.
  • Verifica los resultados para asegurar que sean correctos.

Trucos de eficiencia

  • Usa `AGENTS.md` para reducir instrucciones repetitivas.
  • Aprovecha Skills para encapsular prompts comunes.
  • Usa imágenes para transmitir información visual.
  • Proporciona la información de error completa.

Preguntas frecuentes

P: ¿Qué hago si Codex me entiende mal?

Proporciona una descripción más clara, agrega contexto o usa ejemplos de referencia.

P: ¿Cómo lograr que Codex siga las normas del proyecto?

Crea un archivo `AGENTS.md` que defina las normas; Codex las seguirá automáticamente.

P: ¿Cómo manejar tareas complejas?

Usa el modo `/plan` para elaborar un plan, ejecuta paso a paso y verifica.

P: ¿Qué limitaciones tiene la entrada de imágenes?

Se admiten formatos PNG, JPG y WebP; se recomienda una resolución moderada (ni demasiado pequeña ni demasiado grande).

Otras extensiones