Skip to content

Cómo escribir prompts: la plantilla mágica para que la IA acierte a la primera ​

La respuesta primero: Que la IA acierte a la primera o no depende de si tu prompt contiene «información» o «deseos». Esta lección sobre prompts de programación con IA trata precisamente de cómo incluir información: en la lección anterior convertiste tu idea en una lista de cuatro elementos; en esta conviertes esa lista en un texto que la IA entiende de inmediato: para redactar hay una plantilla de tres elementos, para las desviaciones hay una regla de corrección de dos rondas, y para las reglas que se repiten cada vez hay un lugar de consolidación llamado AGENTS.md / CLAUDE.md.

Suena a tratado académico, pero en realidad se recorre en 12 minutos incluso sin conocimientos previos. Aplica a las cuatro herramientas (Claude Code, Codex, OpenCode, WorkBuddy): esta lección enseña el método general para pasar información a la IA, no una sintaxis privativa de una herramienta concreta.

Guía del flujo de trabajo estableció cinco disciplinas; la lección anterior desarrolló la primera, «primero planificar, luego actuar», y esta continúa con la segunda: cómo convertir la lista en un prompt con el que la IA acierte a la primera.

Qué podrás hacer al terminar ​

  • Usar la plantilla de tres elementos «ubicación / síntoma u objetivo / criterio de finalización» para convertir la lista de requisitos de la lección anterior en un prompt de programación con IA concreto
  • Cuando tengas material a mano, dejar de describirlo y pasarlo directamente: los archivos se referencian con @, las capturas se pegan tal cual y el texto del error se copia en la conversación
  • Corregir al momento las desviaciones: si corriges lo mismo dos veces y sigue mal, vacía la sesión, incorpora las lecciones en un nuevo prompt y reescribe
  • Consolidar las reglas que se repiten cada vez (comandos de compilación, convenciones de código, trampas) en AGENTS.md / CLAUDE.md, para que las nuevas sesiones las carguen automáticamente
  • Distinguir la información real de las «palabras mágicas»: frases de presión como «piensa paso a paso» o «¡importante!» no son palabras clave, según lo declarado oficialmente

Tu situación actual ​

  • Escribes un prompt larguísimo y la IA devuelve algo que sigue sin estar bien: no sabes decir qué frase le faltó
  • Reglas como «comentarios en chino» o «no introduzcas librerías nuevas» hay que volver a escribirlas en cada sesión nueva, y con olvidarlas una sola vez todo se derrumba
  • Has oído que los prompts tienen «palabras mágicas», pero no sabes cuáles sirven de verdad y cuáles son misticismo, así que añades «por favor, sé muy cuidadoso» a cada frase

Cuándo usar esta técnica ​

Cuando necesitas:

  • Convertir la lista de cuatro elementos de la lección anterior en un texto que la IA realmente siga
  • Reducir una ronda de retrabajo en tareas cotidianas como corregir bugs o añadir funciones
  • Hacer que, en un mismo proyecto, cada sesión cargue automáticamente tus reglas

Y además no quieres:

  • Escribir cada prompt desde cero, cada vez más largo y sin foco
  • Forzar a la IA a obedecer a gritos con «¡importante!» o «¡obligatorio!»
  • Llegar a la quinta revisión en la misma conversación sin atreverte a empezar de nuevo

🎒 Preparativos antes de empezar ​

Idea central ​

Un buen prompt no es cuestión de buena prosa, sino de información suficiente. Las mejores prácticas oficiales de Claude Code ponen esto en primer lugar: antes de empezar, la IA lee tu código; la disposición de archivos, las convenciones y el framework de pruebas los encuentra por sí misma; lo que no puede encontrar es lo que nunca se escribió en el código: las reglas acordadas en tus reuniones, la imagen que tienes en la cabeza, lo que «arreglado» significa para ti. Un prompt concreto funciona porque aporta esa información.

La documentación oficial da además un criterio para decidir «¿escribo esta frase o no?», con dos preguntas:

  1. ¿Puede encontrarlo leyendo el código?
  2. ¿De verdad va a buscarlo?

