Casi todas las guías de Spec Driven Development —incluida la mía— te enseñan a empezar desde cero. Hoja en blanco, specify init, una constitución reluciente y un proyecto que nace ordenado. Y está muy bien… salvo por un detalle: casi nunca empiezas desde cero.

La realidad del 90 % de los desarrolladores es otra. Tienes un proyecto que ya está en producción. Lleva meses funcionando. Tiene usuarios, tiene tests, tiene una arquitectura… y tiene cero especificaciones, porque se construyó en la época del vibe coding, cuando todos abríamos un chat con la IA y dejábamos que improvisara. Ahora te toca añadirle una funcionalidad nueva y aparece la pregunta incómoda: ¿ya es tarde para hacer SDD aquí? ¿Tengo que reescribir el proyecto entero?

La respuesta corta es no. No es tarde y no tienes que reescribir nada. Este artículo es la guía práctica, en español, de cómo meter Spec Driven Development en un proyecto que arrancó sin él. Si todavía no tienes claro el concepto base, empieza por mi guía completa de qué es Spec Driven Development →PILLAR y vuelve aquí: este post asume que ya sabes qué es una constitución y cuáles son las cinco fases.

El mito de que SDD solo sirve para proyectos nuevos

En la guía general dejé escrito que aplicar SDD a un codebase legacy puede ser un esfuerzo de meses. Es verdad, pero conviene matizarlo, porque «legacy» mete en el mismo saco dos cosas muy distintas:

• Legacy de verdad: cientos de miles de líneas, sin tests, sin convenciones, sin nadie que recuerde por qué las cosas son como son. Aquí sí: extraer especificaciones del código es un proyecto lento y por módulos. No es lo que vamos a ver hoy.
• Proyecto en producción sano: un código que funciona, tiene tests y sigue unas convenciones razonables, aunque nunca se escribiera una sola spec. Esto se incorpora a SDD en una tarde, y es el caso de la inmensa mayoría de proyectos reales.

La diferencia clave no es el tamaño ni la antigüedad. Es si tienes una red de seguridad —tests— y unas convenciones reconocibles. Si las tienes, meter SDD no solo es viable: es una de las mejores decisiones que puedes tomar antes de dejar que un agente toque tu código.

Porque el riesgo de no hacerlo es real. El código generado por IA sin un contrato claro arrastra bastantes más vulnerabilidades y mucho más retrabajo que el escrito con disciplina —los datos los desgloso en la guía general—. En un proyecto que ya está en producción, ese riesgo no es teórico: es tu viernes por la tarde revisando por qué algo que funcionaba ha dejado de funcionar.

La idea clave: la constitución no inventa reglas, las fotografía

Aquí está el cambio mental que lo hace todo posible, y es lo que diferencia aplicar SDD a un proyecto nuevo de aplicarlo a uno existente.

Cuando empiezas de cero, la constitución es prescriptiva: define hacia dónde quieres ir. Decides tus reglas y el proyecto nace cumpliéndolas.

Cuando el proyecto ya existe, la constitución es descriptiva: no inventa nada, fotografía las convenciones que el código ya tiene de facto. El patrón de arquitectura que ya usas, la forma en que nombras las cosas, los tests que no se pueden tocar, las URLs de tu API que no pueden cambiar. Todo ese conocimiento que hoy vive en la cabeza del equipo —o en la de nadie— lo pasas a un documento que el agente está obligado a respetar.

Esto es lo que en mi canal llamo soberanía arquitectónica llevada a un proyecto vivo: en lugar de rezar para que la IA «lo haga bien», le dices exactamente qué significa «bien» en este proyecto concreto. La constitución deja de ser una declaración de intenciones y se convierte en el contrato que protege tu código existente de las decisiones implícitas del agente.

Y este es justo el problema que el vibe coding ignora en producción: tú le pides «añade comentarios a las tareas» y el modelo, con toda su buena intención, igual mete las queries directamente en el controlador, se salta tu patrón de repositorio, cambia una respuesta JSON o toca un test que ya funcionaba. No porque sea malo, sino porque no conoce tus reglas si no se las escribes.

Cómo aplicar SDD a un proyecto existente, paso a paso

El flujo es el de siempre (constitution → specify → clarify → plan → analyze → tasks → implement), pero hay diferencias importantes en cómo arrancas. Vamos con spec-kit, la herramienta oficial de GitHub, y Claude Code como agente.

1. Inicializa spec-kit DENTRO del repo que ya tienes

