Instalaste Spec Kit, corriste el flujo y obtuviste una spec limpia. El agente la leyó, construyó la feature y los tests se pusieron en verde. El día uno esto parece la respuesta a todo lo que está mal en el vibe coding.
Luego llega el día treinta. Cambias la lógica de precios, el agente toca tres archivos y la spec del disco sigue describiendo el comportamiento antiguo. Nadie la actualizó porque actualizarla no era tarea de nadie. El documento que iba a ser la fuente de verdad es ahora el mentiroso más convincente del repositorio.
Esto no es una crítica a Spec Kit. El Spec Kit de GitHub hace algo de verdad útil: te obliga a escribir intención, restricciones y un plan antes de que un agente empiece a teclear. Ese primer acto de escribir atrapa una clase enorme de malentendidos. La pregunta de este artículo es la que viene después. ¿Qué necesita el desarrollo guiado por especificaciones después de escribir la spec?
La spec es un evento, el contrato es un proceso
Casi todas las herramientas de este espacio tratan la spec como un evento. Corres un comando, produces un documento, se lo pasas a un agente y sigues adelante. El artefacto es el entregable.
Ahí empieza el problema. Una spec que solo existe en el momento de crearse es una foto de la intención tomada antes de que nadie supiera qué aspecto tendría el código. En cuanto sale la primera línea, la realidad y el documento empiezan a separarse. Si no haces nada, no se vuelven a reconciliar nunca.
La unidad útil no es el documento. Es el contrato vivo entre lo que querías decir y lo que hace el sistema, mantenido a lo largo de cada cambio que sigue. Escribir la spec es la parte barata. Mantenerla cierta es el trabajo.
Qué se rompe después de la spec
Tres cosas fallan cuando la spec sale de la herramienta que la escribió.
Pierde el vínculo con el código. Un archivo markdown en una carpeta specs/ no apunta a nada. Dice «el flujo de checkout valida el cupón antes de aplicarlo», pero no sabe qué funciones, archivos o tests implementan esa frase. Cuando la lógica del cupón se mueve, la frase se queda quieta y se vuelve falsa en silencio. Esto es el spec drift, y es el resultado por defecto, no la excepción.
Pierde su evidencia. La spec decía qué aspecto tiene un resultado correcto. ¿Lo comprobó alguien? Un build en verde no es prueba de que se cumplieron los criterios de aceptación, como argumenta en detalle un build en verde no es una feature correcta. La spec describió el contrato; nada conectó ese contrato con una ejecución que de verdad lo pusiera a prueba. Así que te quedas confiando en una casilla marcada.
Pierde su portabilidad. El siguiente agente, el siguiente editor o tú dentro de tres semanas no podéis reconstruir por qué la spec dice lo que dice. Las decisiones que había detrás vivían en un chat que ya no existe. Este es el argumento para tratar las especificaciones como artefactos portables en lugar de archivos atrapados en un solo workflow.
Ninguno de estos es un fallo del paso de escribir. Son fallos de todo lo que el paso de escribir no cubre.
Después de la spec: tres tareas que nadie asignó
Si la spec va a seguir siendo útil, tres tareas tienen que ocurrir de forma continua, y ahora mismo una persona hace las tres a mano sin nombrarlas.
Mantenerla ligada
Cada afirmación de una spec debería estar unida al código que la implementa. No «mira el repositorio», sino las funciones, módulos y tests concretos que hacen cierta la frase. Cuando uno de ellos cambia, el sistema debería saber qué afirmaciones de la spec quedan en cuestión. Esa es la diferencia entre documentación que se pudre y documentación que levanta la mano.
Mantenerla verificada
Los criterios de aceptación de la spec solo valen algo si algo los ejecuta contra el resultado real y mantiene el desenlace unido al contrato. La verificación no es una fase que haces una vez al final. Es la respuesta continua a «¿sigue cumpliéndose el contrato?». Es la razón entera por la que verificar código generado por IA necesita evidencia y no éxito auto-declarado.
Mantenerla viva
Cuando el código cambia, la spec tiene que cambiar con él, o el drift se acumula hasta que el documento no vale nada. Una spec que se actualiza junto al código vale por diez specs que eran perfectas el día en que se escribieron y no se tocaron nunca más.
Ahora mismo, en casi todos los equipos, las tres tareas las hace una persona, a mano, sin que nadie las nombre como trabajo. Tú eres lo que recuerda que la spec existe. Tú eres quien nota, a veces, que un cambio la dejó obsoleta. Tú eres la memoria que conecta el código mergeado con la frase que se suponía que debía satisfacer. Funciona hasta que el volumen de output de los agentes supera tu atención, que ocurre rápido. La razón por la que la spec se pudre no es que la gente sea descuidada. Es que mantenerla cierta nunca se asignó a otra cosa que a una persona sosteniéndolo todo en la cabeza.
Respeta la puerta de entrada, extiende el workflow
Spec Kit es una buena puerta de entrada. Captura la intención en el momento en que la intención es más barata de capturar, antes de que el agente se haya comprometido con una implementación. No hay razón para sustituirlo, y el marco de «alternativas a Spec Kit» se pierde casi siempre lo que de verdad falta.
Lo que falta es la mitad de atrás del bucle. La spec necesita un lugar donde vivir en el que siga conectada al modelo de producto, al repositorio, a las tareas y a la evidencia, y desde el que pueda volver a salir sin quedar aplanada en prosa. La puerta de entrada escribe el contrato. El resto de la casa es donde el contrato tiene que sobrevivir al contacto con un código que cambia.
Dónde encaja PaellaDoc
Este es el problema alrededor del cual está construido PaellaDoc. Un cambio puede entrar como una spec, desde Spec Kit o cualquier flujo parecido, y en lugar de convertirse en un archivo estático se convierte en un nodo mantenido dentro de un modelo local del producto. Las afirmaciones de la spec se enganchan al código que las implementa. Los criterios de aceptación se conectan con las ejecuciones que los ponen a prueba. Cuando el código deriva, las partes afectadas del contrato salen a la superficie en vez de quedarse obsoletas en silencio.
La spec no es el entregable. Es el principio de un contrato que tiene que seguir siendo cierto mientras muchos agentes escriben, fallan, se recuperan y publican. Escribirla nunca fue la parte difícil. Mantenerla veraz lo es.
Preguntas frecuentes
¿Es PaellaDoc una alternativa a Spec Kit? No. Spec Kit escribe la spec al principio del workflow, y lo hace bien. El hueco es lo que pasa después: mantener la spec ligada al código, verificada contra evidencia y actualizada según el código cambia. Esa mitad de atrás es la parte que vale la pena construir.
¿Por qué una spec deja de ser útil con el tiempo? Porque nada la mantiene conectada al código. Según cambia la implementación, el documento se queda congelado y va describiendo un sistema que ya no existe. Sin un mecanismo que detecte ese drift, la spec pasa a engañar de forma activa.
¿Puedo seguir usando Spec Kit y aun así resolver esto? Sí. La idea no es soltar tu herramienta de entrada. Es darle a la spec un sitio donde vivir en el que siga ligada al código y a la evidencia después de que el agente haya construido la feature.