Si ambas respuestas son «sí», no lo escribas: escribirlo diluye el foco. Es como hacer la maleta: cuanto más llena, más fácil es que lo realmente importante quede enterrado.

Las frases de ejemplo de la tabla comparativa oficial de la lección anterior, desmenuzadas, son exactamente tres tipos de información:

Información que le falta a la IAParte correspondiente del ejemplo
Ubicación: dónde mirar«Revisa la renovación del token en src/auth/»
Síntoma: qué ha pasado«Los usuarios reportan que el inicio de sesión falla tras el tiempo de espera de la sesión»
Criterio de finalización: cómo debe quedar arreglado«Primero escribe un test fallido que reproduzca el problema, luego arréglalo»

Hay una más que se suele pasar por alto: la preferencia entre dos enfoques igualmente razonables tampoco se puede leer en el código. Mostrar el error en una ventana emergente o como mensaje en línea: ambas opciones son razonables y la IA elige una al azar; si tú prefieres el mensaje en línea, dilo por adelantado. Las palabras textuales de la documentación oficial son: «si te importa cuál elige, dilo primero».

Una frase para recordar esta lección: el prompt es para pasar información, no para pedir deseos.

Hazlo conmigo ​

(Toma como materia prima la lista de cuatro elementos de la lección anterior y recorre cuatro pasos: primero se convierte en un prompt con información completa, luego en una configuración a largo plazo que no hay que reescribir cada vez.)

Paso 1: convierte la lista en un prompt de programación con IA con la plantilla de tres elementos ​

Por qué: la lista la escribes para aclararte tú; el prompt se lo das a la IA. La misma información, dispuesta de forma distinta, provoca reacciones iniciales completamente diferentes en la IA. La plantilla de tres elementos convierte el patrón de la tabla comparativa oficial en un ejercicio de rellenar huecos.

Reordena la lista de cuatro elementos según esta plantilla (la primera plantilla mágica de esta página, cópiala tal cual para rellenar):

text
Síntoma u objetivo: <quién, en qué situación, con qué problema / qué quiere conseguir>
Ubicación relevante: <archivo, directorio o texto del error; si empiezas de cero, escribe «desde cero»>
Criterio de finalización: <qué debe cumplirse para darlo por hecho, verificable>
Restricciones duras: <no introducir librerías nuevas / mantener el estilo existente / entrega en un solo archivo...>

WorkBuddy Usuarios: pega la plantilla rellenada en la «descripción adicional» al crear la tarea; la documentación oficial también recomienda explicitar en la descripción de la tarea el objetivo, el alcance, las restricciones y la salida esperada.

Al terminar, haz una auto-revisión: ¿cada línea es información que la IA no puede obtener leyendo el código? Lo que sí puede leer (por ejemplo, «el proyecto usa TypeScript»), bórralo.

Deberías ver: un prompt de cuatro líneas o menos. Tras enviarlo, la primera acción de la IA es leer los archivos que señalaste, en lugar de preguntar «¿qué bug?»: eso es lo que parece la información bien entregada.

  • Comprobación rápida: mi línea de «criterio de finalización» es verificable (pasa el test / ya no se reproduce / se abre), no un «ya está hecho»

Paso 2: si ya tienes el material, pásalo directamente en lugar de describirlo ​

Por qué: las descripciones se distorsionan; el material original no. El consejo textual de la documentación oficial es «si ya tienes lo que la IA necesita, pásalo, no lo describas»: un error parafraseado en tres frases vale menos que su línea original.

Las cuatro herramientas tienen canales para «pasar» material; encuadra cada cosa según su tipo:

Materialcómo entregarlo
ArchivosClaude Code: escribe @ más la ruta y el contenido del archivo entra directamente en el mensaje; Codex: menciona archivos con @; OpenCode: en escritorio/web elige Attach file, pega o arrastra al cuadro de entrada; WorkBuddy: usa @ para citar archivos, documentos, reglas
Capturas / borradores de diseñoClaude Code: pégalas directamente en el prompt; WorkBuddy: pega la captura con Ctrl/Cmd + V; OpenCode: adjuntos de imagen (primero confirma que el modelo admita entrada de imágenes)
Salidas de errorpega el texto original de la salida en la conversación; Claude Code además puedes alimentarlo directamente con una tubería

