Lección 02

Anatomía de un prompt que funciona

Las cinco piezas que separan un prompt amateur de uno profesional: rol, contexto, instrucción, ejemplos y formato.

La fórmula (no oficial pero útil)

Después de leer cientos de prompts que funcionan en producción, la mayoría comparten esta estructura:

[ROL]          → quién eres tú, modelo
[CONTEXTO]     → de qué va esto
[INSTRUCCIÓN]  → qué quiero que hagas
[EJEMPLOS]     → cómo se ve un buen output
[FORMATO]      → cómo lo tienes que devolver

No siempre necesitas las cinco. Pero cuando algo no funciona, la pieza que faltaba está siempre en esta lista.

1. Rol — el system

El system fija quién es el modelo. Es la pieza con más palanca.

const res = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 500,
  system: "Eres un crítico literario español, conciso y exigente. Hablas en castellano de España, no de Latinoamérica.",
  messages: [
    { role: "user", content: "Reseña *Cien años de soledad* en 80 palabras." },
  ],
});

Una sola frase en system cambia el tono, el registro y el formato sin que tengas que repetirlo en cada user.

2. Contexto — los datos

Si la respuesta depende de información que el modelo no puede saber, dásela explícitamente. No le hagas adivinar.

const productos = [
  { id: 1, nombre: "Camisa", precio: 29.9, stock: 0 },
  { id: 2, nombre: "Pantalón", precio: 49, stock: 12 },
];

const res = await client.messages.create({
  model: "claude-haiku-4-5",
  max_tokens: 300,
  messages: [
    {
      role: "user",
      content: `Catálogo:\n${JSON.stringify(productos, null, 2)}\n\nPregunta del cliente: "¿Tenéis camisas?"`,
    },
  ],
});

3. Instrucción — qué hacer

Aquí el error más común: pedir varias cosas a la vez. Si necesitas tres tareas, hazlas en tres prompts o pídelas numeradas.

Devuélveme:
1. Un resumen en una frase.
2. Tres puntos clave en formato bullet.
3. Un titular tipo Twitter (máx. 240 caracteres).

4. Ejemplos — el few-shot

Si el formato es raro, muéstralo con ejemplos, no lo describas con palabras.

“Devuélvemelo en formato clave: valor” → ambiguo. “Aquí tienes 3 ejemplos:” + 3 ejemplos → inequívoco.

Lo verás en detalle en la lección 3.

5. Formato — qué pinta tiene la salida

Si vas a parsear la respuesta en código, fuerza el formato:

• JSON → di que sólo JSON, y usa assistant prefill (lo verás en la lección 4).
• Markdown con secciones → enumera las secciones exactas que esperas.
• Texto plano → di “sin markdown, sin viñetas”.

Ejercicio guiado

Combina las cinco piezas para resolver este caso real:

Quiero clasificar emails de soporte en bug | facturación | feature | otro, y que me devuelva el motivo en una frase.

const SYSTEM = `Eres un clasificador de tickets de soporte. \
Devuelves SIEMPRE JSON con dos claves: categoria y motivo. \
Categorías permitidas: bug | facturación | feature | otro.`;

const EJEMPLOS = `
Email: "No me llega el email de recuperación de contraseña."
{ "categoria": "bug", "motivo": "fallo en flujo de recuperación" }

Email: "¿Cuánto cuesta el plan empresa?"
{ "categoria": "facturación", "motivo": "consulta de precios" }
`;

async function clasificar(email: string) {
  const res = await client.messages.create({
    model: "claude-haiku-4-5",
    max_tokens: 200,
    system: SYSTEM,
    messages: [
      { role: "user", content: `${EJEMPLOS}\n\nEmail: "${email}"` },
      { role: "assistant", content: "{" },
    ],
  });
  return JSON.parse("{" + res.content[0].text);
}

Pulsa “Ejecutar” en el playground de la derecha y prueba con tus propios ejemplos.

Lo que toca en la siguiente lección

Cuándo y cómo usar zero-shot (no le das ejemplos) y few-shot (le das 2-5). La diferencia entre ambos vale más que cualquier “modelo más grande”.