Esta es la primera diferencia con un proyecto nuevo. Allí haces specify init mi-proyecto y se crea una carpeta. Aquí no quieres una carpeta nueva: quieres meter spec-kit en lo que ya existe. Para eso está el flag --here.

Instala la CLI (recuerda: el único paquete oficial es el del repositorio github/spec-kit):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Y, situado en la raíz de tu proyecto, inicialízalo in situ:

specify init --here

Te avisará de que el directorio no está vacío. Es normal: tiene tu código. Le dices que sí. Como tu proyecto está en Git —y debe estarlo antes de hacer esto—, cualquier cosa rara la ves en el git diff y la reviertes. Durante la inicialización eliges tu agente (en versiones recientes con --integration claude; en otras el flag es --ai claude, o simplemente lo seleccionas en el menú interactivo). Aparecerán la carpeta .specify/ y los comandos slash, sin tocar tu código.

Aviso que te ahorra un disgusto: si en el futuro actualizas spec-kit con specify init --here --force, hay un comportamiento conocido que puede sobrescribir tu constitution.md con la plantilla por defecto. Antes de actualizar, haz copia de tu constitución.

2. Escribe una constitución que capture tus convenciones

Con el agente abierto, lanza /speckit.constitution y, en lugar de inventar reglas, descríbele las que tu proyecto ya sigue. Pídele explícitamente que analice el código antes de escribir. Los principios que de verdad importan en un proyecto existente son del tipo:

• El patrón de arquitectura que ya usas es obligatorio (por ejemplo, toda la persistencia vive en una capa de repositorios y los controladores no acceden a la base de datos).
• Las convenciones de nombres y de serialización actuales se respetan.
• Los tests existentes son sagrados: no se modifican y deben seguir pasando exactamente igual.
• No se rompe la API pública: ni URLs, ni métodos HTTP, ni formatos de respuesta ya existentes. Las features nuevas añaden, no modifican.
• El stack está congelado: no se añaden dependencias nuevas sin justificación.

Esta constitución es la que después, en la fase de plan, dispara el Constitution Check: una verificación que impide que el agente proponga algo que viole tus reglas. Si intentara meter una query donde no debe, la constitución se lo prohíbe.

3. (Opcional) Documenta lo que ya existe con una baseline spec

En proyectos grandes, antes de pedir nada nuevo, conviene un paso extra: un /speckit.specify que no pide ninguna feature, solo documenta lo que el proyecto ya hace. Le da al agente el mapa completo del terreno antes de tocarlo. En proyectos pequeños no hace falta —la constitución ya captura lo esencial—, pero si tu API tiene muchos módulos, esta baseline evita que el agente trabaje a ciegas.

4. Especifica la feature nueva (sin tecnicismos todavía)

Ahora sí, /speckit.specify para lo que quieres añadir. Describe el qué y el porqué, nunca el cómo: qué hace la funcionalidad, qué reglas de negocio tiene, qué casos límite contempla. Nada de modelos ni de librerías; eso es la fase de plan. Si algo queda ambiguo, pasa /speckit.clarify antes de seguir: el agente te hará preguntas para cerrar huecos.

5. Plan, análisis, tareas e implementación

A partir de aquí, el flujo es el canónico:

/speckit.plan       → el cómo técnico, respetando la constitución
/speckit.analyze    → validación cruzada entre constitución, spec y plan
/speckit.tasks      → tareas atómicas y ordenadas por dependencias
/speckit.implement  → ejecución, tarea a tarea

La gracia es que, en cada uno de estos pasos, el agente vuelve a chequear tu constitución. Cuando planifica, «sabe» que el controlador no puede tocar la base de datos, así que coloca la lógica en la capa correcta. Solito. Porque se lo escribiste como ley.

6. Verifica que NO has roto nada

Y llegamos al paso que de verdad importa en producción. Cuando el agente termina, lanzas toda tu batería de tests. Si los que ya tenías siguen en verde, no has roto nada. Si además los nuevos pasan, has añadido una funcionalidad completa sin tocar lo que funcionaba. Esa es la diferencia entre soltarle un prompt al agente y rezar, y darle un marco donde solo puede hacerlo bien.

Caso práctico: añadir comentarios a una API Flask con 57 tests

Para que no se quede en teoría, lo apliqué a un proyecto real en el vídeo de la serie: TaskFlow, una API REST en Flask con patrón Repository y 57 tests en verde, construida sin SDD. El encargo: añadir comentarios a las tareas —modelo nuevo, endpoints nuevos, tests nuevos— sin romper la API existente ni tocar ninguno de los 57 tests.