Claude Code: la sintaxis de tubería que da el oficial (sin abrir ni copiar el log de errores, pregúntaselo en una frase):

bash
cat error.log | claude -p "这是怎么回事"

💡 Entregar material ≠ no escribir el prompt

Aunque entregues el original, los tres elementos del paso 1 siguen siendo obligatorios: el original responde a «ubicación» y «síntoma», pero «criterio de finalización» y «restricción dura» solo los conoces tú. Solo con ambos juntos tienes un prompt completo.

Deberías ver: que la IA cite el original que entregaste — reproduce el contenido del archivo, lee las líneas clave del error, en lugar de adivinar a partir de tu paráfrasis.

  • Pequeña comprobación: en este prompt hay al menos una parte que es «un original entregado», no mi paráfrasis

Paso 3: si se desvía, corrígelo al instante; si dos rondas no lo corrigen, limpia y reescribe ​

Por qué: por bueno que sea el prompt, no se puede lanzar y olvidar. El oficial recomienda vigilar el primer minuto de trabajo de la IA e interrumpirla en cuanto se desvíe — sale mucho más barato que rehacerlo al final. La corrección además tiene una regla: si al corregir lo mismo dos veces sigue mal, la tercera casi seguro no servirá, porque la conversación ya acumula dos registros de fallo que la IA relee en cada ronda.

Las acciones correctivas tienen tres niveles, que se escalan según cuánto se haya desviado:

  1. Interrumpir en el acto: en Claude Code pulsa Esc para detener la acción actual, conservando lo ya hecho, y luego envía el mensaje correctivo
  2. Retroceder y reintentar: usa /rewind (o pulsa dos veces Esc con el cuadro de entrada vacío) para abrir el menú de retroceso y devolver el código, la conversación o ambos a un prompt anterior
  3. Limpiar y reescribir: si corregir lo mismo falla dos veces, usa /clear para limpiar (o abre una sesión nueva) e integra las lecciones de los dos intentos en un prompt nuevo — palabras del oficial: esto casi siempre es mejor que una tercera ronda de corrección

El mensaje correctivo no debe ser solo «no es así»; también tiene plantilla (la segunda plantilla mágica de esta página):

text
Detente un momento. Lo que estás haciendo ahora es <lo que está haciendo>, lo que yo quiero es <la dirección correcta>.
Antes de tocar el código, confírmame en tres frases cómo vas a proceder; actúa solo cuando yo lo confirme.

Codex El oficial añade una disciplina de sesión: un chat, una tarea coherente, no metas todo el proyecto en la misma sesión — cuanto más se acumula el contexto, peor será el resultado.

Deberías ver: la mayoría de las desviaciones se corrigen a la primera; la que no se corrige, la resuelves limpiando y reescribiendo sin dudar, y el prompt nuevo acierta de una vez.

  • Pequeña comprobación: recuerda una vez que llegué «hasta la tercera ronda de cambios» — si lo repitiera con la regla de las dos rondas, ¿en qué paso limpiaría y reescribiría?

Paso 4: consolida en el manual del proyecto las reglas que se repiten cada vez ​

Por qué: después de escribir unos buenos prompts descubrirás que frases como «instala con pnpm», «ejecuta los tests con vitest», «no toques src/legacy/» hay que incluirlas en cada prompt. Codex Palabras textuales de las mejores prácticas oficiales: una vez que un patrón de prompt funciona, el siguiente paso es dejar de repetirlo manualmente — para eso existe AGENTS.md. El archivo correspondiente en Claude Code se llama CLAUDE.md, y OpenCode también lee AGENTS.md. Es el mismo mecanismo: el archivo se coloca en el proyecto y se carga automáticamente en cada sesión.

¿Qué va en el manual? Fusionando las dos listas oficiales quedan cuatro categorías:

