Prompt engineering básico

Ya tienes el ecosistema montado: el asistente conoce tu proyecto, sigue tus convenciones y recuerda lo que le has enseñado. El siguiente paso es aprender a darle órdenes claras. Un junior brillante que recibe instrucciones vagas produce resultados vagos. Aquí es donde entra el prompt engineering.

Qué es un prompt#

Un prompt es el texto con el que le pides algo al modelo. Es todo lo que recibes antes de que empiece a responder: la pregunta, el contexto, los ejemplos, las restricciones. No hay magia detrás: el modelo procesa ese texto y genera una continuación probable. Cuanto más preciso es el texto de entrada, más ajustado es el de salida.

El término prompt engineering suena técnico, pero la idea es sencilla: formular la petición de manera que el modelo pueda cumplirla de forma fiable, no a la suerte.

Las tres palancas#

Cualquier prompt útil tira de una o varias de estas tres palancas. Cada una ataca un problema distinto, y puedes combinarlas.

Palanca 1: contexto#

El modelo no sabe nada de tu proyecto a menos que se lo cuentes. Sin contexto, trabaja con suposiciones genéricas. Con contexto, trabaja sobre tu caso real.

Esto es lo que ocurre sin contexto:

// Prompt sin contexto — el modelo supone la estructura
añade el campo 'ratio de victorias' a las tarjetas de héroes

El modelo no sabe si las tarjetas están en React, en HTML plano o en un Web Component. No sabe si el campo ya existe en los datos o hay que calcularlo. No sabe si el ratio va en porcentaje o en decimal. Rellena todos esos huecos con su mejor suposición, y si la suposición falla, el código que genera tampoco funciona.

Con contexto:

// Prompt con contexto — el modelo sabe dónde y con qué trabajar
En src/components/HeroCard.tsx tenemos una tarjeta que recibe un héroe
con los campos 'partidas' y 'victorias' (ambos number).
Añade un campo calculado 'ratioVictorias' (victorias / partidas)
y muéstralo en la tarjeta como porcentaje con un decimal.

La diferencia no es de longitud: es de precisión. El modelo sabe exactamente dónde actuar y con qué datos.

Palanca 2: ejemplos#

Una descripción en palabras deja margen de interpretación: el modelo elige el formato que le parece más probable, y puede que no sea el tuyo. Cuando el formato o el comportamiento importa, un ejemplo concreto lo resuelve sin ambigüedad.

Sin ejemplo:

// Prompt sin ejemplo — el formato de salida queda ambiguo
Dame una función que devuelva el héroe con más victorias del equipo.

¿La función recibe un array o un objeto? ¿Devuelve el nombre, el objeto entero o el índice? ¿Qué pasa si hay empate? El modelo elige lo que le parece más probable, y puede que no coincida con lo que necesitas.

Con ejemplo:

// Prompt con ejemplo — entrada y salida especificados sin ambigüedad
Dame una función que reciba un array de héroes y devuelva el héroe
con más victorias.

Ejemplo de entrada:
[
  { nombre: 'Ana', victorias: 38 },
  { nombre: 'Reinhardt', victorias: 52 },
  { nombre: 'Tracer', victorias: 41 }
]

Salida esperada:
{ nombre: 'Reinhardt', victorias: 52 }

Un ejemplo hace explícito lo que una descripción deja implícito. Es especialmente útil cuando el formato de salida importa: JSON, HTML, TypeScript con tipos concretos.

Palanca 3: restricciones#

Sin restricciones, el modelo toma decisiones por su cuenta: qué librerías instalar, qué patrones aplicar, qué ficheros tocar. Esas decisiones pueden ser válidas en abstracto y completamente incorrectas para tu proyecto. Las restricciones eliminan ese espacio de decisión antes de que cause problemas.

Sin restricciones:

// Prompt sin restricciones — el modelo decide por su cuenta
Añade animaciones a las tarjetas de héroes cuando cambia el filtro activo.

El modelo puede instalar Framer Motion, usar la Web Animations API, añadir CSS Transitions o mezclar los tres enfoques. Puede modificar ficheros que no querías tocar. Puede añadir dependencias que contradigan tu política de no usar librerías de UI externas.

Con restricciones:

// Prompt con restricciones — el espacio de decisión queda acotado
Añade animaciones de entrada a las tarjetas de héroes cuando cambia
el filtro activo. Restricciones:
- Solo CSS transitions, sin librerías externas
- La duración máxima es 200ms
- Toca solo HeroCard.tsx y HeroList.css
- Devuelve solo los ficheros que modifiques

El resultado es predecible porque el espacio de decisiones está definido de antemano.

Pares malo → bueno: qué cambia y por qué#

Estas tres palancas se ven mejor en contraste. A continuación, cuatro pares concretos del Team Builder con la consecuencia real de cada versión.

Par 1: pedir sin formato de salida#

// MAL: la respuesta incluye explicaciones, párrafos de contexto y el
// código mezclado con texto — tienes que extraerlo a mano
Crea los tipos TypeScript para un héroe del Team Builder.

// BIEN: la respuesta es directamente el código que necesitas
Crea los tipos TypeScript para un héroe del Team Builder.
Devuelve solo el bloque de código TypeScript, sin texto adicional
antes ni después.

Sin especificar el formato, el modelo añade introducción, explicaciones por sección y conclusión. El código llega mezclado con markdown y prosa: no es pasteable directo, tienes que extraerlo a mano antes de pegarlo en el fichero, y es fácil colar texto que no es código.

Par 2: pedir sin criterios de aceptación#

// MAL: 'mejora' puede significar cualquier cosa
Mejora la función de filtrado del Team Builder.

