//Mantener especificaciones

Escribes la especificación, el agente genera el código, los tests pasan y haces la release. Tres días después el cliente pide que las reservas también notifiquen por email, y ahí se complica la metodología. ¿Qué haces con esa spec cuando el mundo cambia? Porque más temprano que tarde acaba cambiando.

Casi todos los pipelines de Spec-Driven Development que circulan por ahí nacieron pensando en proyectos greenfield, donde cada petición es funcionalidad nueva y cada spec estrena carpeta. Pero el software real es, o se vuelve enseguida, brownfield , y las peticiones que llegan a partir de ahí casi nunca son features nuevas.

Por si fuera poco, los cambios o mejoras en los requisitos, suelen involucrar cambios en las pruebas. Es decir, habrá tests antiguos que fallarán porque ya no se cumplen los criterios de aceptación, o incluso que ya no tengan sentido.

Todo esto junto, nos plantea el dilema de qué hacer con la spec cuando el mundo cambia. Y no hay una solución perfecta, pero si hay varias estrategias que podemos analizar y elegir según el contexto.

Spec-First, especificaciones de usar y tirar

La primera escuela dice que la spec existe exclusivamente para eliminar ambigüedad antes de codificar, y que una vez cumplida esa misión se puede archivar en la papelera sin remordimientos. Es la opción más barata y la que menos disciplina pide, porque nadie tiene que mantener nada y la historia queda contada en Git.

En muchos casos, está bien, porque la documentación ya está en otra parte. La incorporación de un agente al equipo de desarrollo, no cambia nada. Simplemente le especificamos las cosas con detalle optimizando la relación señal/ruido y a otra cosa mariposa.

El precio a pagar es que los agentes no disponen de una fuente cómoda y asequible de información para entender el estado actual del sistema. Cad uno,aterriza en un planeta desconocido, al menos en lo funcional. Las siguientes escuelas, mantienen la especificación, cada una a su manera.

Spec-anchored, especificaciones vivas

La segunda escuela propone una spec por funcionalidad, para siempre. Cuando el requisito cambia no creas ningún documento nuevo, sino que reabres la spec existente y editas sus criterios, de manera que la spec deja de describir un cambio y pasa a describir un estado, igual que hace el código.

Tiene de bueno que el documento esté siempre actualizado con el estado del sistema. Cualquier nuevo agente (todos lo son) puede consultar la spec y conocer el estado actual del sistema. Y cualquier cambio se refleja como una enmienda al documento, sin necesidad de crear uno nuevo.

El problema es que necesita una forma de marcar lo obsoleto, especialmente para los criterios de aceptación. Y, retocar la solución y definición del problema sin un rastro fisico de la historia.

Delta-Specs, especificaciones enlazadas

La tercera escuela genera con cada cambio una spec nueva que referencia a la anterior, formando una cadena de decisiones. Sobre el papel es la más fiel a la realidad, porque conserva el porqué de cada evolución sin reescribir la historia, y a los que venimos de arquitecturas con event sourcing nos resulta hasta familiar.

En la práctica arrastra una pega importante: para saber qué hace el sistema hoy necesitas recorrer toda la cadena de deltas, reconstruyendo el estado a base de aplicar parches. Que es, casualmente, el mismo problema que el Spec-Driven Development venía a resolver. Además de que la lista tiene que ser doblemente enlazada (si alguien ve una spec debe saber si hay alguna posterior que la referencie, y viceversa).

Y un enemigo común a ambas estrategias tiene nombre propio, specification rot, y es más fácil de invocar de lo que parece: basta con que alguien toque la funcionalidad del código sin pasar por la spec para que el documento empiece a desviarse de la realidad. Una documentación que se equivoca todavía tiene arreglo; el problema serio es la que lleva tanto tiempo sin tocarse que ya nadie confía en ella.

La pregunta del millón: ¿nueva o cambio?

Por si fuera poco, ninguna de las estrategias funciona si nadie detecta a tiempo que una petición afecta a algo que ya existe. Esa detección puede ocurrir en tres momentos: cuando el humano lo declara al pedirlo, cuando el agente lo descubre contrastando la petición con lo que ya hay, o cuando te enteras tarde porque ha saltado un test en rojo. Cuanto antes respondas, más barato te sale.

Es decir, lo ideal es saber si algo ya existe antes de escribir una sola línea. Pero para ello, necesitas almacenar conocimiento. Eso puedes hacerlo en tu cabeza, en un software especializado o en tu viejo sistema de ficheros. Yo, que tengo más años que un bosque, he elegido la tercera.

Por eso mantengo un índice del producto, un PRD agrupado por categorías que enlaza a las specs. Me parece la menor burocracia para permitirle al agente preguntarse si eso ya existía antes.

Y respecto a la estrategia de qué hacer con la evolución de las especificaciones… he tirado por la calle del medio. La especificación anclada al código me ofrece el mejor compromiso entre mantenimiento y flexibilidad.

Llevo meses dando forma a estas ideas en AIDDbot, un arnés de skills para agentes, donde incorporo todas estas ideas. Es open source, así que puedes ver cómo lo resuelvo y, mejor aún, contarme dónde me equivoco.

El mínimo rigor que elimine la ambigüedad

Ya ves, después de darle muchas vueltas he llegado a una conclusión poco espectacular: no hay estrategia ganadora. Usar y tirar encaja en prototipos y demos, la spec anclada en sistemas de producción con vida larga, y los deltas solo si tu problema real es auditar decisiones, que no suele serlo. La regla que me funciona es aplicar el mínimo nivel de burocracia que elimine la ambigüedad en tu contexto, y optimizar la relación señal/ruido.

Si quieres el recorrido completo, de la spec a la release con los agentes haciendo el trabajo pesado, te lo enseño paso a paso en el curso Spec-Driven Development Inteligente.