CategoríaQué escribirEjemplo
ComandosCómo instalar dependencias, ejecutar tests, ejecutar un solo test, comprobar tipospnpm install / pnpm vitest run path/to/file.test.ts
ConvencionesQué helper usar para el manejo de errores, de qué directorios no copiar patrones«Usa src/lib/errors.ts, no lances cadenas sin más»
TrampasVariables de entorno, directorios que parecen inútiles pero no lo son«Los tests de integración necesitan DATABASE_URL»
Definición de terminadoCómo verificar que está terminado«Al terminar, ejecuta el test correspondiente; solo cuenta como hecho si pasa»

La tercera plantilla mágica de esta página — el esqueleto del manual (válido para AGENTS.md / CLAUDE.md):

markdown
# Manual del proyecto

## Comandos
- Instalar dependencias: <comando>
- Ejecutar un solo test: <comando>
- Comprobar tipos: <comando>

## Convenciones
- <Manejo de errores, nomenclatura, reglas de directorios; solo lo que no se deduce del código>

## Trampas
- <Variables de entorno, directorios fáciles de malinterpretar>

## Definición de terminado
- <Cómo verificar que está terminado: qué ejecutar, qué ver para darlo por bueno>

Dos advertencias oficiales, más importantes que la propia plantilla:

  • Corto y preciso, mejor que largo y completo. La guía de memoria de Claude Code recomienda no superar las 200 líneas; Codex lo expresa así: «un archivo corto y preciso es más útil que un archivo largo lleno de reglas vagas». Empieza por lo más básico y añade reglas nuevas solo cuando notes errores repetidos.
  • Si comete el mismo error dos veces, hazle hacer retrospectiva y actualizar el manual. Es la acción concreta que da el oficial de Codex — la raíz del error suele ser una regla que falta en el manual.

💡 WorkBuddy Usuarios

Las conversaciones de tareas de WorkBuddy también admiten usar @ para citar «archivos, documentos, reglas». Guarda las reglas habituales en un documento de reglas y, al crear la tarea, cítalo con @: el efecto equivale a un manual ligero.

Ten en cuenta una diferencia entre herramientas: OpenCode da prioridad a AGENTS.md; a partir de la v2.3.1 (2026-11-18) solo recurre a CLAUDE.md cuando no hay AGENTS.md en el directorio. Al usar varias herramientas a la vez, dónde colocar el manual y cómo se apilan los niveles: los detalles avanzados están en AGENTS.md y CLAUDE.md: deja un manual del proyecto para la IA.

Deberías ver: en las sesiones nuevas ya no tienes que repetir las reglas — preguntas «¿cómo se ejecutan los tests en este proyecto?» y cita los comandos del manual.

  • Pequeña comprobación: cada regla del manual supera las dos preguntas de la idea central (no se deduce del código / la IA no lo buscará por sí sola)

Punto de control ✅ ​

  • Puedo recitar los tres elementos: ubicación, síntoma u objetivo, criterio de finalización — más una frase de restricción dura
  • He entregado originales: pasé archivos con @, pegué capturas o el texto del error, en lugar de parafrasear con palabras
  • Tras fallar dos veces corrigiendo lo mismo, limpié y reescribí el prompt en lugar de enviar una tercera ronda
  • Mis reglas repetidas están en AGENTS.md / CLAUDE.md y las sesiones nuevas las cargan automáticamente
  • Eliminé el lenguaje de presión del prompt y lo sustituí por información concreta

Aviso de trampas ​

❌ Tomar las «palabras mágicas» como interruptores ​

«Piensa paso a paso», «sé exhaustivo», añadir «¡Importante!» a las reglas o incluso escribirlas en mayúsculas — el oficial dice claramente que esto es texto de prompt normal, no palabras clave; lo que controla la intensidad del razonamiento es el nivel de effort / intensidad de razonamiento, no los adjetivos. Peor aún: apilar énfasis en reglas que siempre se ignoran solo hace que el modelo las sobre-generalice. Lo que hay que hacer no es presionar, sino escribir la información con concreción; y las reglas que de verdad no admiten ni una excepción se imponen con los mecanismos de coerción de la propia herramienta (reglas de permisos, hooks) — ese es el tema de Costo y seguridad.

