Ingeniería de contexto: que la IA no adivine nada

Dos líneas y un módulo que no es nuestro

La historia #14, «Cancelar una reserva», vuelve al tablero del Sprint 3: la primera versión no distinguía estados y Camila pidió rehacerla bien. Valentina abre su asistente de código y escribe lo primero que se le ocurre: «Hacé el módulo para cancelar reservas de EventoUAB en JavaScript». En diez segundos tiene esto:

// cancelarReserva.js
import { db } from "./db.js";
import { enviarCorreo } from "./correo.js";

export async function cancelarReserva(reservaId, usuario) {
  const reserva = await db.reservas.findById(reservaId);
  if (reserva.userId !== usuario.id && usuario.rol !== "admin") {
    throw new Error("No autorizado");
  }
  reserva.status = "CANCELLED";
  reserva.motivo = usuario.motivo;
  reserva.penalidad = reserva.precio * 0.2;
  await db.reservas.save(reserva);
  await enviarCorreo(usuario.email, "Reserva cancelada");
  return reserva;
}

Compila, se lee prolijo y hasta suena razonable. Pero Valentina lo mira con calma y se da cuenta de que casi nada de eso existe en EventoUAB:

Qué es la ingeniería de contexto

El prompt es la instrucción («hacé esto»). El contexto es todo lo demás que el modelo tiene delante cuando responde: los documentos, los nombres, las reglas, los ejemplos. La ingeniería de contexto es decidir qué información recibe, con qué forma y en qué orden, para que haga la tarea sin suponer.

Tu equipo ya tiene el material

No hay que inventar documentos nuevos. Cada artefacto que el curso te hizo producir cubre un tipo distinto de hueco:

¿Cuánto del backlog le paso?

Valentina ya entendió que debe dar contexto. Lo primero que piensa es el backlog: ahí está la historia #14 y todo lo que Camila pidió. El tablero del producto tiene 38 historias entre «Ver disponibilidad», «Lista de espera», «Notificar a Bienestar» y varias más. ¿Qué pega en el chat?

El backlog como contexto: el qué y el cuándo está listo

Una historia bien escrita ya es medio prompt. Los criterios de aceptación son las reglas que el código debe cumplir y que la prueba va a comprobar; la Definition of Done dice qué más hace falta para llamarla terminada. Y hay una sección que casi nadie escribe y que más protege: lo que NO entra en esta historia.

Historia #14 — Cancelar una reserva
Como estudiante responsable de un club, quiero cancelar una reserva
que ya no voy a usar, para liberar el espacio.

Criterios de aceptación
- Solo el club que hizo la reserva puede cancelarla.
- No se puede cancelar con menos de 2 horas de anticipación.
  Justo 2 horas antes sí se puede.
- Solo se puede cancelar una reserva confirmada.

