Escribiste una spec el lunes. Describía el flujo de compra: tres pasos, un camino de invitado, sin tarjetas guardadas. El viernes el código tiene opción de tarjeta guardada, un camino exprés de dos pasos y un campo de cupón que nadie pidió. La spec sigue diciendo tres pasos y sin tarjetas guardadas.
Ni la spec ni el código mienten a propósito. Simplemente han dejado de contar la misma historia. Esa distancia es el spec drift, y en cuanto empiezas a buscarla la encuentras en todas partes donde un agente toca la base de código.
Qué es el spec drift en realidad
El spec drift es la distancia creciente entre el contrato que escribiste y el comportamiento que ahora se publica. Es el modo de fallo que el desarrollo guiado por especificaciones existe para evitar, y al que sucumbe en silencio cuando nadie mantiene el contrato. La spec describió la intención en un momento. El código siguió moviéndose. Cada cambio que aterriza sin actualizar el contrato ensancha el hueco.
No es lo mismo que una spec mala. Una spec mala está equivocada el día que la escribes. Una spec con drift era correcta y se quedó rancia. La diferencia importa, porque una spec con drift es más peligrosa que una obviamente equivocada. Sigue pareciendo autoridad. La gente la sigue citando en las reviews. Los agentes la siguen leyendo como verdad de base. Tiene la forma de un contrato y el contenido de un rumor.
Se supone que la spec es el contrato entre intención e implementación. El drift rompe ese contrato en silencio, sin mensaje de error.
Por qué los agentes lo empeoran, no lo mejoran
El drift es un problema viejo. La documentación se pudre desde el primer README. Lo que ha cambiado es el ritmo.
Cuando cada línea la escribía una persona, el drift se acumulaba a velocidad humana. Tocabas tres archivos al día y recordabas más o menos lo que decía la spec. Ahora un agente toca treinta archivos en una tarde y no arrastra tu memoria del contrato entre ejecuciones. Arrastra el contexto que cargaste en esa sesión. Los agentes pierden contexto entre sesiones por defecto, así que la segunda ejecución no sabe qué prometió la primera, y ninguna de las dos actualiza el documento que archivaste el lunes.
Lanza varias sesiones en paralelo y la cosa empeora. Cada una es razonable en local. Cada una empuja el código un poco más lejos del contrato escrito. Los agentes van a derivar lo planifiques o no, y la spec suele ser la primera baja porque nada obliga a una ejecución a reconciliarse contra ella.
El resultado es conocido: código localmente correcto y globalmente incoherente. Cada diff pasó su review en sus propios términos. El sistema completo ya no coincide con lo que dijiste que estabas construyendo.
Los cuatro sitios donde se esconde el drift
El drift rara vez es una gran divergencia. Son cien pequeñas, y se acumulan en sitios predecibles.
1. Comportamiento que la spec nunca mencionó
El agente añadió el campo de cupón. Funciona. Tiene tests. La spec no sabe que existe. El comportamiento nuevo sin contrato es la forma más común de drift, y la más difícil de notar, porque no hay nada en la spec que lo contradiga.
2. Restricciones que el código rompió en silencio
La spec decía «sin tarjetas guardadas». En algún refactor, una capa de caché empezó a guardar una tarjeta tokenizada durante la sesión. Nadie decidió violar la restricción. Se coló en un cambio que parecía no tener relación. Los límites rotos son el drift más caro, porque la restricción solía estar ahí por una razón que ahora has olvidado.
3. Decisiones que se revirtieron sin una nota
La spec del lunes eligió actualizaciones optimistas de la UI. El arreglo del jueves cambió a confirmación por servidor porque las optimistas provocaban un parpadeo. Buena decisión. Pero la spec sigue defendiendo el enfoque abandonado, así que el siguiente agente que la lea intentará «arreglar» el código de vuelta al parpadeo.
4. Criterios de aceptación que ya no coinciden
Los criterios de aceptación de la spec describían el flujo de tres pasos. El flujo ahora tiene dos. Los criterios pasan porque nadie los ejecuta contra el comportamiento actual, o fallan y todos han aprendido a ignorar ese rojo concreto. En cualquier caso, el contrato ha dejado de significar algo.
El coste que ya estás pagando
El drift no te manda una factura. Te cobra en reviews más lentas, en agentes que construyen con confianza contra un contrato rancio, y en la reunión donde dos personas descubren que trabajaban con versiones distintas de la verdad. Es el sustrato del problema del «yo nunca acordé eso»: la spec decía una cosa, el producto hace otra, y nadie puede reconstruir cuándo se separaron.
El coste más hondo es la confianza. En cuanto un equipo aprende que la spec podría estar mintiendo, deja de leerla. Y una spec en la que nadie confía es peor que ninguna, porque pagaste por escribirla y aun así no puedes apoyarte en ella.
Cazar el drift antes de que se componga
No puedes evitar el drift. El código cambia; para eso está. Lo que sí puedes hacer es acortar la distancia entre que un cambio aterriza y que el contrato lo alcanza.
Unas cuantas cosas ayudan en la práctica:
- Haz que actualizar la spec sea barato. Si actualizar el contrato es una ceremonia, nadie lo hace con una fecha límite encima. Este es todo el argumento de un flujo spec-driven ligero: una spec lo bastante pequeña como para que mantenerla al día no sea un proyecto en sí mismo.
- Reconcilia al final de una ejecución, no al final de un trimestre. El momento de actualizar el contrato es cuando el cambio está fresco, antes de que la siguiente sesión olvide por qué pasó.
- Ancla la spec al código, no a una carpeta. Un contrato que vive junto a la implementación y la evidencia se puede contrastar con la realidad. Un contrato que vive en un documento que tienes que acordarte de abrir, no. Esta es la idea de fondo de la documentación viva: docs que se actualizan como subproducto del trabajo en vez de como tarea aparte.
- Trata la spec como portable, no desechable. Una especificación portable que lleva su intención, decisiones y evidencia entre herramientas es mucho más difícil de abandonar que un archivo Markdown que un agente escribió y el siguiente ignoró.
Todo esto apunta en la misma dirección: dejar de tratar la spec como un documento que escribes una vez y empezar a tratarla como una especificación viva que se mueve con el código.
Dónde encaja PaellaDoc
El spec drift es el problema alrededor del que está construido PaellaDoc. En vez de una spec que se queda en una carpeta mientras los agentes reforman el código a su lado, el contrato vive en un modelo local conectado al producto, al repositorio y a la evidencia de cada ejecución. Cuando un cambio aterriza, la spec es un sitio contra el que reconciliar ese cambio, no un archivo que alguien tiene que recordar que existe. La idea no es congelar el código. Es asegurar que, cuando el código se mueve, la historia que contaste sobre él se mueva también.
Preguntas frecuentes
¿El spec drift es lo mismo que la deuda técnica? No. La deuda técnica es un hueco entre el código y un diseño sano. El spec drift es un hueco entre el código y el contrato que escribiste sobre él. Puedes tener código limpio que ha derivado mucho de su spec, y una base de código desordenada cuya spec está perfectamente al día.
¿Puedo borrar la spec cuando el código ya funciona? Puedes, y mucha gente lo hace. El problema aparece después, cuando un agente o compañero nuevo necesita cambiar el código y no hay registro de qué tiene que seguir siendo cierto. Borrar una spec con drift quita el síntoma y conserva la enfermedad.
¿Con qué frecuencia hay que actualizar una spec? Al ritmo del trabajo, no del calendario. El momento útil es cuando un cambio aterriza y la razón sigue fresca. Agrupar las actualizaciones de spec para más tarde es justo como se acumula el drift.