El mantra de las startups es conocido: "ship fast, learn fast". Construye un MVP en semanas, ponlo delante de usuarios, itera. El problema no es la velocidad. El problema es lo que ocurre cuando ese MVP, construido sobre suposiciones no documentadas, tiene que escalar, integrarse con agentes de IA o sobrevivir al primer pivot. El 80% del rework en software se origina en defectos de requisitos. Y un MVP sin especificación es, por definición, un producto construido sobre requisitos implícitos.
Spec-Driven Development (SDD), también conocido como desarrollo guiado por especificaciones, no propone volver al waterfall ni escribir documentos de 100 páginas antes de programar. Propone algo más preciso: documentar las decisiones que ya estás tomando, en un formato que tanto humanos como agentes de IA puedan consumir. La diferencia entre un MVP que valida y uno que genera meses de rework está, casi siempre, en esas decisiones no escritas.
El coste oculto de los MVPs sin especificación
Cuando un equipo construye un MVP bajo presión de tiempo, ocurre un patrón predecible: los requisitos se asumen en lugar de documentarse. El frontend asume una estructura de datos. El backend asume un flujo de usuario. QA asume criterios de aceptación. Y nadie descubre las inconsistencias hasta 3-5 semanas después, cuando las piezas no encajan.
Los datos son contundentes:
- El 30-50% del esfuerzo total en proyectos de software se destina a rework (Boehm & Papaccio)
- El 80% de ese rework es atribuible a defectos en requisitos (Info-Tech Research Group)
- Un error de requisitos cuesta 8x más corregir en diseño, 16x en código y 29x en producción (NASA)
- Cada euro invertido en mejorar procesos de requisitos retorna entre 3x y 7,5x (Carnegie Mellon SEI)
En un MVP típico de 8-12 semanas, esto se traduce en 3-5 semanas adicionales de rediseño no planificado. No porque el equipo sea malo, sino porque las suposiciones no documentadas divergen entre personas. Y cuando introduces agentes de IA en ese proceso, el problema se multiplica.
Por qué la IA amplifica el problema
Un agente de IA como Claude Code o GitHub Copilot no tiene intuición. No "sabe" que el CTO quería un flujo de pago en dos pasos, no en tres. No deduce que la API debe ser RESTful porque el equipo de mobile lo necesita. Sin especificación, el agente genera código basado en patrones estadísticos, no en decisiones de producto.
Cuando equipos con procesos de requisitos inmaduros integran IA, no reducen el rework: lo aceleran. Como señala Thoughtworks en su análisis de SDD para el Technology Radar, la IA produce soluciones erróneas más rápido cuando no tiene especificaciones que la guíen. El resultado es más código que refactorizar, no menos.
Cuándo una especificación es "suficientemente formal" para IA
El sesgo del "Quick Ship" asume que especificar es lo opuesto a ser ágil. Que escribir una spec antes de programar es perder tiempo. Pero una especificación útil para SDD no se parece a un documento de requisitos de 100 páginas. Se parece a esto:
## Feature: Checkout simplificado ### Problema El 34% de usuarios abandona en el paso de pago. Necesitamos reducir fricción sin comprometer seguridad. ### Restricciones - Máximo 2 pasos (datos + confirmación) - Pasarela: Stripe (ya integrada) - No almacenar datos de tarjeta (PCI compliance) - API REST, endpoint POST /api/checkout ### Criterios de aceptación - [ ] Usuario completa compra en menos de 60 segundos - [ ] Error de pago muestra mensaje claro, no código HTTP - [ ] Funciona en mobile (viewport 375px+) ### Integración - Usa el componente Button existente de /ui/Button - Sigue el patrón de estado de /hooks/useAsync - Tests con Vitest, mínimo 80% cobertura
Eso es una especificación suficiente para SDD. No 100 páginas. Son 20 líneas que explicitan las decisiones que el equipo ya había tomado mentalmente pero no había escrito. La diferencia es que ahora un agente de IA puede leerlas y generar código que respete esas restricciones.
Los tres niveles de formalidad
- Nivel 1 - Prosa estructurada: Markdown con secciones claras (problema, restricciones, criterios). Suficiente para el 80% de features de un MVP. 10-15 minutos de escritura.
- Nivel 2 - Contratos de API: OpenAPI para endpoints, schemas JSON para modelos de datos. Necesario cuando hay múltiples consumidores (mobile, web, agentes). 30-60 minutos.
- Nivel 3 - Comportamiento formal: Gherkin para flujos críticos, state machines para workflows complejos. Reservado para lógica de negocio donde un error tiene impacto financiero o regulatorio. 1-2 horas.
Caso: de 7 sprints a 3 sprints con SDD + Claude Code
Contexto: SaaS B2B, equipo de 6 developers, producto en fase de crecimiento post-MVP. Estaban reconstruyendo el módulo de facturación para soportar múltiples divisas y cumplimiento fiscal europeo.
Sin SDD (estimación original): 7 sprints
- Sprint 1-2: Desarrollo del core de facturación con Copilot (prompts ad hoc)
- Sprint 3: Descubren que el modelo de datos no soporta divisas múltiples correctamente
- Sprint 4: Rediseño del schema + migración de datos
- Sprint 5-6: Reimplementación parcial + tests
- Sprint 7: Integración, QA, hotfixes
Patrón clásico: Los sprints 3-4 son puro rework. El equipo no definió formalmente las restricciones de multidivisa antes de empezar. Copilot generó código que asumía una sola divisa porque ningún prompt lo especificó.
Con SDD: 3 sprints
- Semana previa: 3 días escribiendo especificaciones (modelo de datos multidivisa, reglas fiscales por país, contratos de API con OpenAPI, criterios de aceptación en Gherkin para flujos críticos)
- Sprint 1: Claude Code genera el schema, los endpoints y los tests base a partir de las specs. Revisión humana: 70% del código aceptado sin cambios
- Sprint 2: Lógica de negocio y reglas fiscales. La "constitución" del proyecto (reglas inmutables) evita que la IA genere atajos que violen compliance
- Sprint 3: Integración, QA, deploy. Sin rediseños porque las decisiones críticas estaban documentadas desde el día 1
Comparativa: sin SDD vs con SDD
Los 3 días de especificación ahorraron 4 sprints de rework. ROI: 15x sobre el tiempo invertido en specs.
Matriz: cuándo SDD es ROI positivo vs overhead
SDD no es siempre la respuesta correcta. Hay contextos donde el overhead de escribir especificaciones no compensa. Esta matriz te ayuda a decidir:
| Escenario | SDD recomendado | Por qué |
|---|---|---|
| MVP con integración de IA agéntica | Sí | Los agentes necesitan contexto explícito. Sin spec, generan código que no encaja con las decisiones de producto. |
| Feature compleja (múltiples integraciones, compliance) | Sí | Coste de error alto. Una spec de 1-2 horas ahorra semanas de rediseño. |
| Equipo de 4+ developers en la misma feature | Sí | La spec es la fuente de verdad compartida. Reduce malentendidos entre miembros. |
| Landing page o cambio de copy | No | Bajo riesgo, bajo coste de error. Un prompt directo es suficiente. |
| Prototipo desechable para validar hipótesis | No | Si sabes que lo vas a tirar, no inviertas en formalizarlo. Un prompt ad hoc es correcto. |
| Bugfix aislado en código existente | No | El contexto está en el código. La IA puede entenderlo directamente. |
| MVP que va a escalar post-validación | Sí | El coste de no especificar se paga con intereses cuando hay que escalar el MVP validado. |
| Refactoring de código legacy con IA | Sí | La IA necesita saber qué mantener y qué cambiar. Sin spec, toca lo que no debe. |
Regla general: Si el coste de un error supera las 4 horas de rework, o si más de 2 personas (humanas o agentes) van a trabajar en la misma feature, SDD es ROI positivo. Por debajo de ese umbral, un prompt bien escrito es suficiente.
Herramientas ligeras para escribir specs
No necesitas software especializado para practicar SDD. Las mejores especificaciones para MVPs se escriben con herramientas que ya tienes:
1. Prosa estructurada en Markdown
El formato más accesible. Un archivo .md con secciones claras: problema, restricciones, criterios de aceptación, integración. Funciona con cualquier agente de IA (Claude Code, Copilot, Cursor) porque es texto plano que se incluye como contexto.
Cuándo usarlo: Para el 80% de las features de un MVP. Es rápido de escribir (10-15 minutos) y suficientemente formal para que un agente genere código consistente.
2. OpenAPI para contratos de API
Si tu MVP tiene una API (y casi todos la tienen), una especificación OpenAPI es el contrato que conecta frontend, backend y cualquier agente de IA que consuma o genere endpoints. Los agentes modernos interpretan OpenAPI directamente y generan código que respeta el schema.
Cuándo usarlo: Cuando hay múltiples consumidores de tu API (app mobile, web, integraciones de terceros) o cuando un agente de IA va a generar tanto el backend como el frontend.
3. Gherkin para flujos críticos
Gherkin (Given-When-Then) no es solo para testing. Es un formato que describe comportamiento esperado de forma que tanto humanos como IA lo entienden sin ambigüedad. Ideal para flujos donde un error tiene impacto real: pagos, registro, permisos.
Feature: Checkout con múltiples divisas
Scenario: Usuario completa compra en EUR
Given un usuario con carrito de 3 productos
And la divisa seleccionada es EUR
When confirma el pago con Stripe
Then el cargo se procesa en EUR
And recibe confirmación por email en menos de 30 segundos
Scenario: Fallo de pago muestra error comprensible
Given un usuario en el paso de confirmación
When el pago falla por fondos insuficientes
Then ve el mensaje "Tu banco ha rechazado el pago"
And no ve códigos de error técnicos 4. "Constitución" del proyecto
Un documento breve (20-40 líneas) que define las reglas inmutables del proyecto: patrones de arquitectura, convenciones de naming, dependencias permitidas, estructura de carpetas. Este documento se carga como contexto permanente en el agente de IA (lo que en la disciplina de context engineering se denomina "contexto curado"), asegurando que todo código generado respete los estándares del equipo.
Ejemplo de herramientas: CLAUDE.md para Claude Code, .github/copilot-instructions.md para Copilot, .cursorrules para Cursor. El formato varía, la función es la misma.
5. onext SDD Plugin
Plugin desarrollado por onext que integra SDD directamente en el flujo de trabajo del equipo. Genera templates de especificación adaptados al stack del proyecto, valida que el código generado por IA cumpla las restricciones definidas en la spec, y mantiene la "constitución" del proyecto sincronizada con el agente. Diseñado para equipos que usan Claude Code, Copilot o Cursor como agentes principales.
El sesgo del "Quick Ship" y cómo neutralizarlo
El sesgo del Quick Ship es una trampa cognitiva: equipos priorizan la velocidad percibida (líneas de código escritas, features "terminadas") sobre la velocidad real (features que funcionan correctamente en producción sin rework posterior).
Con la llegada de la IA agéntica, este sesgo se intensifica. Un agente puede generar miles de líneas de código en minutos. La tentación de "ya lo arreglaremos después" es mayor que nunca. Pero el coste de arreglar después también es mayor, porque el agente ha construido capas sobre capas de suposiciones incorrectas.
Tres señales de que tu MVP sufre el sesgo del Quick Ship
- Los pull requests generados por IA requieren más de 2 rondas de revisión. Si el agente no entiende el contexto, genera código que necesita corrección constante. Eso no es velocidad, es rework disfrazado.
- Diferentes developers implementan la misma lógica de formas distintas. Sin especificación compartida, cada persona (y cada agente) toma decisiones de diseño diferentes. El resultado es un codebase inconsistente que se vuelve exponencialmente más difícil de mantener.
- El equipo descubre "sorpresas" en integración. El frontend esperaba un formato de datos. El backend devuelve otro. La API asumía autenticación por token, el mobile la esperaba por cookie. Cada sorpresa es una decisión no documentada.
SDD no es waterfall. Es disciplina mínima.
Thoughtworks, en su análisis de SDD para el Technology Radar, advierte de un riesgo real: que los equipos confundan SDD con un retorno al big design up front. Es una preocupación válida.
"Dentro de prácticas emergentes como el spec-driven development, hemos notado el riesgo de revertir a antipatrones clásicos de ingeniería de software, especialmente el sesgo hacia especificación pesada up-front y releases big-bang."
— Thoughtworks, Technology Radar Vol. 33
La respuesta está en la proporcionalidad. Una spec de 20 líneas para una feature de un MVP no es waterfall. Es la misma disciplina que aplicamos cuando escribimos un test antes de programar (TDD). Nadie argumenta que escribir tests es "overhead" incompatible con la agilidad. Las especificaciones para IA son el equivalente: documentar la intención antes de ejecutar.
El objetivo no es documentar todo. Es documentar lo suficiente para que las decisiones críticas no queden en la cabeza de una persona (o peor, en la inferencia estadística de un LLM).
Cómo empezar con SDD en tu próximo MVP
No necesitas adoptar SDD de forma completa para ver resultados. Estos son los pasos para empezar:
Paso 1: Identifica las 3-5 decisiones críticas del MVP
Antes de escribir código, lista las decisiones que, si se toman mal, generarán más rework. Normalmente son: modelo de datos, contratos de API, flujos de usuario críticos, y restricciones técnicas (compliance, performance, integraciones).
Paso 2: Escribe una spec ligera para cada una
Usa prosa estructurada en Markdown. 15-20 líneas por spec. Incluye: problema, restricciones, criterios de aceptación, integración con código existente. Tiempo total: 2-4 horas para un MVP típico.
Paso 3: Crea la "constitución" del proyecto
Un archivo con las reglas inmutables: patrones de arquitectura, convenciones de naming, dependencias permitidas. Este archivo se carga como contexto en tu agente de IA. Tiempo: 1-2 horas, una sola vez.
Paso 4: Usa las specs como input para el agente
En lugar de escribir prompts ad hoc, referencia la spec al pedir a Claude Code o Copilot que genere código. El agente produce código que respeta las restricciones documentadas.
Paso 5: Revisa contra la spec, no solo contra el código
En code review, la primera pregunta no es "el código está bien escrito". Es "el código cumple la especificación". Si no hay spec, ese es el primer problema a resolver.
Inversión total: 1-2 días de especificación antes de empezar a programar. Retorno típico: 3-5 semanas de rework evitado. ROI conservador: 10-15x sobre el tiempo invertido.
Conclusión: la velocidad real no se mide en líneas de código
El sesgo del Quick Ship nos ha enseñado a medir velocidad en features shipped, líneas escritas, sprints completados. Pero la velocidad que importa es otra: cuánto tarda una feature en funcionar correctamente en producción, sin rework posterior, y mantenerse estable a lo largo del tiempo.
SDD no ralentiza la entrega. Elimina las iteraciones destructivas que la ralentizan. Los equipos que lo adoptan no escriben menos código. Escriben el código correcto antes, y evitan escribir el mismo código tres veces.
En un mundo donde los agentes de IA pueden generar miles de líneas en minutos, la habilidad más valiosa ya no es programar rápido. Es especificar con precisión qué hay que construir. Eso es Spec-Driven Development. Y eso es lo que separa a los equipos que entregan de los que retrabajan.
2 días de especificaciones evitan 5 semanas de rework. Los números hablan solos.