10. Prompts y comunicación efectiva con Codex

Objetivo del tema

Aprender a redactar instrucciones claras para Codex CLI, estructurar prompts que guíen al agente y reutilizar plantillas según el tipo de tarea.

10.1 Por qué importa un buen prompt

Las versiones actuales de Codex combinan una TUI potente con análisis de contexto del repositorio. Un prompt bien planteado reduce iteraciones, evita comandos inesperados y facilita que los diffs se ajusten a tus expectativas.

Claridad

Describe qué quieres lograr y dónde. Evita frases ambiguas o supuestos que el agente no pueda validar.

Contexto

Incluye estado actual, restricciones y dependencias. Codex usa esa información para decidir cómo actuar.

Resultado esperado

Indica cómo validar el éxito (tests, archivos tocados, formato del output). El agente documentará los pasos.

10.2 Cómo redactar tareas claras

Piensa en el prompt como un mini-brief. La estructura sugerida en la documentación reciente de Codex es:

  • Objetivo: qué problema solucionas.
  • Alcance: carpetas, componentes o servicios involucrados.
  • Condiciones: requisitos específicos (estándares, dependencias, estilo de código).
  • Entrega: forma de validación (tests, mensajes de commit, formato de respuesta).

Ejemplo básico para iniciar una sesión:

codex --full-auto "Objetivo: agregar logging estructurado al endpoint /health.
Alcance: archivos app/main.py y tests/test_health.py.
Condiciones: usar logging.getLogger('health'), no introducir dependencias nuevas.
Entrega: ejecutar pytest -q y mostrar resumen."

Si quieres mantener el control sobre cada acción, combina el prompt con aprobaciones manuales:

codex --sandbox workspace-write --ask-for-approval on-request "Refactorizar el servicio de pagos.
Resalta los cambios propuestos y pide confirmación antes de ejecutar migraciones."

10.3 Estructura recomendada de prompts

Adapta esta plantilla cuando necesites guiar a Codex paso a paso:

Componentes sugeridos del prompt
Sección Ejemplo Notas
Situación «Tenemos una API FastAPI con endpoint /health ya desplegado» Aporta contexto previo o historia del cambio.
Objetivo «Necesito agregar validación y manejo de errores para el timestamp» Enfoca la tarea principal que esperas.
Pasos sugeridos «Revisa app/main.py, ajusta la respuesta y actualiza la prueba correspondiente» No es obligatorio, pero acelera el plan inicial del agente.
Validación «Ejecuta pytest -q y comparte el resultado» Cierra el ciclo indicando cómo verificar que todo quedó listo.
Formato «Resume los cambios en bullets breves» Controla la salida final para documentar la sesión.

Recuerda que puedes complementar con archivos AGENTS.md (global, del repositorio o del subdirectorio) para instrucciones persistentes. Codex los fusiona al inicio de cada sesión.

10.4 Plantillas reutilizables

Guarda tus prompts más usados en ~/.codex/prompts/. Un archivo bug-fix.md aparecerá como /bug-fix al escribir / en la TUI.

Historia de usuario

Objetivo:
- [ ] Construir <feature> para <persona> con <beneficio>.

Contexto:
- Stack principal: <framework / lenguaje>.
- Archivos relevantes: <ruta1>, <ruta2>.
- Reglas de diseño o negocio: <detalle>.

Entrega:
- Valida con <comando de tests>.
- Resume los cambios y su impacto en <formato deseado>.

Rellena los campos entre < > antes de enviar el prompt. Codex interpretará las listas de verificación como tareas concretas.

Reporte de bug

Situación actual:
- Entorno / rama: <detalle>.
- Pasos para reproducir:
  1. ...
  2. ...
- Resultado observado: <mensaje de error o comportamiento>.

Objetivo:
- Corregir el bug asegurando que <comportamiento esperado>.

Validación:
- Ejecuta <tests / scripts>.
- Si es necesario, agrega una prueba que falle antes de la corrección.

Cuando Codex recibe instrucciones de reproducción concretas, puede generar pruebas automáticas o sugerir diagnósticos adicionales.

Refactor incremental

Meta:
- Simplificar <clase/módulo> manteniendo compatibilidad externa.

Restricciones:
- Evitar cambios en interfaces públicas.
- Reutilizar helpers existentes si es posible.

Plan sugerido:
1. Analiza el código actual y describe oportunidades de extracción.
2. Propón un plan de refactor por etapas.
3. Implementa la primera etapa y ejecuta <comando de pruebas>.

Entrega:
- Resume riesgos pendientes y próximos pasos.

10.5 Consejos en la conversación continua

Una vez iniciada la sesión, ajusta el rumbo con mensajes breves:

  • Refuerza prioridad: «Enfócate primero en la validación de datos; luego hablamos del logging».
  • Detiene o corrige: «No ejecutes migraciones hasta que lo confirme».
  • Solicita resúmenes: «Haz un diff visual y dame bullets de cambios».

Comandos útiles en la TUI:

  • /help muestra accesos rápidos y gestión de archivos adjuntos.
  • /approvals alterna el modo de autorización en caliente.
  • /status detalla sandbox, rutas y sesión activa.
  • /resume (o codex resume --last en la terminal) retoma el contexto reciente.

Si necesitas incluir capturas o logs, pégalos directamente; Codex soporta adjuntos de texto e imágenes para enriquecer la conversación.

10.6 Conclusión

Dominar los prompts multiplica la efectividad de Codex: permite al agente comprender mejor el objetivo, planificar y registrar decisiones sin perder trazabilidad. Usa plantillas, archivos AGENTS.md y comandos de la TUI para mantener conversaciones enfocadas y productivas.

Retornar