Hay una epidemia silenciosa en el Product Management moderno. Se llama "vibe coding".
El equipo le pide a una IA una historia de usuario. La IA devuelve algo que suena bien. El PM lo pasa a Jira sin leerlo. El desarrollador asume algo diferente. El producto final no se parece a lo que nadie imaginó.
Pero el problema no es la IA. El problema es que le estás pidiendo que sea adivina. Sin contexto, sin restricciones, sin un ancla semántica, cualquier LLM alucina.
La solución no es dejar de usar IA: es escribir specs tan precisas que ni una máquina ni un humano puedan malinterpretarlas. Eso es Spec-Driven Development. Amazon lo hace con PR/FAQs; Google con Design Docs.
Vas a construir tu Spec Kit: documentos inmutables —specs, ADRs, RFCs— que cualquier LLM puede ingerir sin perder contexto. Vas a dejar de depender de la interpretación.
Vamos.
PM pide a la IA → IA devuelve algo genérico → PM lo pasa a Jira sin leer → dev asume otra cosa → QA descubre el malentendido cuando ya es caro cambiar.
2.1. ¿Por Qué Falla la Especificación Tradicional?
El PM tradicional escribe historias de usuario así:
"Como usuario, quiero poder iniciar sesión con Google para no tener que recordar otra contraseña."
Eso suena razonable. Pero es una bomba de ambigüedad. Cada hueco sin resolver es una reunión futura —o una decisión que tomará el dev sin contexto y descubrirás en QA:
- 🕳️ Huecos de esta historia "razonable"
- ¿Qué pasa si el usuario ya tiene cuenta con email y contraseña? ¿Se fusionan?
- ¿Qué datos traemos de Google? ¿Nombre? ¿Email? ¿Foto?
- ¿Qué pasa si el usuario cancela el popup de Google?
- ¿Qué mensaje de error mostramos si falla?
- ¿Esto es para web, mobile, ambos?
- ¿Cuándo consideramos que está "terminado"?
La especificación ambigua es deuda operativa. Como la deuda técnica, hace lento al equipo: cada historia requiere 3 reuniones de aclaración antes de poder codificarse.
2.2. El Principio de Inmutabilidad Contextual
Una especificación SDD tiene una propiedad crítica: es inmutable para el ciclo de desarrollo actual. Esto significa:
- Se escribe antes de empezar a construir.
- Se congela cuando el equipo acepta que es clara y completa.
- Durante la construcción, no se cambia. Si algo debe cambiar, se escribe un nuevo spec y el viejo queda como registro histórico.
- Se escribe
- El equipo comenta
- Inmutable: se construye
- Nuevo spec lo reemplaza
Si la spec cambia mientras construyes, nunca sabes qué estabas construyendo. Los LLMs necesitan contexto estable —cambiar el prompt a mitad de camino les hace perder el hilo. Y el equipo necesita un norte fijo: si el norte se mueve, todos se desorientan.
Una spec SDD es como el brief creativo de un video de YouTube: duración, tono, audiencia, CTA, estructura. Si cambias el brief mientras editas, el video pierde coherencia. Si es sólido, editor, narrador y diseñador trabajan en paralelo sin pisarse.
2.3. El PR/FAQ: El Formato que Amazon (y Ahora Tú) Usa
El PR/FAQ (Press Release / Frequently Asked Questions) es el formato de especificación que Amazon usa desde sus inicios. Tiene tres bloques:
Un PR/FAQ completo le da al LLM contexto cero (el mundo antes), estado final (el mundo después), restricciones (lo que no se hace) y criterio de éxito (cómo se mide). Con eso no adivina: ejecuta dentro del marco.
2.4. El Spec Kit: Tu Repositorio de Contexto Inmutable
El Spec Kit es una carpeta (en GitHub, Drive o tu herramienta de documentación) que contiene:
spec-kit/
├── README.md # Instrucciones de uso
├── templates/
│ ├── pr-faq-template.md # Template de PR/FAQ
│ ├── adr-template.md # Architecture Decision Record
│ └── rfc-template.md # Request for Comments
├── active/
│ └── feature-login-google.md # Spec actual en desarrollo
└── archive/
└── 2024-01-feature-pagos.md # Specs cerrados (historial)
Cada spec activo es un archivo Markdown que puede ser: - Leído por humanos en GitHub. - Ingerido por LLMs como contexto. - Comentado por el equipo antes de congelarse. - Rastreado en su historial de cambios (git).
3.1. Crear tu Repositorio Spec Kit en GitHub
Paso 1 — Crear el repositorio
1. Ve a github.com/new.
2. Nombre del repositorio: spec-kit.
3. Descripción: "Spec-Driven Development Kit — Contexto inmutable para PMs y LLMs".
4. Público o privado (según prefieras).
5. Inicializar con README.
6. Crear repositorio.
Paso 2 — Crear la estructura de carpetas Desde la terminal o la interfaz web de GitHub, crea:
spec-kit/
├── templates/
├── active/
└── archive/
Si usas la terminal:
mkdir templates active archive
Paso 3 — Crear el template de PR/FAQ
Crea un archivo templates/pr-faq-template.md con el siguiente contenido:
# PR/FAQ: [Nombre del Producto/Feature]
## Metadatos
- **Autor:** [Tu Nombre]
- **Estado:** [Borrador | En Revisión | Congelado | Archivado]
- **Fecha:** [YYYY-MM-DD]
- **Versión:** 1.0
- **Industria:** [Industria del proyecto]
---
## Press Release (Comunicado de Prensa)
**Título:** [Título del comunicado, máximo 10 palabras]
**Subtítulo:** [Subtítulo que resume el beneficio clave, máximo 20 palabras]
**Ciudad, Fecha —** [Nombre de la Empresa] anunció hoy el lanzamiento de [Nombre del Producto], una [descripción breve del producto] que [beneficio principal para el cliente].
El producto está dirigido a [segmento de clientes] que actualmente [situación actual del cliente sin el producto].
A diferencia de [alternativas actuales], [Nombre del Producto] [diferenciador clave].
**Testimonio del Cliente:**
> "[Cita ficticia de un cliente usando el producto, mostrando el antes y después.]"
> — [Nombre y cargo ficticios]
---
## FAQ Externas (Para el Cliente)
**P: ¿Qué problema resuelve este producto?**
R: [Descripción clara del problema, en lenguaje del cliente]
**P: ¿Quién debería usar esto?**
R: [Perfil del usuario ideal]
**P: ¿Qué necesito para empezar a usarlo?**
R: [Requisitos del lado del cliente]
**P: ¿Funciona sin internet?**
R: [Sí/No y condiciones]
**P: ¿Cuánto cuesta?**
R: [Modelo de precios o "aún no definido"]
**P: ¿Qué pasa con mis datos actuales?**
R: [Política de migración o integración]
---
## FAQ Internas (Para el Equipo)
### Negocio
**P: ¿Cómo medimos el éxito de esto?**
R: [Métrica específica, ej. "tasa de conversión >5%" o "NPS >50"]
**P: ¿Cuál es el costo de no hacer esto?**
R: [Costo de oportunidad o riesgo]
**P: ¿Quién decide si esto se lanza o no?**
R: [Persona o rol accountable]
### Técnica
**P: ¿Qué stack técnico requiere?**
R: [Lenguajes, frameworks, servicios externos]
**P: ¿Qué dependencias externas existen?**
R: [APIs, proveedores, licencias, terceros]
**P: ¿Cómo manejamos errores?**
R: [Comportamiento esperado en fallo]
**P: ¿Hay restricciones de rendimiento?**
R: [Tiempos de respuesta, concurrencia, límites]
**P: ¿Qué datos se almacenan y dónde?**
R: [Arquitectura de datos, cumplimiento normativo]
### Legal / Regulatorio
**P: ¿Qué regulaciones aplican?**
R: [GDPR, ley de datos, FDA, INVIMA, etc.]
**P: ¿Hay implicaciones de privacidad?**
P: [Qué datos personales se manejan]
**P: ¿Necesitamos aprobación de algún ente externo?**
R: [Sí/No y cuál]
---
## Criterios de Aceptación (DoD — Definition of Done)
Esta feature se considera completa cuando:
1. [ ] [Criterio de aceptación 1: condición observable y medible]
2. [ ] [Criterio de aceptación 2: condición observable y medible]
3. [ ] [Criterio de aceptación 3: condición observable y medible]
4. [ ] [Pruebas automatizadas pasan]
5. [ ] [Documentación actualizada]
6. [ ] [Revisión de seguridad completada]
---
## Instrucciones para LLMs
*Esta sección está diseñada para ser leída por asistentes de IA (Claude, ChatGPT, Gemini) antes de procesar este documento.*
**Contexto Cero:** Este es un documento de especificación de producto en estado [Estado]. Como asistente, debes asumir que este es el único contexto disponible sobre el producto. No debes inventar características, usuarios o casos de uso que no estén descritos aquí. Si algo no está especificado, pregunta antes de asumir. Tus respuestas deben mantenerse dentro del alcance definido por el PR/FAQ anterior.
3.2. Escribir tu Primer PR/FAQ
Usando el template, escribe un PR/FAQ para un feature real de tu producto actual.
Caso de ejemplo (Contenido Digital y Medios): Una empresa de medios quiere lanzar un "reproductor de video con notas colaborativas" para que los equipos de producción dejen feedback directamente sobre el timeline del video (en lugar de intercambiar correos con timestamps).
Press Release:
"MedioCo anunció hoy el lanzamiento de FrameNote, un reproductor de video con capa de notas colaborativas que permite a los equipos de producción dejar feedback sincronizado al frame exacto. A diferencia de los correos interminables con timestamps imprecisos, FrameNote ancla cada comentario al segundo exacto del video, reduciendo el ciclo de revisión en un 40%."
FAQ Externa:
P: ¿Necesito instalar algo? R: No. FrameNote funciona en el navegador.
P: ¿Funciona con cualquier video? R: Con videos subidos a la plataforma o enlazados desde YouTube/Vimeo.
FAQ Interna:
P: ¿Qué stack técnico requiere? R: Frontend en React, backend en Node, almacenamiento en GCP Cloud Storage. La capa de notas usa WebSocket para sincronización en tiempo real.
P: ¿Cómo medimos el éxito? R: Reducción del tiempo promedio de revisión de videos de 3 días a 1.5 días.
3.3. Pasar el PR/FAQ a un LLM como Contexto
Una vez que tu PR/FAQ está congelado, úsalo como prompt de sistema para cualquier LLM:
Contexto: Eres un asistente de producto para [Nombre del Producto], descrito en el siguiente PR/FAQ.
[Pegar aquí el contenido completo del PR/FAQ]
Instrucciones:
1. Responde solo dentro del alcance definido por este documento.
2. Si te pregunto algo que no está en el documento, di "No está especificado en el PR/FAQ actual".
3. Basado en este contexto, genera:
a) 5 historias de usuario priorizadas
b) Los criterios de aceptación para la historia #1
c) Un posible mockup en texto de la interfaz principal
Ejemplo práctico: Copia tu PR/FAQ de FrameNote, pégalo en Claude o ChatGPT, y pídele que genere el backlog inicial. El LLM usará tu contexto, no el suyo genérico. Compara la respuesta con lo que obtendrías si solo le pides "genera un backlog para un reproductor de video".
4. Cómo Usar Esto para Mejorar tus Procesos Reales
4.1. El Espec como Escudo contra el Scope Creep
Situación real: Estás a mitad de un sprint. El cliente pide un cambio. No es grande, dice. Solo "agregar un campo más".
Lo que hacías antes: Decías que sí, el equipo lo incluía en la historia actual, y al final el cambio era 3 veces más grande de lo que parecía.
Lo que harás ahora: Abres el spec del feature actual. Buscas la sección de "Criterios de Aceptación". Le preguntas al cliente: "¿Este cambio está contemplado en el spec actual o es un cambio de alcance?" Si no está en el spec, no se incluye en este ciclo. Se escribe un nuevo spec para el próximo ciclo.
Instrucción: Esta semana, cuando alguien te pida un cambio a mitad del ciclo, responde: "Está fuera del spec actual. Lo evaluamos para el próximo ciclo." Anota cuántas veces pasa.
4.2. El Spec como Contexto para tu Equipo
Situación real: Un nuevo desarrollador se une al proyecto. Necesita entender qué se está construyendo y por qué.
Lo que hacías antes: Una reunión de 1 hora donde explicas todo de memoria y el nuevo desarrollador olvida la mitad.
Lo que harás ahora: Le das el link al spec-kit. Le dices: "Lee los specs activos. Mañana conversamos." El desarrollador llega con preguntas específicas, no con confusión general.
4.3. Diagnóstico Rápido: ¿Tus Especificaciones Están Enfermas?
Responde estas preguntas sobre tu proyecto actual:
- ¿Puedo señalar un documento y decir 'esto es lo que estamos construyendo'?
- Sí concreto → Tienes un spec.
- "Está en Jira" → No tienes un spec, tienes tickets.
-
"Lo expliqué en una reunión" → No tienes nada.
-
¿Tu equipo sabe qué significa 'terminado' sin preguntarte?
- Sí → Tienes DoD claros.
-
No → Tus criterios de aceptación son ambiguos.
-
¿Podrías pasar tu spec a un LLM y obtener respuestas coherentes?
- Sí → Tu spec es machine-readable.
-
No → Tu spec necesita más estructura.
-
¿Tu spec ha cambiado esta semana?
- No → Está congelado (correcto).
- Sí → O estás en Discovery (justificado) o tu spec no es inmutable (problema).
4.4. Entregable del Módulo
Construye tu Spec Kit personal en GitHub (o Google Docs si GitHub te queda grande por ahora):
Archivo 1 — Template de PR/FAQ: - Basado en el template de este módulo. - Personalizado con tus secciones adicionales si aplica.
Archivo 2 — PR/FAQ de un feature real: - Escribe el PR/FAQ completo para un feature que estés construyendo o planeando. - Debe incluir: Press Release + FAQ Externas + FAQ Internas + Criterios de Aceptación. - Sin secciones vacías. Si no sabes algo, investiga o escribe "Por definir: [fecha límite para definirlo]".
Archivo 3 — README del repositorio: - Instrucciones de uso del Spec Kit. - Reglas de inmutabilidad (cuándo se congela un spec, cómo se archiva). - Cómo usar los specs con LLMs.
Formato de entrega: Link al repositorio de GitHub (README + template + PR/FAQ activo). Si no usas GitHub, link a una carpeta de Google Drive con los 3 archivos en Markdown o Google Docs.
- Error: escribir la spec después de empezar a construir. Corrección: la spec congela el contexto ANTES de ejecutar; escrita después solo documenta decisiones ya tomadas.
- Error: un press release del PR/FAQ que no convencería a nadie. Corrección: si el press release no emociona, el producto no se construye: esa es exactamente la prueba.
- Error: FAQ internas sin las preguntas incómodas (costos, riesgos, dependencias). Corrección: el valor de las FAQ internas está en las objeciones difíciles; sin ellas son decoración.
- Error: tratar las specs como documentos vivos que cualquiera edita en caliente. Corrección: versiona en Git: los cambios entran por PR y la historia queda auditable.
- Error: crear el repositorio de specs y abandonarlo tras el primer sprint. Corrección: el Spec Kit es un proceso con dueño y cadencia, no una carpeta que se llena una vez.
| Criterio | No Aprobado (0) | Aprobado (1) | Sobresaliente (2) |
|---|---|---|---|
| 1. El PR/FAQ es específico y accionable | El PR/FAQ es genérico, las FAQs están vacías o las respuestas son vagas ("depende", "lo veremos después") | El PR/FAQ tiene todas las secciones completas pero algunas respuestas son ambiguas o no resolvieron preguntas reales | El PR/FAQ responde preguntas reales que tu equipo hizo, los criterios de aceptación son medibles, y un LLM podría generar un backlog coherente a partir de él |
| 2. El Spec Kit está estructurado y es reusable | Solo existe el PR/FAQ sin carpeta, template ni instrucciones | Hay carpeta y template pero no hay reglas de inmutabilidad ni instrucciones para LLMs | El repositorio tiene template + PR/FAQ activo + README con reglas de inmutabilidad + instrucciones explícitas para LLMs |
| 3. Identificaste dónde tu proceso actual necesita specs | No hay diagnóstico ni plan de adopción | Identificaste que tus especificaciones son ambiguas pero no señalas un caso concreto donde un spec te habría ahorrado una reunión | Identificaste un caso real de la semana pasada donde una especificación ambigua generó retrabajo, escribiste el spec que lo habría prevenido, y lo incluiste como caso en tu Spec Kit |
Aprobación: 2 de 3 criterios en "Aprobado" o superior.
Para avanzar al Módulo 4: Tu PR/FAQ debe pasar la prueba del LLM. Toma tu spec, pégalo en Claude o ChatGPT, y pídele que genere 5 historias de usuario. Si las historias son coherentes con tu visión y no alucinan features que no pediste, tu spec es sólido. Si no, vuelve a ajustar las secciones ambiguas.
Toma la historia "iniciar sesión con Google" y reescríbela como PR/FAQ resolviendo los 6 huecos del checklist de arriba. Luego pégala en un LLM y pídele 5 historias de usuario: si no alucina, tu spec quedó sólido.
- El "vibe coding" falla porque le pides a la IA que adivine: sin contexto, alucina.
- Una spec ambigua es deuda operativa: cada hueco se convierte en una reunión o un retrabajo en QA.
- Una spec es inmutable una vez congelada (Draft → Review → Frozen → Superseded).
- El PR/FAQ (Press Release + FAQ externas + internas) le da al LLM contexto, estado final, restricciones y criterio de éxito.
Kit: GitHub Spec Kit (8 templates)
| Archivo | Descripción |
|---|---|
| ⬇ README.md | Documentación completa del Spec Kit: estructura, reglas, instrucciones para LLMs |
| ⬇ spec-template.md | Template de especificación de feature |
| ⬇ plan-template.md | Template de plan de implementación técnica |
| ⬇ tasks-template.md | Template de desglose en tareas atómicas |
| ⬇ checklist-template.md | Quality Gate / validación del spec |
| ⬇ constitution-template.md | Reglas del proyecto y boundaries |
| ⬇ adr-template.md | Architecture Decision Record |
| ⬇ rfc-template.md | Request for Comments |