Cómo escribir prompts: Habla al corazón de Codex
📚 Navegación de la serie: El artículo anterior 12 · Comandos de barra diagonal y atajos de teclado te enseó a colocar los dedos en el lugar correcto durante la sesión: usar
/para cambiar de modo, limpiar el contexto y ver el estado; con las teclas ya dominadas. Este artículo cambia de nivel: ahora que la mano sabe dónde presionar, la boca debe saber cómo expresarse. Para una misma necesidad, si la forma de pedirla es adecuada o no, el trabajo realizado por Codex cambiará drásticamente.
Se suele decir: "la potencia de una herramienta de programación de AI depende del modelo"; a esto tengo que oponerme.
Para ser honestos y directos: con el mismo GPT-5 y el mismo repositorio, quien sabe cómo plantear sus necesidades lo resuelve en tres frases, mientras que quien no sabe, da vueltas con cinco rondas de modificaciones y termina enfadado. El modelo ya es lo suficientemente potente; en la mayoría de los casos lo que te frena no es su inteligencia, sino la instrucción que le entregas. Si envías un mensaje con un volumen de información cercano a cero como "corrige este bug", el modelo se verá obligado a deducir: qué archivo es, qué error tiene o qué aspecto debería tener, todo basado en adivinanzas. Si adivina mal, mirarás la pantalla llena de diff murmurando "esta AI no sirve", pero la que realmente no sirve no es ella.
Yo mismo cometí este error el año pasado. Un servicio de Node devolvió un error 500 y envié un simple "la API de inicio de sesión falló, corrígela" sin adjuntar siquiera los registros. Codex estuvo buscando un largo rato, eligió un bug que creía correcto y modificó tres archivos, ninguno de los cuales era el verdadero problema; el fallo real se debía a una variable de entorno que no le mencioné, algo de lo que no tenía idea alguna. Fue entonces cuando comprendí plenamente: el límite de lo que puede hacer Codex está definido en gran medida por la forma en que planteo mis preguntas.
Por lo tanto, en este artículo no te enseñaremos a memorizar plantillas, sino a comprender una sola cosa: qué necesita saber exactamente Codex para no perder el rumbo. Cuando entiendas esto a fondo, los prompts se redactarán solos de forma natural.
Al terminar este artículo, obtendrás:
- Una tabla comparativa de "malos prompts vs buenos prompts" para que la sigas y reduzcas drásticamente la tasa de correcciones.
- Un marco de "cuatro elementos" para redactar requisitos: objetivo, alcance, restricciones y verificación; el aspecto que omitas será el que Codex se vea obligado a adivinar.
- Cómo dividir tareas grandes en pasos pequeños que Codex pueda procesar y tú puedas revisar con facilidad.
- El uso oficial del modo de objetivo
/goalpara fijar criterios de aceptación de tipo "si no cumple, no se detiene" (requiere habilitarfeatures.goalspreviamente; la sección 05 tiene los pasos detallados). - Un experimento práctico de "dos formas de pedir una misma necesidad" para comprobar visualmente la diferencia.
01 Por qué un mal prompt es tan deficiente
Analicemos el fallo del inicio. Desde la perspectiva de Codex, la frase "la API de inicio de sesión falló, corrígela" carece de información clave por completo:
- ¿Qué API de inicio de sesión? Tiene que buscar por todo el proyecto.
- ¿Cómo falló? ¿Qué error arroja o bajo qué condiciones se reproduce? No tiene idea alguna.
- ¿Cuál es el comportamiento correcto esperado? Solo le queda adivinar basándose en "cómo suele funcionar un inicio de sesión".
Como se explicó en [06 · Completar la primera tarea], el funcionamiento de Codex se basa en un bucle de agente (agent loop): invoca al modelo, lee archivos, modifica archivos y ejecuta comandos, girando en el ciclo de "pensar → hacer → observar". La descripción oficial es que "ejecuta comandos de terminal en un bucle, modificando el código, realizando comprobaciones e intentando validar su trabajo". Sin embargo, por muy inteligente que sea este ciclo, si el primer paso de "pensar" recibe información basura, todo el bucle girará en falso en la dirección equivocada.
Analogía: Escribir la dirección de entrega de un pedido. Si al hacer tu pedido solo pones "entregar en tal residencial", el repartidor tendrá que buscar a ciegas edificio por edificio, probablemente entregándolo mal o teniendo que llamarte por teléfono. Si escribes "Residencial XX, edificio 8, portal 2, piso 1503, hay un zapatero verde en la puerta", llegará con los ojos cerrados. Cuanto más precisa sea la dirección, menos rodeos dará el repartidor; cuanto más impreciso seas, más tendrá que adivinar y mayor será la probabilidad de fallar. Con las instrucciones para Codex ocurre exactamente lo mismo: la precisión de la "dirección" que proporciones define directamente si dará rodeos o no.
Veamos la lógica comparativa en la que insiste la documentación oficial, organizada en la siguiente tabla (columna izquierda para malas prácticas, columna derecha para buenas):
| Escenario | ❌ Mal prompt | ✅ Buen prompt |
|---|---|---|
| Corregir bug | "La API de inicio de sesión falló, corrígela" | "El usuario informa que al llamar a POST /api/login tras expirar la sesión devuelve un error 500. Primero escribe una prueba que falle para reproducirlo, localiza la lógica de actualización del token en src/auth/, corrígela y finalmente ejecuta la prueba para confirmar que pasa en verde" |
| Escribir pruebas | "Añadir pruebas para parser.py" | "Escribe pruebas para parse_date en parser.py, cubriendo los casos límite de cadena vacía y formato no válido, evita usar mocks y ejecuta pytest para confirmar que pasan" |
| Añadir funcionalidad | "Añade una función de exportación" | "Revisa primero cómo está implementado export_csv en report.py y añade export_json siguiendo el mismo patrón, no agregues nuevas dependencias además de las librerías ya instaladas" |
| Leer código | "¿Por qué este módulo está escrito así?" | "Revisa el historial de git del módulo transform y resume cómo su API ha evolucionado paso a paso hasta su forma actual" |
¿Ves la lógica? Un buen prompt se centra en una sola acción: proporcionarle de antemano a Codex la información que de otro modo tendría que adivinar. Si no tiene que adivinar, no perderá el rumbo.
💡 Resumen en una frase: Un mal prompt falla porque "los vacíos de información obligan a Codex a deducir", mientras que un buen prompt aclara de antemano lo que tendría que adivinar.
02 Los "cuatro elementos" para redactar requisitos: objetivo, alcance, restricciones y verificación
En la sección anterior mencionamos "proporcionarle de antemano lo que tendría que adivinar", pero ¿qué datos concretos debemos darle? No te dejes llevar por la intuición, basta con recordar un marco: el conjunto de objetivo, alcance, restricciones y verificación. Esta es la lista de verificación que he consolidado tras innumerables correcciones: repásala mentalmente antes de plantear cada requisito, ya que el aspecto que omitas será el que Codex decida por su cuenta.
Analogía: La "hoja de especificaciones" que le entregas al contratista de una obra. Un contratista confiable confirmará cuatro cosas contigo antes de empezar: qué resultado exacto buscas (objetivo), qué habitaciones modificar y cuáles no tocar (alcance), qué consideraciones especiales hay, como no derribar muros de carga (restricciones), y cómo se inspeccionará la obra terminada (verificación). Con los cuatro elementos listos, trabajará según las especificaciones y podrá completar la tarea de forma autónoma; si falta uno, tendrá que tomar una decisión basada en suposiciones, que probablemente no sea de tu agrado. Plantear requisitos a Codex es entregarle esta misma hoja de especificaciones.
拆开看这四件分别是什么、缺了会怎样： Analicemos qué representa cada uno de estos cuatro elementos y qué ocurre si faltan:
| Elemento | Pregunta a la que responde | Cómo indicarlo | Qué ocurre si falta |
|---|---|---|---|
| Objetivo (Goal) | Qué se quiere lograr | "Devolver 0 para listas vacías", "Cambiar formato de exportación a JSON" | Adivinará lo que deseas, dejando el rumbo a la suerte |
| Alcance (Scope) | Qué modificar y qué no | Nombrar archivos/funciones: "Modificar solo average en stats.py" | Buscará a ciegas en todo el proyecto y modificará otras cosas de paso |
| Restricciones (Constraint) | Qué consideraciones respetar | "No importar librerías nuevas", "Mantener compatibilidad hacia atrás", "No tocar migrations/" | Seguirá sus propias preferencias y el resultado podría no ser de tu agrado |
| Verificación (Verification) | Qué define el éxito | "Escribir dos casos de prueba y ejecutarlos", "Código de salida de compilación igual a 0" | Se detendrá cuando "sienta que está casi listo", dejándote a ti la tarea de buscar fallos |
De estos cuatro elementos, la "verificación" es el que los principiantes suelen omitir con más frecuencia, pero el que más se debe incorporar; la documentación oficial hace hincapié en esto:
Codex 在能够验证自己工作的时候，产出质量更高。把复现问题的步骤、验证功能的方式、要跑的 lint 和预提交检查都带上。 Codex genera resultados de mayor calidad cuando es capaz de validar su propio trabajo. Incluye los pasos para reproducir el problema, el método para validar la funcionalidad y los comandos de lint o comprobaciones previas a la confirmación que se deben ejecutar.
¿Por qué la verificación es tan clave? Porque si no hay comprobaciones que se puedan ejecutar, el hecho de que "parezca completado" se convierte en la única señal de Codex para detenerse. Si no estableces criterios, se detendrá según su "intuición", convirtiéndote a ti en el responsable final de la inspección y obligándote a vigilar cada fallo en persona. Pero si le proporcionas una comprobación que devuelva un resultado claro de "aprobado / fallido" (un conjunto de pruebas, un comando de lint o un código de salida de compilación), el ciclo se cerrará por sí mismo: el modelo trabaja → ejecuta la comprobación → revisa el resultado → si falla continúa modificando, sin necesidad de que te quedes vigilando.
En mi caso, ahora redacto los requisitos utilizando la ráfaga de los "cuatro elementos". El mes pasado, al añadir validación de correo electrónico a un proyecto Python, lo pedí así:
在 src/validators.py 里加一个 validate_email 函数（目标）。
只动这个文件，别碰别的（范围）。
用标准库 re 实现，别引第三方库（约束）。
写完补三个测试：user@example.com 为真、invalid 为假、user@.com 为假，
跑 pytest 确认全过（验证）。Con los cuatro elementos listos, Codex acertó a la primera: localizó el archivo, escribió la función, añadió los tres casos de prueba, los ejecutó y me mostró el resultado en verde. No tuvo que adivinar en ningún momento, porque definí estrictamente "qué hacer, qué modificar, qué usar y qué define el éxito".
💡 Resumen en una frase: Repasa mentalmente el conjunto de "objetivo, alcance, restricciones y verificación" antes de pedir algo; el aspecto que omitas será el que Codex decida por su cuenta; la "verificación" es el elemento más importante que debes añadir: al proporcionarle comprobaciones ejecutables de aprobado/fallido, el ciclo se cerrará solo.
03 Alcance y restricciones: si puedes "adjuntar" información, no la "describas"
Dentro de los cuatro elementos, el "alcance" y las "restricciones" a menudo no requieren descripciones extensas, basta con adjuntar la materia prima directamente a su alcance; dedicamos esta sección a explicar cómo hacerlo, ya que es el truco más práctico en el día a día.
La regla clave es una sola: si puedes "adjuntar", no "describas". Codex siempre comprenderá mejor los materiales originales que tu explicación de segunda mano sobre ellos.
Primero: Introduce los archivos relacionados directamente en el contexto. La documentación oficial en la sección de "Prompting" lo indica explícitamente: al enviar requisitos, proporciona el contexto que Codex pueda utilizar, como referencias a archivos e imágenes relacionados. La forma más directa es nombrar las rutas de los archivos en el prompt:
参考 src/types/user.ts 里的类型定义，给 UserService 补上类型注解Esto es diez mil veces más confiable que decir "hay un archivo de tipos de usuario en el proyecto, búscalo". Aquí hay una ventaja gratuita al usar la extensión de IDE: la documentación oficial lo detalla con claridad; la extensión de IDE incorpora automáticamente en el contexto la lista de archivos abiertos actualmente y la selección de texto activa. En otras palabras, en VS Code basta con que selecciones unas líneas con el cursor para que Codex sepa que te refieres a ellas, sin necesidad de describirlo.
Analogía: Conectar un pendrive USB vs indicarle una ubicación aproximada para que lo busque por su cuenta. Nombrar los archivos o dejar que el IDE agregue el contexto de forma automática es como insertar un "pendrive USB de datos" directamente en la mesa de trabajo de Codex: se conecta y queda listo para usar, accediendo a la información en un segundo; si solo dices "los datos están en algún armario del tercer piso, búscalo tú mismo", tendrá que revisar todo el archivo y equivocarse retrasará más la tarea. (La analogía del puerto USB de MCP en [02 Conceptos clave] se refería a "conectar capacidades externas", aquí nos referimos a "conectar datos", dos usos de un mismo concepto).
Segundo: Pega los errores completos, no los resumas. Vale la pena convertir esto en memoria muscular: si te encuentras con un traceback, no lo resumas como "arrojó un puntero nulo", pega la traza de la pila completa tal como está:
运行测试时报了这个错，帮我定位原因：
TypeError: Cannot read properties of null (reading 'userId')
at getUserProfile (src/services/user.ts:42:18)
at async ProfileController.getProfile (src/controllers/profile.ts:15:20)¿Por qué pegarla completa? Porque la traza contiene los nombres de archivo, números de línea y la cadena de llamadas completa, permitiendo que Codex se sitúe con precisión quirúrgica en user.ts:42. Si la resumes, estarás eliminando estas coordenadas clave y forzándolo a adivinar de nuevo.
Tercero: Envía imágenes para problemas visuales o de interfaz. Codex admite entradas de imágenes: puedes pegar o arrastrar una imagen directamente al área de chat; también se pueden incluir imágenes en la CLI (los parámetros de comandos específicos se rigen por la documentación oficial). Los diseños, capturas de pantalla de errores o diagramas de arquitectura siempre serán más precisos que intentar describir con texto "mueve el botón un poco a la izquierda".
Comparemos "el material que quieres dar" y "cómo proporcionarlo":
| Información que quieres dar | ❌ Describir con palabras | ✅ Proporcionar directamente |
|---|---|---|
| Contenido de un archivo | "Hay un archivo de autenticación en el proyecto" | Nombrar src/auth/session.ts en el prompt |
| Código que estás revisando | "Esa parte de la lógica" | Seleccionarlo en el IDE para que la extensión lo cargue automáticamente |
| Una traza de error | "Arrojó un error de undefined" | Pegar el traceback completo tal como está |
| Un problema de interfaz | "El botón está mal ubicado" | Adjuntar una captura de pantalla o diseño directamente |
💡 Resumen en una frase: El alcance y las restricciones casi nunca requieren descripciones extensas: nombrar archivos, seleccionar en el IDE, pegar errores completos o adjuntar capturas; si puedes "adjuntar", no "describas", ya que Codex siempre entenderá mejor la fuente original que tu interpretación.
04 Cómo dividir tareas grandes: para que Codex pueda procesarlas y tú revisarlas
El conjunto de los cuatro elementos soluciona "cómo detallar un requisito individual". Pero algunas tareas son grandes por naturaleza: "implementar un sistema completo de autenticación de usuarios" o "migrar todo el proyecto de JavaScript a TypeScript"; si le lanzas esto en un solo mensaje, Codex lo procesará de golpe y perderá el rumbo en algún rincón invisible, dejándote con una maraña de modificaciones cuando te des cuenta.
La postura oficial respecto a este tipo de tareas es muy clara:
Codex 在你把复杂工作拆成更小、更聚焦的步骤时，处理得更好。小任务对 Codex 更好测、对你更好审。要是不确定怎么拆，直接让 Codex 给你提个方案（plan）。 Codex funciona mejor cuando divides las tareas complejas en pasos más pequeños y enfocados. Las tareas pequeñas son más fáciles de probar para Codex y más sencillas de revisar para ti. Si no estás seguro de cómo dividirla, pídele directamente a Codex que te proponga un plan.
Esta afirmación tiene dos implicaciones que debes recordar. Primero: dividir el trabajo no es solo para Codex, sino también para ti; con pasos pequeños, el modelo puede probarlos fácilmente y tú puedes revisar el diff con comodidad; un cambio de unas decenas de líneas se evalúa en un vistazo, pero si son cientos de líneas en ocho archivos distintos, no tendrás forma de inspeccionarlo (el fallo que cometí al inicio se debió precisamente a aceptar sin revisar). Segundo: ¿no sabes cómo dividirlo? No lo fuerces, pídele a Codex que proponga un plan primero; esto conecta con lo explicado en [06]: "pídele propuestas para tareas grandes en lugar de dejar que empiece a modificar de inmediato".
Analogía: No puedes tragarte una vaca entera de un bocado. Por muy grande que sea tu apetito, debes cortarla en trozos: un trozo por vez, masticar y tragar, y si un trozo está en mal estado lo puedes escupir de inmediato; si intentas tragarla entera, te atragantarás y no sabrás dónde está el bloqueo. Dividir una tarea grande en pasos es como trocear esa vaca: es seguro solo cuando cada trozo es lo suficientemente pequeño como para "ver de inmediato si hay un problema".
¿Cómo dividirla? Aquí tienes una estructura de ejemplo para un "sistema de autenticación" para que aprecies el nivel de detalle:
大任务：实现完整的用户认证系统
拆成小步，一步一交付：
步骤 1：设计认证的数据结构（用户表 + token 表），先给方案我确认
步骤 2：实现注册功能（密码 bcrypt 加密），补测试跑通
步骤 3：实现登录功能（签发 JWT），补测试跑通
步骤 4：实现 token 校验中间件，补测试跑通
步骤 5：实现登出功能，补测试跑通Presta atención a dos detalles de esta división: primero, cada paso incluye su propia "verificación" (añadir pruebas y pasarlas); esta es la aplicación práctica de la "verificación" de la sección 02 en cada paso del camino; segundo, el paso 1 pide una propuesta antes de implementar: para decisiones estructurales que afectan a todo el sistema, si la dirección es errónea lo demás no servirá de nada, así que pídele el diseño primero para revisarlo; corregir un boceto es mucho más económico que derribar una pared ya construida.
Cuando no sabes cómo dividir una tarea, Codex cuenta con dos modos integrados para ayudarte, mencionados en [07], y aclaramos su propósito aquí:
/plan(modo plan): pide a Codex que explore y proponga un plan, generando una lista de ejecución antes de proceder con la implementación. Es adecuado cuando "tú mismo no tienes claro cómo abordar la tarea"; deja que estructure los pasos y, cuando estés conforme, dale luz verde.- Una indicación directa de "no modifiques nada aún": si no quieres cambiar de modo, puedes añadir una restricción en la conversación normal: "dime primero qué archivos vas a modificar y cuál es tu lógica de cambio, pero no modifiques ningún archivo en este paso".
¿Qué tareas se deben dividir y planificar con /plan y cuáles no lo necesitan? Aquí tienes un criterio de decisión:
| Tarea | Cómo abordarla |
|---|---|
| Corregir una errata, añadir una línea de log, renombrar una variable | Hazlo directamente, si puedes explicar cómo se verá el diff en una frase, no dividas ni planifiques |
| Añadir validación a una función, escribir una prueba | Un requisito simple + los cuatro elementos, se resuelve en un paso |
| Afecta a múltiples archivos, código desconocido o con gran impacto | Usa /plan primero, revisa la propuesta y autoriza la ejecución paso a paso |
| "Implementar un sistema XX completo", "Migración o refactorización total" | Divídela en 5 a 8 pasos independientes, cada uno con su verificación, y ejecútalos en orden |
El truco práctico más útil es preguntarte: "¿Puedo explicar en una sola frase cómo se verá el cambio final? Si la respuesta es sí, hazlo directamente; si te trabas, significa que la tarea es lo suficientemente compleja como para dividirla y pedirle un plan primero." Planificar con /plan para corregir una errata sería complicarse la vida sin sentido.
💡 Resumen en una frase: No intentes procesar tareas grandes de golpe: divídelas en fragmentos pequeños, cada uno con su propia verificación y fáciles de revisar; si no sabes cómo estructurarla, usa
/planpara pedirle un plan primero; al contrario, para cambios sencillos cuyo diff se explica en una frase, ejecútalos directamente sin planificar.
05 Autorizar los criterios de aceptación: el modo de objetivo /goal
En la sección 02 mencionamos que la "verificación" es lo más importante a incorporar, pero las comprobaciones en prompts normales tienen una limitación: solo aplican a "esta ronda"; Codex ejecuta la comprobación en esta ronda y, si falla, posiblemente te devuelva el control a la espera de que le insistas. Si quieres que "no se detenga hasta cumplir el estándar, modificando ronda tras ronda por su cuenta hasta lograrlo", Codex cuenta con un modo dedicado para ello: el modo de objetivo (Goal mode).
Veamos en qué se diferencia de los prompts normales. En un prompt común, el criterio de aceptación es "ejecutarlo a ver qué pasa"; con /goal, el criterio se fija como el objetivo de toda la tarea. La documentación oficial lo describe con claridad:
设目标时，目标文本同时充当起始提示和完成标准。Codex 用它决定下一步做什么、以及任务是不是完成了。 Al establecer un objetivo, el texto de este sirve como prompt inicial y como criterio de completado. Codex lo utiliza para determinar qué hacer a continuación y si la tarea se ha completado.
En otras palabras, la frase del objetivo que proporcionas define tanto "qué hacer" como "cuándo se considera terminado"; Codex realiza una comparación tras cada bloque de trabajo: si no se ha cumplido continúa trabajando, y se detiene solo cuando lo logra. Es ideal para tareas largas que constan de múltiples pasos, requieren una definición clara de éxito y permiten al modelo ir contrastando su progreso.
¿Cómo se usa? Escribe /goal en la conversación seguido de tu objetivo. La clave es redactar el objetivo de modo que "Codex pueda juzgar por sí mismo si lo logró o no"; el requisito oficial es: un buen objetivo debe incluir entregables específicos, indicadores cuantificables o criterios medibles. Veamos dos ejemplos oficiales para entenderlo:
/goal 把这个代码库从 JavaScript 迁到 TypeScript，要求在 strict 模式下编译通过，且不出现显式的 any 类型/goal 把首页的可交互时间（TTI）降到 1 秒以内¿Lo notas? "Compilación aprobada en modo strict sin usar any" o "TTI por debajo de 1 segundo": todos estos son criterios que devuelven un resultado claro de "sí / no". Al contrario, si escribes "código de alta calidad" o "mejor experiencia de usuario", al no ser medibles objetivamente, el modo de objetivo no podrá ayudarte a cerrar la tarea, ya que no sabrá si se cumplió o no.
Algunos detalles prácticos al usar /goal para evitar cometer errores:
- ¿No aparece
/goalen la lista? Requiere activar un interruptor de funciones. El método oficial: escribegoals = truebajo la sección[features]en~/.codex/config.toml, o ejecuta directamentecodex features enable goals(también puedes pedirle a Codex que lo ejecute por ti).
# ~/.codex/config.toml
[features]
goals = true- ¿Te cuesta definir el objetivo al principio? La recomendación oficial: si el objetivo es difícil de definir al inicio, usa
/planprimero para dejar que Codex te ayude a aclararlo, y luego conviértelo en el objetivo; incluso puedes pedirle que te "entreviste" para redactar un objetivo con criterios de éxito claros. - El objetivo se puede reorientar sobre la marcha. No queda bloqueado una vez establecido: puedes enviar mensajes a mitad de camino para añadir restricciones ("usa esta librería en su lugar" o "no vayas por ese camino"); si quieres ver el progreso sin interrumpir el flujo principal, usa el chat lateral (side chat) para pedirle un informe.
- ¿Te preocupa perder la conexión en tareas largas? Advertencia oficial: para objetivos que tardan mucho tiempo en ejecutarse, pausa la ejecución antes de desconectarte de la red, y reanúdala o edítala cuando recuperes la conexión.
Comparemos los criterios de verificación de los prompts comunes frente al modo /goal para saber cuál usar en cada caso de un vistazo:
| Verificación en prompt común | Modo de objetivo /goal | |
|---|---|---|
| Duración | Solo para esta ronda, devolviendo el control al terminar | Para toda la tarea, no se detiene hasta cumplir el objetivo |
| Adecuado para | Requisitos simples de uno o dos pasos | Tareas largas con múltiples pasos que requieren una definición clara de éxito |
| Redacción del criterio | "Escribir dos pruebas y pasarlas" | Redactado como un "sí / no" medible y cuantificable |
| Habilitar interruptor | No es necesario | Requiere features.goals = true |
💡 Resumen en una frase: Si quieres que Codex "no se detenga hasta cumplir el estándar, modificando paso a paso por su cuenta", usa el modo de objetivo
/goal: el objetivo debe redactarse como un criterio medible de sí/no; si te cuesta definirlo usa/planprimero y recuerda activarfeatures.goals.
06 Manos a la obra: dos formas de pedir un mismo requisito para ver la diferencia
La teoría no es suficiente, hagamos un pequeño experimento para comprobar la diferencia con nuestros propios ojos. Solo necesitas preparar un archivo de prueba de tres líneas, sin depender de ningún proyecto existente.
Nota sobre diferencias de plataforma: los comandos de creación de directorios
mkdirse usan directamente en Mac / Linux; en Windows ejecutamkdir/cdigual y crea un nuevo archivostats.pycon el Bloc de notas para pegar las dos líneas y guardarlo.
Primer paso: Crear un archivo de prueba con un "fallo" (Mac / Linux)
mkdir prompt-demo
cd prompt-demo
echo 'def average(nums):
return sum(nums) / len(nums)' > stats.pyEsta función tiene una trampa: si se le pasa una lista vacía [], len(nums) será 0, lo cual provocará un error de división por cero. La utilizaremos como nuestro campo de pruebas.
Segundo paso: Iniciar Codex en el directorio del proyecto
codexResultado esperado: aparece la interfaz de usuario de Codex, con el cuadro de entrada y el cursor en la parte inferior. (Si no se inicia o te pide iniciar sesión, regresa a [03 Instalación y sesión]).
⚠️ Debes iniciar
codexobligatoriamente dentro del directorioprompt-demo, no lo hagas en el escritorio o en el directorio principal: Codex toma el directorio donde lo inicias como su espacio de trabajo y leerá el contenido de allí.
第三步：先用「烂提问」，感受它怎么脑补Tercer paso: Usar un "mal prompt" primero para ver cómo adivina
@stats.py 帮我改改这个函数Resultado esperado: es muy probable que Codex "adivine" lo que quieres hacer: quizás añada anotaciones de tipo o un docstring, pero no sabrá que lo que realmente te interesa es solucionar la caída por la lista vacía, dejando la dirección a la suerte. Este es el precio de omitir el objetivo y la verificación: el modelo está tomando las decisiones por ti.
第四步：换「好提问」——四件套全上Cuarto paso: Cambiar a un "buen prompt" con los cuatro elementos
@stats.py 里的 average 函数有个 bug：传入空列表时会因为除以零而崩溃。
期望行为是空列表返回 0（目标）。
只改这个函数，别动别的（范围）；用纯 Python 实现，别引库（约束）。
帮我修，并补一个测试：average([]) 应返回 0、average([2, 4]) 应返回 3，
写完跑一遍确认通过（验证）。Resultado esperado: esta vez la secuencia de acciones de Codex es clarísima: localiza el caso de la lista vacía → añade la validación para devolver 0 → escribe los dos casos de prueba que especificaste → ejecuta las pruebas → te muestra el resultado aprobado. Ya no tiene que adivinar lo que deseas, porque definiste de forma estricta "qué hacer, qué modificar, qué usar y qué define el éxito".
第五步：退出，看改动落没落地Quinto paso: Salir y comprobar si los cambios se aplicaron
Sal de Codex (la tecla de salida se indica en la pantalla) y revisa el archivo en la terminal:
cat stats.py(En Windows PowerShell usa type stats.py)
Resultado esperado: en stats.py aparece la validación de la lista vacía (como if not nums: return 0). Coincide con lo solicitado en el cuarto paso = has desarrollado la intuición para comunicarte con claridad.
Al colocar ambos prompts frente a frente, la diferencia es evidente:
| Tercer paso ❌ Mal prompt | Cuarto paso ✅ Buen prompt | |
|---|---|---|
| Objetivo | Sin definir, el modelo lo decide | Devolver 0 para listas vacías, definido estrictamente |
| Alcance | Sin definir, busca en todo el archivo | Nombrar la función average |
| Restricciones | Sin definir, introduce dependencias libremente | Python puro sin importar librerías |
| Verificación | Sin definir, se detiene según su intuición | Dos casos de prueba + ejecución |
| Tu experiencia | Revisas el diff preguntándote "esto no es lo que quería" | Sigue tu guión a la perfección a la primera |
💡 Resumen en una frase: Para un mismo archivo y un mismo bug, un mal prompt deja que Codex deicda por ti, mientras que uno bueno define estrictamente el objetivo, alcance, restricciones y verificación; completar estos pasos por ti mismo es mucho más ilustrativo que leer la teoría diez veces.
07 Resumen en un diagrama: del requisito a la implementación
Conectemos la lógica de este artículo en un diagrama: desde que expresas el requisito hasta que Codex completa el trabajo, este es el flujo de ejecución:
En este diagrama debes prestar atención a dos bifurcaciones clave: primero, "¿es grande la tarea?": para tareas complejas divídelas y usa /plan primero, no las envíes de golpe; segundo, "¿cuenta con comprobaciones ejecutables?": al proporcionar una comprobación de aprobado/fallido, el ciclo se cerrará solo; si no la das, se detendrá según su intuición y te dejará a ti la tarea de validación. Al tomar la decisión correcta en estas dos bifurcaciones, tu colaboración con Codex fluirá con normalidad.
💡 Resumen en una frase: La ruta correcta para un requisito es "dividir tareas grandes o usar
/plan→ detallar los cuatro elementos → dar verificaciones ejecutables para cerrar el ciclo → revisar diff para aplicar"; lo que te frena casi nunca es el modelo, sino si has completado estos pasos adecuadamente.
08 Resumen
Este artículo se ha centrado en un solo tema: cómo redactar tus requisitos para que Codex pueda recibirlos y ejecutarlos con precisión.
Para cerrar, si no puedes memorizarlo todo, quédate con esta tabla:
| Técnica | Resumen | Cómo aplicarla |
|---|---|---|
| Los cuatro elementos | Objetivo, alcance, restricciones y verificación; lo que omitas será lo que el modelo decida por su cuenta | "Modifica average (alcance), devuelve 0 para listas vacías (objetivo), no importes librerías (restricciones) y añade dos pruebas que pasen (verificación)" |
| Adjuntar antes que describir | Proporcionar datos de alcance y restricciones directamente | Nombrar archivos, seleccionar texto en el IDE, pegar traceback completo o arrastrar capturas de pantalla |
| Dividir tareas grandes | No procesar de golpe, dividir en pasos pequeños con su propia verificación | Si te cuesta estructurarla usa /plan para pedir un plan primero y autoriza la ejecución paso a paso |
| Fijar el estándar | No detenerse hasta cumplir el objetivo | Usar /goal con un criterio medible de sí/no (requiere habilitar previamente features.goals) |
Ahora deberías ser capaz de: traducir un vago "ayúdame a modificar esto" en un requisito que Codex pueda recibir con precisión, aclarando el objetivo, alcance, restricciones y verificación, proporcionando los materiales directamente, dividiendo las tareas complejas o usando /plan y configurando /goal para fijar criterios de éxito estrictos. Esta técnica de comunicación es la base fundamental de todas tus operaciones con Codex; por muy avanzadas que sean las funciones, si el prompt inicial es deficiente, el resultado final también lo será.
Pregunta de reflexión: ya que "explicarse con claridad" es tan importante, para ciertas reglas fijas (como "no importar librerías nuevas en este proyecto" o "guardar las pruebas siempre en la carpeta
tests/"), ¿deberías repetirlas en cada prompt? ¿Existe alguna forma de que Codex las "recuerde" para no tener que repetirlas a diario? (Pista: [11 · AGENTS.md] contiene la respuesta).
El siguiente artículo [14 · Flujos de trabajo comunes]: este artículo ha cubierto la lógica general de "cómo explicarse con claridad", y el próximo la aplicará en algunos de los flujos de trabajo más frecuentes en el día a día: explorar bases de código desconocidas, corregir bugs, refactorizar o escribir pruebas, ofreciéndote un método de ejecución estándar para cada uno. Con la teoría dominada, es hora de ver la práctica.