Fuera de esta historia
- Notificar a Bienestar Estudiantil (historia #22).
- Cobros, penalidades o motivos de cancelación.

Definition of Done
- Una prueba automática por cada criterio, incluido el borde.
- PR revisado por otra persona del equipo.

«Y encima me agregó un administrador»

Con la historia en el chat, la nueva versión ya valida las 2 horas. Pero Valentina nota otra cosa: la IA le dejó un parámetro esAdmin «para que Bienestar pueda cancelar cualquier reserva». Nadie pidió eso. La historia dice quién cancela, pero no dice quién más existe en el sistema, y la IA tuvo que imaginarse a los actores.

Casos de uso como contexto: quién y qué rama

El diagrama de casos de uso fija el alcance (qué hace el sistema y quién lo usa). Su descripción textual fija el comportamiento: el flujo principal y los alternativos son, casi uno a uno, las ramas del código y las pruebas.

Actores del sistema: Estudiante (responsable de un club) y Bienestar.
Actor de este caso: Estudiante. Bienestar no participa.

Precondición: el estudiante inició sesión.

Flujo principal
1. El estudiante elige una reserva de su club.
2. El sistema verifica que sea del club y que falten 2 horas o más.
3. El estudiante confirma.
4. El sistema marca la reserva como cancelada y libera el espacio.

Flujos alternativos
2a. La reserva es de otro club: se rechaza.
2b. Faltan menos de 2 horas: se rechaza.
2c. La reserva no está confirmada: se rechaza.

Postcondición: el espacio queda libre en ese horario.

Los nombres que la IA se inventa

Ahora el flujo es correcto, pero los nombres siguen sueltos: la IA escribe reserva.status, reserva.userId y usuario.club porque nadie le dijo cómo se llaman las cosas. En el proyecto, el diagrama de clases (el modelo de dominio) ya lo resolvió: Estudiante, Club, Reserva y Espacio, con sus atributos. Valentina tiene ese diagrama dibujado en el repositorio.

Diagrama de clases como contexto: nombres y estructura

El diagrama de clases le da a la IA el vocabulario del dominio. El modelo de EventoUAB se puede escribir como texto con Mermaid, un lenguaje de diagramas que GitHub y GitLab dibujan solos, y que cualquier IA lee sin ambigüedad.

classDiagram
  class Estudiante {
    nombre
    carnet
    correo
  }
  class Club {
    nombre
    facultad
  }
  class Reserva {
    fecha
    horaInicio
    horaFin
    estado
  }
  class Espacio {
    nombre
    capacidad
    tieneProyector
  }
  Estudiante "1" --> "0..*" Club : lidera
  Club "1" --> "0..*" Reserva : solicita
  Reserva "0..*" --> "1" Espacio : ocupa

Cancelar lo que ya está cancelado

Con historia, caso de uso y modelo, la función ya se parece a EventoUAB. Valentina la prueba con una reserva ya cancelada: la IA responde «cancelada con éxito». Con una reserva que ya terminó ayer, también. El atributo estado existe, pero nadie le dijo qué valores puede tomar ni cuáles cambios están permitidos.

Diagrama de estados como contexto: qué se puede hacer cuándo

Un objeto como la reserva vive una secuencia de estados, y no todos los saltos son válidos. El diagrama de estados es la lista cerrada de esos saltos. Para la IA es contexto que dice «estos son los únicos valores de estado» y «estas son las únicas transiciones».

stateDiagram-v2
  [*] --> confirmada : reservar
  confirmada --> cancelada : cancelar (2 h o más antes)
  confirmada --> finalizada : pasa la horaFin
  cancelada --> [*]
  finalizada --> [*]

«Asumí que cualquier miembro del club puede cancelar»

Valentina armó el paquete completo y, al final de su pedido, agregó una regla: «si te falta información, no la completes: listá tus supuestos». La IA entrega la función y, al pie, escribe: «Supuesto: asumí que cualquier miembro del club puede cancelar, no solo quien lidera el club». El modelo dice que un Estudiante «lidera» un Club, pero no dice nada de los demás miembros. Es un hueco real, y la IA lo señaló en vez de taparlo.

Los huecos y el control: lo que la IA no puede decidir por vos

Con el paquete completo, la función que sale ya no inventa nada: cada línea tiene un origen que se puede señalar. Mirá el resultado y fijate de dónde sale cada decisión.

// reservas.js
const HORAS_MINIMAS = 2;                                       // criterio 2 (historia #14)

export function cancelarReserva(reserva, club, ahora) {
  if (reserva.club !== club) {                                 // criterio 1; flujo alternativo 2a
    throw new Error("Solo el club dueño puede cancelar la reserva");
  }
  if (reserva.estado !== "confirmada") {                       // diagrama de estados; flujo 2c
    throw new Error("Solo se puede cancelar una reserva confirmada");
  }
  const inicio = new Date(`${reserva.fecha}T${reserva.horaInicio}`);   // atributos del modelo
  const horasAntes = (inicio - ahora) / 3600000;
  if (horasAntes < HORAS_MINIMAS) {                            // criterio 2; borde: justo 2 h sí; flujo 2b
    throw new Error("Solo se puede cancelar con 2 horas de anticipación");
  }
  return { ...reserva, estado: "cancelada" };                  // transición confirmada → cancelada
}

Y las pruebas salen de las mismas fuentes, una por criterio, por rama y por transición. Se ejecutaron en Node con node --test:

import test from "node:test";
import assert from "node:assert/strict";
import { cancelarReserva } from "./reservas.js";

const reserva = {
  club: "Robótica", fecha: "2026-11-10",
  horaInicio: "10:00", horaFin: "12:00", estado: "confirmada",
};
const a = (hhmm) => new Date(`2026-11-10T${hhmm}`);

test("el club dueño cancela con 3 horas de anticipación", () => {
  assert.equal(cancelarReserva(reserva, "Robótica", a("07:00")).estado, "cancelada");
});
test("otro club no puede cancelar", () => {
  assert.throws(() => cancelarReserva(reserva, "Teatro", a("07:00")), /club dueño/);
});
test("no se cancela una reserva ya cancelada", () => {
  assert.throws(() => cancelarReserva({ ...reserva, estado: "cancelada" }, "Robótica", a("07:00")), /confirmada/);
});
test("no se cancela una reserva finalizada", () => {
  assert.throws(() => cancelarReserva({ ...reserva, estado: "finalizada" }, "Robótica", a("07:00")), /confirmada/);
});
test("borde: justo 2 horas antes sí se puede", () => {
  assert.equal(cancelarReserva(reserva, "Robótica", a("08:00")).estado, "cancelada");
});
test("borde: 1 h 59 min antes no se puede", () => {
  assert.throws(() => cancelarReserva(reserva, "Robótica", a("08:01")), /2 horas/);
});

Si se cambia < por <= en la comparación de las horas, falla exactamente una prueba: la del borde de 2 horas. Esa prueba existe porque el criterio lo pedía, no porque la IA se acordó de él.

Las reglas para el asistente

El paquete de contexto cierra con unas pocas reglas que convierten los documentos en una frontera. Son las que evitaron que la IA «completara» el hueco de la decisión 6:

Una plantilla reutilizable: CONTEXTO.md

Todo lo anterior cabe en un solo archivo de texto que vive en el repositorio. Muchos asistentes de código leen automáticamente un archivo de instrucciones de la raíz (como AGENTS.md o CLAUDE.md), y también podés pegar el tuyo al empezar una conversación:

# CONTEXTO — [Producto] · Historia #[N] "[Título]"

## 1. Tarea
Una frase: qué se implementa y en qué archivo.

## 2. Historia y criterios (del backlog)
Copiá la historia, sus criterios de aceptación con los bordes y la DoD.

## 3. Caso de uso
Actores, precondición, flujo principal, flujos alternativos y postcondición.

## 4. Modelo (diagrama de clases, en Mermaid)
Clases, atributos con sus nombres exactos y relaciones con multiplicidad.

## 5. Estados (diagrama de estados, en Mermaid)
Estados válidos y transiciones permitidas.

## 6. Fuera de alcance
Lo que NO se hace en esta historia.

## 7. Convenciones
Lenguaje, librería de pruebas, idioma de los mensajes de error.

## 8. Reglas para el asistente
1. Usá solo los nombres de este documento.
2. Si falta información, preguntá o listá el supuesto al final.
3. No agregues nada de la sección 6.
4. Entregá una prueba por criterio y por transición, con los bordes.

Armador de paquete de contexto

Tarea: «implementar cancelar reserva». Marcá qué artefactos le das a la IA y mirá cuántas decisiones le dejás adivinar. Abajo se arma el texto que pegarías en el chat. Probá con ninguno, con uno solo, con todos, y buscá cuál combinación es la mínima que cubre todo.

Detectar lo que inventó la IA

Otro intento de la IA, esta vez con la historia #14, el modelo y el diagrama de estados, pero sin la sección «Fuera de alcance». Leelo línea por línea contra los artefactos de esta guía.

export function cancelarReserva(reserva, club, ahora) {
  if (reserva.club !== club) throw new Error("Solo el club dueño puede cancelar");
  if (reserva.estado === "finalizada") throw new Error("La reserva ya terminó");
  const horas = (new Date(`${reserva.fecha}T${reserva.horaInicio}`) - ahora) / 3600000;
  if (horas < 2) throw new Error("Faltan menos de 2 horas");
  reserva.estado = "cancelada";
  reserva.canceladaPor = club;
  reserva.penalidad = horas < 24 ? 50 : 0;
  notificarBienestar(reserva);
  return reserva;
}

Actividades de repaso

Un repaso integrador de lo que acabás de recorrer. Cada actividad se corrige al instante; tu progreso se guarda automáticamente en este navegador.

🎯 Reto Final: el CONTEXTO.md de tu próxima historia

Ahora con tu propio proyecto. Elegí la próxima historia que vayas a programar con ayuda de una IA y escribí su CONTEXTO.md usando la plantilla: la historia con sus criterios, el caso de uso, el modelo y los estados que la tocan, qué queda fuera de alcance y las reglas para el asistente. Si algún artefacto todavía no existe en tu equipo, anotá qué decisiones quedarían sin dueño.

Cheat Sheet

¿Sabías que...?