Hay un patrón que se repite en muchos proyectos de software: el equipo arranca con energía, hay reuniones, hay un Trello con tickets, hay código en GitHub, hay despliegues. Y a los tres meses alguien dice en voz baja lo que todo el mundo piensa: “esto no es lo que pedimos”.

No es un fallo de programación. Es un fallo de definición.

Spec-Driven Development es el nombre que se le está dando a una disciplina muy simple en su enunciado y muy difícil en su práctica: definir qué hay que construir antes de empezar a construirlo, y dejar esa definición por escrito de forma que cualquiera del equipo —incluido un asistente de IA— pueda leerla y entenderla igual.

Qué es Spec-Driven Development

Spec-Driven Development (SDD) es una metodología de desarrollo de software que pone la especificación escrita como el artefacto central del proyecto, anterior al código. La especificación describe qué se va a construir, con qué restricciones, qué entradas y salidas tiene cada componente, y qué decisiones técnicas ya están tomadas. El código se escribe contra esa especificación, no contra una intuición compartida en una llamada de Zoom.

No es un BRD de cien páginas. No es un Gantt. Es un documento corto, vivo y verificable.

Por qué los proyectos fracasan sin especificación

Los problemas no aparecen el día 1. Aparecen cuando el equipo crece, cuando entra alguien nuevo, cuando hay que tomar una decisión técnica y nadie recuerda por qué se eligió Postgres en lugar de Mongo, o cuando el cliente revisa el primer demo y se da cuenta de que entendía algo distinto.

Estas son las señales típicas de un proyecto sin spec:

Cada developer interpreta el ticket a su manera
Las decisiones técnicas se toman de palabra y se olvidan
El testing es reactivo: se descubre que algo no encaja cuando ya está construido
Los cambios de alcance no son cambios — son malentendidos que afloran tarde
La revisión de código se vuelve subjetiva: “esto no me gusta” en lugar de “esto no cumple X”

La consecuencia es siempre la misma: se entrega más tarde, con más código del necesario, y con un equipo desconfiado de su propio proceso.

Qué cambia cuando hay un contrato escrito

Cuando existe una especificación clara antes de empezar a programar, pasan cuatro cosas concretas.

Las decisiones se discuten una vez. No se vuelve a hablar cada semana de si los IDs serán uuid o autoincremental, porque está en el documento. Si alguien quiere cambiarlo, lo cambia en la spec primero y eso obliga a justificar el cambio.

Los desacuerdos salen a la luz pronto. Las dos personas que pensaban que “el módulo de facturación” significaba cosas distintas lo descubren leyendo la spec, no integrando dos commits incompatibles tres semanas después.

El testing se vuelve trivial. Cada requisito de la spec es un test. No hay que inventar qué probar, lo dice el documento.

La IA pasa de ayudante errático a ejecutor fiable. Cuando le das a un asistente como Claude un trozo de código y le pides que lo modifique, sin contexto improvisa. Cuando le das la spec, ejecuta dentro de unos límites claros y los respeta.

Este último punto es la diferencia entre usar IA como un autocompletado caro o usarla como un programador junior bien instruido.

El dato detrás de esto

Hay investigación reciente sobre lo que mejora la fiabilidad de los asistentes de código generativos. Según el estudio de la Universidad de Princeton sobre Generative Engine Optimization (KDD 2024), los modelos de lenguaje producen resultados un 30-40% más consistentes cuando trabajan a partir de un contrato estructurado que cuando se les pide directamente desde lenguaje natural ambiguo.

Y antes de que existiera la IA generativa, la industria ya tenía décadas de evidencia parecida: los proyectos con especificación previa entregan, en promedio, en menos tiempo y con menos retrabajo. La novedad no es la idea — es que ahora la spec es lo que diferencia un equipo que rentabiliza la IA de uno que se ahoga en código generado a ciegas.

Spec-Driven Development en la práctica: cómo se ve un día

No todo proyecto necesita una spec de la misma profundidad. Una corrección de bug puede vivir con un párrafo en el ticket. Un módulo nuevo, no.

Una spec funcional típica para un módulo de tamaño medio incluye:

Objetivo del módulo en una frase
Casos de uso principales (no todos, los importantes)
Restricciones técnicas ya tomadas (stack, integraciones, performance)
Datos: qué entra, qué sale, qué se persiste
Decisiones explícitas: por qué A y no B, para que dentro de seis meses nadie discuta lo ya discutido
Criterios de aceptación verificables

Eso suele caber en una página y media. Y se actualiza a medida que el proyecto avanza, no se escribe una vez y se archiva.

Cuándo NO aplicar Spec-Driven Development

Hay tareas donde imponer una spec añade fricción sin retorno. Conviene ser honesto con esto:

Bugs simples: si el ticket es claro, escribir spec es burocracia
Spike o prueba de concepto: la spec llega DESPUÉS del spike, no antes
Equipos de una sola persona en proyectos pequeños: la spec sobra cuando todo el contexto está en una sola cabeza, aunque el momento en que dejas de ser una persona, la spec deja de ser opcional
Trabajo creativo exploratorio: si todavía no sabes qué quieres construir, la spec será inventada y peor que nada

La regla práctica: usa SDD cuando el coste de un malentendido sea mayor que el coste de escribir el documento. Casi siempre lo es.

Preguntas frecuentes

¿Spec-Driven Development es lo mismo que Waterfall?

No. Waterfall asume que la spec se escribe entera al principio y no cambia. SDD asume que la spec evoluciona a medida que el proyecto avanza, pero cualquier cambio se documenta antes de tocar código. Es iterativo, pero con contrato.

¿Cómo encaja SDD con metodologías ágiles?

Encaja bien. Cada sprint o ciclo puede tener su mini-spec. La diferencia con Scrum puro es que el “ticket” deja de ser una frase tipo “Como usuario quiero…” y se convierte en un mini-contrato verificable.

¿Qué herramientas se usan para mantener la spec?

Cualquier formato versionable: Markdown en el repo, Notion, Confluence, Google Docs. Lo importante no es la herramienta — es que la spec viva al lado del código y se modifique con la misma seriedad que el código.

¿Cuánto tiempo se tarda en escribir una spec antes de programar?

Para un módulo medio: entre dos y seis horas iniciales, más actualizaciones puntuales durante el proyecto. Suena mucho hasta que comparas con las decenas de horas que ahorra al evitar reescribir código construido sobre malentendidos.

¿Necesito SDD si trabajo solo con IA?

Más que nunca. Una IA sin spec genera código mediocre. Una IA con spec genera código que encaja en tu proyecto. La diferencia se nota desde el primer prompt.

Spec-Driven Development no es una moda. Es lo que algunos equipos llevan haciendo bien desde hace años, y lo que otros llaman ahora con un nombre nuevo porque la IA generativa lo ha convertido en condición necesaria, no en buena práctica opcional.

Si quieres ver el flujo de trabajo paso a paso —cómo escribimos la spec, cómo la mantenemos viva, cómo le pasamos contexto a Claude para que ejecute dentro de ese contrato—, te lo enseño en una serie de vídeos en preparación. Cuando esté lista, te aviso al email que dejes.