Especificaciones vivas: specs que se actualizan con el código

La mayoría de las specs nacen muertas. Escribes una al empezar una feature, es exacta durante más o menos un día, y a partir del segundo commit deja de describir poco a poco lo que estás construyendo. Cuando la feature se publica, la spec es un documento histórico sobre un plan que abandonaste.

Una especificación viva es la apuesta contraria. Es una spec diseñada para cambiar cuando cambia el código, de modo que en cualquier momento siga describiendo el producto que existe de verdad. Esa única propiedad es la que separa un contrato en el que puedes confiar de un archivo que aprendes a ignorar.

Las specs estáticas no están mal, están congeladas

La generación actual de herramientas spec-driven es buena consiguiendo que se escriba una spec. Spec Kit, por ejemplo, te da un flujo limpio de propuesta a spec, a plan, a tareas. Esos archivos hacen legible un cambio antes de que nadie construya, algo genuinamente valioso y justo donde el desarrollo guiado por especificaciones se gana su fama.

La limitación no está en el formato. Está en el ciclo de vida. Una spec producida así se escribe una vez, al principio del trabajo, y luego el trabajo sigue sin ella. Nada lleva la spec hacia delante a medida que cambia el código. Es un artefacto estático: correcto en t=0, degradándose desde t=1.

Esto no es una crítica a escribir specs por adelantado. Escribir el contrato antes de construir es justo la idea. El problema es tratar «escrita» como «terminada». Un contrato que nunca se actualiza se convierte en la fuente del spec drift: el código y la spec contando dos historias distintas, las dos con aire de autoridad, una de ellas mintiendo.

Qué significa «viva», en concreto

«Viva» es una palabra fácil de agitar, así que aquí va la prueba concreta. Una spec está viva si un cambio en el código puede actualizarla sin que una persona se acuerde de hacerlo como tarea aparte, y si un cambio en la spec tiene un camino definido hacia el código. La información fluye en las dos direcciones. El documento no está aguas arriba del trabajo; es parte del bucle.

Eso se descompone en tres propiedades.

Está anclada, no al lado

Una spec estática vive en una carpeta junto al código. Una spec viva está conectada al código: a los archivos, componentes y tests que la implementan. Cuando puedes trazar una afirmación de la spec al código que la satisface, puedes detectar el momento en que divergen. Una spec flotando en un directorio docs/ no tiene ese ancla, y por eso deriva sin que nadie lo note. Es la misma razón por la que una especificación portable tiene que llevar sus vínculos al código y a la evidencia, no solo su prosa.

Se actualiza como subproducto del trabajo

Las specs se pudren porque actualizarlas es una tarea aparte, y las tareas aparte pierden contra las fechas límite siempre. Una spec viva se actualiza como efecto secundario del trabajo que ya está pasando: cerrar una tarea, aterrizar un cambio, registrar una decisión. Si mantener el contrato al día exige una segunda pasada disciplinada para la que nadie tiene tiempo, no se mantendrá al día. Este es el principio operativo detrás de la documentación viva en general.

Sabe cuándo está rancia

Una spec viva no tiene por qué ser mágicamente siempre correcta. Tiene que poder decirte cuándo podría estar equivocada. Una spec conectada al código y a criterios de aceptación que se pueden reejecutar puede avisar del momento en que la realidad diverge del contrato, en vez de presentar en silencio un verde antiguo como verdad actual.

Por qué importa más con agentes

Cuando una sola persona escribía todo el código, la spec y el modelo mental derivaban juntos a la misma velocidad, y la persona podía reconciliarlos de memoria. Esa red de seguridad ya no está.

Un agente no guarda tu memoria del contrato entre ejecuciones. El contexto se pierde entre sesiones salvo que algo fuera del chat lo sostenga. Lanza varios agentes en paralelo y cada uno edita contra el contexto que le diste, no contra un contrato compartido y actual. Una spec estática no puede servir como ese contrato compartido, porque para la tercera ejecución ya no coincide con el código. Una spec viva sí, porque se movió junto a las dos primeras.

Dicho de otro modo: cuanto más rápido se escribe el código, más corta es la vida útil de una spec congelada. Los agentes no convirtieron las specs vivas en un lujo opcional. Hicieron que las estáticas caduquen antes.

Una spec viva no es más documentación

El instinto, al oír todo esto, es escribir más. Specs más grandes, más detalle, más secciones que mantener al día. Es la dirección equivocada, y es como el desarrollo guiado por especificaciones acaba con fama de aplastar con su sobrecarga.

Una spec viva suele ser más pequeña que una estática, no mayor. Guarda las partes que tienen que sobrevivir al contacto con el código —intención, límites, criterios de aceptación, las decisiones detrás del diseño— y delega el resto en el código y los tests, que ya son la descripción más actual del comportamiento que tienes. La meta no es un documento que lo describa todo. Es un contrato lo bastante pequeño para mantenerlo vivo y lo bastante conectado para seguir diciendo la verdad.

Si te encuentras manteniendo una spec que duplica lo que el código ya dice, no estás manteniendo una spec viva. Estás manteniendo una segunda copia de la verdad que derivará de la primera.

Dónde encaja PaellaDoc

Una spec viva necesita un sitio donde vivir que esté conectado al producto y al código, no una carpeta que se queda rancia. Esa conexión es lo que PaellaDoc está construido para sostener: un modelo local donde la spec está anclada al repositorio, a las tareas y a la evidencia de cada ejecución, de modo que un cambio en el código tiene dónde actualizar el contrato y un cambio en el contrato tiene un camino hacia el trabajo. La spec deja de ser un documento que archivas y pasa a ser parte del sistema que se mantiene al día porque el trabajo la mantiene al día.

Preguntas frecuentes

¿En qué se diferencia una spec viva de una buena documentación? La documentación describe cómo funciona algo para quien lo lee. Una spec viva es un contrato que define qué tiene que ser cierto y sigue conectado al código que lo demuestra. La buena documentación viva y las specs vivas comparten el mismo enemigo, la ranciedad, pero una spec lleva criterios de aceptación y límites, no solo explicación.

¿Las specs vivas sustituyen a los tests? No. Los tests verifican comportamiento; una spec viva lleva la intención, los límites y las decisiones que los tests no pueden expresar. Las dos se refuerzan. Los criterios de aceptación de la spec son contra lo que comprueban los tests, y así la spec sabe cuándo se ha quedado rancia.

¿Puedo convertir mis specs estáticas actuales en vivas? En parte. Puedes conectarlas al código, recortarlas a lo que tiene que seguir al día y enrutar las actualizaciones a través del trabajo en vez de una tarea aparte. Lo que no puedes hacer es volver viva una spec escribiendo más de ella. Vivir es cuestión del ciclo de vida, no de la longitud.