❌ Cada prompt cargando con todo el equipaje ​

Codex oficialmente enumera como el error más común «amontonar las reglas de largo plazo en el prompt, en lugar de moverlas a AGENTS.md». El prompt guarda la información de esta tarea; el manual guarda las normas de largo plazo — mezclarlos tiene dos costos: el prompt se vuelve cada vez más largo y el foco se diluye; al cambiar de sesión, las normas se pierden por completo.

❌ Quieres la versión completa, pero solo escribiste los requisitos mínimos ​

La IA tiende a interpretar tus palabras de forma conservadora y a hacer «lo mínimo que satisface los requisitos literales» — no puede ver cuán grande es lo que esperas en tu mente. Si quieres una versión completa con estados vacíos, mensajes de error y flujo de guardado, enumera el alcance en el prompt (la frase oficial es be ambitious, seguida de la lista completa de lo que quieres). Esta técnica se mencionó en los consejos avanzados de la lección anterior; su lugar de escritura es aquí.

Consejos avanzados (opcional) ​

Deja que la IA escriba el manual por ti. Tanto el CLI de Claude Code como el de Codex tienen /init, que genera desde el repositorio un manual inicial; tu trabajo consiste sobre todo en recortar — hasta dejar solo la información que no se puede leer del código. Claude Code además tiene /doctor para sugerir recortes y /context para confirmar que el archivo realmente se cargó.

Del manual a la habilidad. ¿Reutilizas el mismo prompt una y otra vez, corriges el mismo flujo repetidamente? La regla empírica oficial de Codex: ya es momento de empaquetarlo como skill. Este es el siguiente nivel de «consolidar»; considéralo cuando tu manual ya sea estable.

Resumen de la lección ​

✅ Has recorrido la cadena completa de los prompts para programar con IA: escribir los tres elementos (ubicación / síntoma u objetivo / criterio de finalización) → entregar los originales directamente (archivo @, pegar capturas de pantalla, pegar mensajes de error) → regla de las dos rondas para corregir el rumbo (interrumpir → revertir → borrar y reescribir) → consolidar las normas de largo plazo (AGENTS.md / CLAUDE.md).

✅ Ya sabes que el criterio para juzgar un buen prompt no es la longitud, sino que cada frase sea información que la IA no puede obtener leyendo el código — con las dos preguntas superadas, borra todo lo que sí se puede leer.

✅ Distingues entre información y presión: las palabras mágicas no son un interruptor, los niveles de effort sí lo son; las normas de verdad van al manual o a un mecanismo de cumplimiento, no dependen de un «¡importante!».

Repaso de conceptos clave:

ConceptoEn una fraseDónde profundizar
Tres elementosUbicación / síntoma u objetivo / criterio de finalizaciónPaso 1 de esta página
Entregar los originales@ citar, pegar capturas, pegar el texto del errorPaso 2 de esta página
Regla de las dos rondasdos correcciones fallidas → borrar y reescribirPaso 3 de esta página
Manual del proyectoAGENTS.md / CLAUDE.md, se carga automáticamente en cada sesiónAGENTS.md y CLAUDE.md
El mito de las palabras mágicaslas frases de presión no son informaciónAviso de errores comunes en esta página

Avance de la próxima lección ​

Por muy bien que escribas el prompt, el código seguirá arrojando errores al ejecutarse — y el texto original del error es precisamente el material más valioso para el siguiente prompt. Próxima lección: El ciclo de errores: alimenta el mensaje de error tal cual.

Aprenderás:

  • Por qué los errores deben alimentarse «tal cual» y qué se pierde al parafrasearlos
  • Cómo lograr que la IA recorra por sí misma el ciclo «modificar — ejecutar — leer la salida — corregir de nuevo», hasta que pase
  • Cómo cambiar de enfoque cuando ya no avanza la reparación, sin dar vueltas en un callejón sin salida
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.