Spec vs Prompt: Una opción para borrar la deuda técnica

La diferencia entre un spec y un prompt marca el límite entre crear un demo que funciona una vez y construir un producto que escala. Si has vibecodeado aplicaciones con inteligencia artificial y terminas con historiales de chat interminables llenos de parches, este contenido es para ti: aprenderás la anatomía mínima de una especificación técnica y por qué reemplaza al prompt en proyectos serios.

¿Por qué un prompt largo termina fallando?

Piensa en el último prompt que usaste. Funcionó bien, seguiste iterando, y después de 50 interacciones tienes un historial lleno de errores, inconsistencias y reparcheos. Ese problema tiene nombre: saturación del contexto [00:38].

Lo que sucede es que la inteligencia artificial empieza a olvidar las reglas de oro que definiste al principio. Se enfoca en cosas poco relevantes y descarta lo que sí importa para el proyecto.

¿Qué es la saturación del contexto? Es cuando la IA, tras muchas interacciones, olvida las reglas iniciales del proyecto y prioriza detalles irrelevantes. El resultado son inconsistencias y errores acumulados en el desarrollo.

Y hay un problema extra. Si un desarrollador nuevo entra a colaborar, ¿le vas a pasar tu historial de 50 mensajes para que entienda la idea detrás de la aplicación? Ahí es donde todo se cae.

¿Qué es el efecto Jenga en el vibe coding?

Cuando avanzas en un proyecto, la deuda técnica se acumula y termina impidiendo que escales el producto. En el vibe coding esto se conoce como el efecto Jenga [1:20].

Ocurre cuando, por resolver una funcionalidad, terminas afectando otra que ya estaba funcionando bien. Como en el juego: mueves una pieza y la torre se tambalea.

La raíz del problema es simple. Tu historial de chat con la inteligencia artificial no es un documento de ingeniería. Esa es la diferencia central con una especificación.

¿Qué es un spec? Es un contrato técnico con vida propia que no vive en un historial de chat, sino en tu repositorio, junto al código del proyecto. No deja espacio para ambigüedades.

¿Cuál es la anatomía mínima de un spec?

Para el proyecto del curso trabajaremos un spec llamado Creación de reservas, que encontrarás en la caja de recursos. Vamos parte por parte [1:53].

Una especificación mínima se compone de cuatro bloques claros:

• Intención: permitir a usuarios autenticados agendar un bloque de tiempo, garantizando que el sistema no asigne el mismo turno a dos personas. Aquí defines por qué importa la funcionalidad y qué resuelve.
• Comportamiento: el usuario selecciona un bloque disponible y confirma; el sistema lo asigna y actualiza la grilla en tiempo real. Define qué hace la funcionalidad.
• Restricciones: los límites del negocio.
• No objetivos (non goals): lo que deliberadamente no vas a construir.

Después de esos cuatro pilares, conviene detenerse en los dos que más confusión generan.

¿Qué van en las restricciones de un spec?

Las restricciones ponen los límites físicos o del negocio [2:35]. En el spec de reservas incluyen:

• Prevención de colisión: el sistema valida la disponibilidad en la base de datos antes de guardar. Si dos usuarios reservan el mismo bloque en el mismo milisegundo, el segundo recibe un error de conflicto.
• Regla de tiempo: no se pueden hacer reservas en fechas u horarios del pasado.
• Formato: las reservas son estrictamente en bloques enteros de una hora.

Estas reglas eliminan la interpretación libre y le dan a la IA fronteras claras.

¿Por qué son importantes los no objetivos?

En los non goals especificas qué no quieres hacer [3:14]. Para el spec de reservas se definió que no se programará pasarela de pagos integrada, porque se paga en el club, y que no se enviarán correos ni SMS de confirmación.

Y aquí viene lo interesante. Como la inteligencia artificial no es determinista, suele tomarse atribuciones. Es muy probable que decida desarrollarte una pasarela de pago por su cuenta, asumiendo que ese es el siguiente paso lógico tras una reserva.

Por eso decirle explícitamente qué no debe construir es tan valioso como decirle qué sí.

¿Cómo detectar los gaps de un prompt?

Ahora al ejercicio: encontrar todos los gaps de un prompt real. Este es uno que se usaría para desarrollar la misma app de reservas de pádel con vibe coding [4:15]. Estos son los vacíos que aparecen:

1. Alcance desmedido: pedir "login con Google y Facebook" o una pasarela de pagos como si fueran viñetas o cambios de color. Son funcionalidades críticas y complejas tratadas como triviales.
2. Subjetividad: pedir un calendario "con animaciones suaves" o una interfaz "tipo Airbnb o Uber" no dice nada preciso a la IA.
3. Micromanagement: definir "verde manzana claro" para bloques libres y "gris oscuro" para ocupados cuando ni siquiera existe la estructura de base de datos. Preocuparse por el color antes que por los cimientos.
4. Desconexión con el negocio: pedir "usa Firebase o Postgres, la que escale mejor". Son bases muy distintas: una es NoSQL y la otra es SQL. La elección depende del tipo de información a almacenar, no de una corazonada.
5. Delegar el pensamiento crítico: pedirle a la IA que "piense en casos donde podría haber inconsistencias y los solucione". Ese pensamiento crítico es tuyo como arquitecto o director del producto.

Sí puedes usar la inteligencia artificial para descubrir estos gaps, pero eres tú quien debe definirlos.

¿Cuál es la diferencia clave entre spec y prompt?

Si hay algo que quiero que te lleves es esto: el spec es un documento técnico que no deja espacio para ambigüedades, mientras que el prompt improvisa y acumula deuda técnica.

Un prompt sirve para crear demos. Un spec sirve para crear productos [00:00]. Con tu primer spec ya listo, el siguiente paso es dejar todo el setup preparado para desarrollar el proyecto.

¿Qué gaps encontraste tú en el prompt del ejercicio? Déjalos en los comentarios.