El resultado fue exactamente el que busca esta metodología: feature completa, los 57 tests originales intactos, y la vista nueva respetando el patrón de repositorio igual que el resto del proyecto. Todos los prompts y comandos del vídeo (incluida la constitución descriptiva completa) están en el repositorio: github.com/JoaquinRuiz/spec-driven-development-produccion.

Errores comunes al meter SDD en código existente

Cuatro tropiezos que veo una y otra vez:

1. Querer reescribir el proyecto. SDD no exige tocar lo que ya funciona. Se incorpora encima de tu código actual; las features nuevas siguen el flujo, las viejas se quedan como están.
2. Escribir una constitución prescriptiva en un proyecto existente. Si defines reglas que tu código todavía no cumple, generas conflicto en cada paso. Primero fotografía la realidad; reformar convenciones es otro trabajo, posterior.
3. Empezar sin tests. Los tests son tu red de seguridad: sin ellos no puedes verificar que no has roto nada. Si tu proyecto no tiene, el primer paso no es SDD, es generar una batería de tests sobre el comportamiento actual.
4. Olvidar que el agente lee la spec del propio repositorio. Por eso la spec y la constitución viven dentro del proyecto, versionadas junto al código. No es estética: es lo que hace que el flujo funcione.

Preguntas frecuentes

¿Puedo usar Spec Driven Development si mi proyecto no se empezó con specs?

Sí. No necesitas reescribir nada. Inicializas spec-kit dentro del repositorio existente con specify init --here, escribes una constitución que capture las convenciones que el proyecto ya tiene, y a partir de ahí aplicas el flujo de SDD a las funcionalidades nuevas. El código antiguo se queda como está.

¿Tengo que reescribir mi código para aplicar SDD?

No. SDD se incorpora encima de tu proyecto actual. Las features nuevas pasan por el flujo (constitución, spec, plan, tareas, implementación) y el código existente no se toca, salvo lo justo para registrar lo nuevo.

¿Cómo inicializo spec-kit en un proyecto que ya existe?

Con el flag --here: situado en la raíz del proyecto, ejecutas specify init --here. A diferencia de un proyecto nuevo, esto no crea una carpeta aparte, sino que añade la estructura de spec-kit dentro de tu repositorio. Ten el proyecto en Git antes de hacerlo.

¿Necesito tests para aplicar SDD a un proyecto en producción?

Son muy recomendables. Los tests existentes funcionan como red de seguridad: te permiten verificar que la funcionalidad nueva no ha roto lo que ya funcionaba. Si tu proyecto no tiene tests, el primer paso debería ser crearlos sobre el comportamiento actual antes de añadir nada con la IA.

¿Qué diferencia hay entre la constitución de un proyecto nuevo y la de uno existente?

En un proyecto nuevo la constitución es prescriptiva: define las reglas que quieres seguir. En uno existente es descriptiva: documenta las convenciones que el código ya sigue, para que el agente las respete en lugar de improvisar las suyas.

¿Funciona SDD en proyectos legacy muy grandes?

Depende. Un proyecto en producción con tests y convenciones razonables se incorpora a SDD en una tarde. Un legacy enorme sin tests ni documentación es un esfuerzo mayor, que se aborda por módulos y de forma incremental, extrayendo especificaciones del código poco a poco.

Empieza por aquí

Si quieres aplicar esto a tu propio proyecto, este es el orden que te recomiendo:

1. Repasa, si te hace falta, la guía completa de Spec Driven Development para tener claras las cinco fases.
2. Mira el vídeo del caso práctico y clónate el repositorio con todos los prompts.
3. Coge un proyecto tuyo que tenga tests, inicialízalo con specify init --here y escribe su constitución descriptiva. La primera vez que veas tus tests seguir en verde tras dejar que la IA añada una feature, lo entiendes para siempre.
4. Suscríbete al canal: estoy publicando la serie completa sobre SDD en español.

Y si quieres entender de verdad qué hay debajo de estos modelos que escriben código por nosotros, tengo tres libros publicados sobre inteligencia artificial, empezando por El motor de la inteligencia artificial, que va justo de eso: dejar de tratar a la IA como una caja negra y entender cómo funciona por dentro.

Meter Spec Driven Development en un proyecto que ya existe no es un lujo de proyectos nuevos. Es la forma de seguir usando la IA en código que importa sin perder el control sobre lo que se construye. No necesitas reescribir tu proyecto. Solo necesitas escribir, por una vez, las reglas que hasta ahora vivían en tu cabeza.

Nos vemos en el próximo artículo. ¡Que la IA te acompañe!