// BIEN: los criterios definen exactamente qué es 'mejor'
Refactoriza la función filterHeroes en src/utils/heroes.ts para
que sea más legible. Criterios:
- Extrae la lógica de filtrado por rol a una función auxiliar
- Sin dependencias nuevas
- La firma pública de filterHeroes no cambia
- Añade un comentario encima de cada función que explique qué hace

Sin criterios, el modelo optimiza según su propio criterio de “mejor”: puede que meta una librería, cambie la firma o reestructure algo que no querías tocar. Con criterios, el resultado es verificable: o cumple cada punto o no.

Par 3: alcance indefinido#

// MAL: 'arregla los errores' no acota qué ficheros ni qué tipo de errores
Arregla los errores del Team Builder.

// BIEN: alcance concreto, tipo de error concreto
En src/hooks/useHeroes.ts hay un error de TypeScript en la línea 34:
'Property victorias does not exist on type Hero'. Arréglalo sin
cambiar la interfaz Hero ni el comportamiento del hook.

“Arregla los errores” puede llevar al modelo a reescribir lógica que ya funcionaba, añadir dependencias que no pediste o romper tests que pasaban: recibes un diff de 400 líneas donde esperabas 5. Con un alcance concreto, el cambio es quirúrgico y verificable.

Par 4: sin plan previo#

// MAL: el modelo empieza a tocar código sin que sepas a qué
Añade paginación al listado de héroes.

// BIEN: pedir el plan antes de tocar nada
Antes de hacer ningún cambio, dime qué ficheros vas a modificar,
qué lógica nueva vas a añadir y si necesitas alguna dependencia externa.
Luego espera a que yo apruebe el plan antes de escribir código.

Tarea: añadir paginación al listado de héroes en HeroList.tsx.
Máximo 10 héroes por página. Sin librerías externas.

Pedir el plan primero es la restricción más valiosa de todas. Si el modelo malinterpreta el alcance —quiere tocar tres ficheros que no debía o añadir una dependencia que contradice tu política— lo ves en el plan, en texto, antes de que cambie una sola línea. Revertir un plan cuesta cero; revertir ediciones en código cuesta tiempo y atención.

Más técnicas que funcionan#

Pedir formato de salida siempre#

Si no lo pides, el modelo decide por su cuenta. Algunos formatos útiles:

// Ejemplos de restricciones de formato
// — Solo el bloque de código, sin texto adicional
// — Responde en JSON con esta estructura: { campo: valor }
// — Devuelve solo los ficheros modificados, en bloques de código separados
// — Si no sabes la respuesta con seguridad, dímelo en lugar de inventarte algo

Acotar el alcance con precisión#

El modelo no sabe qué ficheros son sensibles para ti. Si no lo dices, puede tocar cualquier cosa.

// Acotación de alcance
// — Toca solo este fichero
// — No modifiques la interfaz pública
// — Sin cambios en los tests existentes
// — No instales dependencias nuevas

Dar criterios de aceptación#

Un criterio de aceptación convierte una petición vaga en una especificación verificable.

// Criterios de aceptación
// — El filtro funciona con cero, uno o varios roles seleccionados
// — La URL refleja el filtro activo como parámetro de búsqueda
// — El resultado es accesible con teclado (Tab y Enter para seleccionar)
// — No se renderiza nada si el array de héroes está vacío

Pedir el plan antes de tocar código#

Ya lo viste en el Par 4. Es el hábito más rentable de todos: antes de cualquier cambio no trivial, pide el plan y apruébalo. El modelo expone su interpretación del problema y tú puedes corregir malentendidos antes de que tengan consecuencias en el código.

Comprueba lo que sabes#

Tu turno#

Tienes este prompt vago para una tarea del Team Builder:

Mejora la pantalla principal del Team Builder.

Tu tarea es reescribirlo para que sea un prompt de calidad. No hay un editor de código aquí porque la calidad de un prompt no se puede verificar automáticamente: lo que importa es que razonas sobre qué le falta y cómo arreglarlo.

El escenario: quieres que el asistente añada una sección de resumen encima del listado de héroes. El resumen debe mostrar el número total de partidas del equipo, el número de victorias y el ratio global. Los héroes están en src/data/heroes.ts como un array de objetos con nombre, rol, partidas y victorias. El componente del listado vive en src/components/HeroList.tsx. No quieres que el asistente use librerías externas ni que modifique la interfaz Hero.

Reescribe el prompt con todo lo que necesita para que el asistente haga exactamente lo que describes.

Criterios OK

Un prompt de nivel OK incluye el fichero donde hay que trabajar y describe en una o dos frases qué tiene que hacer el asistente. El resultado ya no es “mejora la pantalla principal”: hay una tarea concreta y un destino claro. El modelo puede cumplirlo aunque le queden huecos por rellenar.

Criterios mejor

Un prompt de nivel mejor añade contexto de los datos: qué campos tiene el héroe, de dónde vienen. También especifica el formato de salida (qué fichero o ficheros debe devolver el asistente) y acota el alcance (qué no debe tocar). El modelo tiene suficiente para producir un resultado directamente usable sin que tengas que aclarar nada después.

Criterios excelente

Un prompt excelente añade los criterios de aceptación: qué tiene que ser cierto cuando el asistente termine. Por ejemplo: el ratio se muestra con un decimal, la sección es visible en móvil a 375px, no hay dependencias nuevas, la interfaz Hero no cambia. También pide el plan antes de tocar código: “dime qué vas a modificar y por qué, y espera a que yo apruebe antes de escribir nada”. Un prompt excelente hace que la revisión del resultado sea mecánica: o cumple cada criterio o no.