Errores comunes al hacer Spec-Driven Development (y cómo evitarlos)

Escribes una especificación impecable. Se la pasas al agente. Y aun así, dos semanas después, estás peleando con un código que ya no se parece a lo que pediste y con un documento que nadie ha vuelto a tocar.

Si te suena, no es que el Spec-Driven Development no funcione. Es que casi todo el mundo lo empieza cometiendo los mismos errores, y casi ninguno tiene que ver con la herramienta que elijas.

El SDD es, en una frase, lo opuesto al vibe coding: en vez de pedirle cosas a la IA por las vibras e ir corrigiendo sobre la marcha, defines de antemano qué quieres que haga el software para que el agente lo construya sin inventarse la mitad. Suena bien. Pero el método tiene trampas, y son trampas de mentalidad, no de comandos.

Aquí van los errores más caros que vas a cometer (o ya estás cometiendo). Empezamos por los tres que más tardes te roban.

Error 1: tratar la spec como una losa inmutable ¶

Este es el error que convierte el SDD en waterfall con otro nombre.

La idea de “defínelo todo antes de escribir una línea de código” viene de sitios donde no te queda otra: la NASA especificaba hasta el último botón de las naves Apolo porque, una vez arriba, no podías enchufar un cable y parchear. En el espacio no se cambia nada.

El problema es que tu API no se va al espacio. Y cuando tratas la especificación como si fuera intocable —“esto está escrito aquí, así que no se mueve”— resucitas exactamente la rigidez que el agilismo llevaba dos décadas combatiendo. Cada cambio de requisito se vive como una herejía, la spec original se vuelve sagrada, y acabas sometido a un documento en lugar de servirte de él.

Cómo evitarlo: mentalidad híbrida. La spec te da orden y guardarraíles para que el agente no se escape por las ramas, pero sigue siendo flexible. No olvides que al otro lado hay un cerebrito enchufado con el que puedes conversar: si a mitad de la implementación ves que algo no encaja, le dices “para, esto hazlo de esta otra forma” y ajustas la spec. Orden sin dogma. La especificación manda sobre el caos, no sobre tu criterio.

Error 2: acabar manteniendo dos fuentes de verdad ¶

Este es, para mí, el problema principal del SDD mal aplicado, y el que hace que mucha gente lo abandone a las dos semanas.

Ya nos costaba mantener el código. Si ahora le sumas mantener una especificación detallada y sincronizada con ese código, tienes dos fuentes de verdad que se desincronizan a la primera de cambio. Y seamos honestos: a nadie, nadie en su sano juicio, le apetece mantener código y documentación a la vez. La doc se queda vieja, el código avanza, y en un mes la spec miente.

Cómo evitarlo: que la spec capture intención, no detalle. La gracia de la programación asistida por IA de los últimos meses es que el agente entiende tu código leyéndolo, no leyendo un documento que describe el código. Ya sabe cómo montas tus componentes de frontend o tus rutas de backend mirando los que ya tienes. Así que no dupliques esa realidad en prosa.

Reserva la especificación para lo que el código no te cuenta: el porqué, los criterios de aceptación, los límites no negociables. Para lo demás, deja que la documentación viva implícita en el código y, cuando necesites texto, genéralo con la IA a partir del repositorio y limítate a revisarlo. Especificas la intención de una feature nueva, no reescribes un espejo del proyecto entero cada semana.

Error 3: medir el SDD con el cronómetro del vibe coding ¶

Te sientas a escribir la especificación y notas que no estás programando. Una tarde “perdida” en un documento mientras a tu alrededor todo el mundo habla del vibe coding como si fuera magia: piensas algo y aparece el resultado. La acción parece ralentizarse, y la tentación de abandonar el método y volver al chat improvisado es enorme.

Es una comparación tramposa. El vibe coding es rápido en el primer borrador y carísimo después: cuando a los tres días no entiendes qué hace el código, cuando el agente toca lo que no debía, cuando tienes que rehacer la mitad de lo que entregó casi bien. Ese tiempo no aparece en el cronómetro del primer día, pero lo pagas igual.

Cómo evitarlo: cambia lo que mides. El cuello de botella de programar nunca fue teclear; era traducir una intención ambigua a código que el equipo entienda y mantenga. El SDD mete ese trabajo al principio, donde es barato, en lugar de al final, donde es caro. No compares “tiempo hasta el primer código que compila”, compara “tiempo hasta el código que no tienes que rehacer”. Con esa vara, el SDD casi siempre gana.

Hasta aquí los tres errores de mentalidad. Pero hay tres más, y duelen más precisamente porque parecen buenas prácticas: los cometes pensando que lo estás haciendo bien, y te das cuenta cuando ya has perdido la tarde.