Spec Drift: ¿qué pasa cuando los requerimientos cambian?

El spec drift es el error más común al programar con inteligencia artificial, y aprender a evitarlo con spec-driven development es lo que separa un proyecto que escala de uno que acumula deuda técnica. Si trabajas con agentes como CloudCode y SpecKit, esto te importa.

Imagina que le pides un cambio a la IA con un simple prompt. CloudCode va al backend, modifica el código, hace lo mismo en el frontend y todo parece funcionar. Cierras el computador y te vas a dormir tranquilo. Y aquí viene el problema: acabas de cometer el pecado mortal de la arquitectura asistida por IA.

Qué es el spec drift y por qué es peligroso

El spec drift ocurre cuando el código dice una cosa y las especificaciones del proyecto dicen otra distinta. La aplicación funciona, pero la documentación quedó desincronizada.

¿Qué es el spec drift? Es la desincronización entre el código y las especificaciones de un proyecto. El código funciona correctamente, pero la spec sigue describiendo una lógica de negocio vieja, lo que genera deuda técnica y frena el escalamiento.

Este es justamente uno de los problemas principales de trabajar solo con vibe coding. Se relaciona con el efecto Jenga [01:00]: cuando la IA, por solucionar una funcionalidad, termina afectando otra feature que andaba bien. Como en el juego, mueves una pieza y toda la torre se tambalea.

Por cuál nivel entra un cambio en SpecKit

Cuando llega una solicitud de cambio o una funcionalidad nueva, la regla es clara: un cambio nunca entra por el código. Entra por el artefacto más alto que toca, y desde ahí la cadena se regenera hacia abajo.

Tomemos un caso real [01:30]: el negocio pide cambiar la disponibilidad de reservas de 24 horas a un horario de 7:00 a.m. a 10:00 p.m. La pregunta clave es cuál artefacto toca primero.

• ¿Toca la constitución? No, porque no cambiamos base de datos, tecnología ni lineamientos de código.
• ¿Cambia la lógica de negocio? Sí, cambia la funcionalidad.
• Como las funcionalidades se definen en la spec, ese es el artefacto de entrada.

Identificar el nivel correcto es lo que evita que toques el código a ciegas y generes contradicciones más abajo.

¿Por dónde entra un cambio en spec-driven development? Entra por el artefacto más alto que afecta. Si cambia la lógica de negocio, entra por la spec; si cambia la tecnología o los lineamientos, entra por la constitución. Nunca se empieza modificando el código.

Cómo propagar un cambio con el comando Clarify

Para gestionar el cambio se usa el comando Clarify, que ya conocías. CloudCode modifica la spec y desde ahí propaga todo hacia abajo: spec, funcionalidades, plan, tareas y finalmente la implementación.

El flujo práctico [02:30] arranca en la terminal, parándote en la raíz del proyecto. Estos son los pasos:

1. Crear una rama nueva con git checkout -b change-request-horario-01.
2. Abrir Cloud y ejecutar speckit --clarify indicando el cambio deseado.
3. Dejar que CloudCode identifique los functional requirements e historias de usuario a modificar.

Y aquí pasó algo interesante [03:30]: al escribir el prompt dije que la grilla iba de 7:00 a.m. a 10:00 p.m., pero que el rango excluido era de 10:00 p.m. a 6:00 p.m.. Me equivoqué, era 6:00 a.m. CloudCode detectó la contradicción y me pidió aclararla antes de seguir. Ese cruce entre humano e IA es el pensamiento crítico en acción.

Qué muestra el archivo spec.md tras el cambio

Cuando CloudCode termina, muestra los cambios en spec.md [04:30]. Lo que está en verde con un signo más es lo agregado con la nueva información; lo que está en púrpura con un menos es lo removido, que corresponde a la lógica vieja de 24 horas.

Si no hay ambigüedades con la constitución, el sistema sugiere continuar con speckit plan. Aquí generaste una nueva versión de spec.md, y recuerda que el plan es el puente entre la especificación y las tareas.

Cómo regenerar plan, tareas e implementación

El plan no se genera desde cero. CloudCode identifica solo el cambio nuevo y ajusta el plan.md en consecuencia. Después sigue la cadena completa hasta el código.

• speckit --plan: ajusta el plan de trabajo con el cambio detectado.
• speckit task: divide ese plan en tareas atomizadas que usarán los agentes.
• speckit implement: convierte esas tareas en código real del proyecto.

Para verificar el resultado [06:30], levantas el backend con npm run dev en su carpeta y el frontend con npm run dev. Los comandos están en el archivo quickstart. Al abrir la app, las reservas ya solo permiten de 7:00 a.m. a 21:00, tal como pidió el negocio.

Por qué cambia la spec y no solo el código

Aquí está el poder del spec-driven development [07:30]. Si abres spec.md, la historia de usuario número dos ya indica la grilla de 7:00 a.m. a 10:00 p.m. Y el functional requirement número siete confirma que el club opera de 7:00 a.m. a 22:00.

La diferencia con el vibe coding es enorme: allá el código cambiaba pero la especificación seguía diciendo 24 horas. Aquí cambiamos primero la especificación, y a partir de eso cambia el código. Esa es la sincronización que blinda tu proyecto.

En la era de la inteligencia artificial el código es un commodity; lo verdaderamente invaluable es el pensamiento crítico. Aprendiste a blindar tus ideas en una constitución, dictar reglas de negocio en una especificación y trazar los planos para que la IA trabaje sin desviarse.

Cuéntame en los comentarios cómo te fue, qué problemas tuviste y cómo los resolviste.