«La spec es el contrato» es una de esas frases con las que todo el mundo asiente. Suena bien, suena rigurosa, y la mayor parte del tiempo no significa nada, porque un contrato que nadie firma, que nadie puede incumplir y que nadie hace cumplir no es un contrato. Es un deseo con mejor formato.
Si quieres que la frase pese, tienes que responder tres preguntas que un contrato real siempre responde. ¿Quién lo firma? ¿Quién puede romperlo? ¿Y cómo se entera alguien de que se rompió? Sáltatelas y «la spec es el contrato» es solo una forma más bonita de decir «escribimos algo una vez».
Un contrato tiene partes
Un contrato vincula a unas partes entre sí. Así que la primera pregunta es: ¿entre quiénes?
En el desarrollo guiado por especificaciones la spec se sitúa entre la intención de producto y la implementación. A un lado está quien responde de lo que el software debe hacer. Al otro, quien, o lo que, lo construye, y cada vez más eso es un agente. La spec es la declaración acordada de qué significa «correcto», escrita antes de empezar a construir para que ambos lados apunten al mismo objetivo.
Por eso la spec tiene que ir antes que el código. Un contrato que escribes después de terminar el trabajo no es un contrato, es una descripción. Todo el valor de definir el contrato de aceptación antes de implementar es que existe como un compromiso al que ambas partes pueden señalar, no como un resumen de lo que ya pasó.
La firma también importa. Alguien tiene que aceptar de verdad la spec, dejando constancia, antes de que el agente construya contra ella. Esa firma es lo que zanja tres semanas después la discusión del «yo nunca acordé eso». Sin un momento registrado de acuerdo, la spec es un borrador, y los borradores no vinculan a nadie.
Un contrato se puede incumplir
Aquí es donde se desmorona casi toda la charla de «spec como contrato». Si nada puede romper el contrato, nunca fue un contrato. Entonces, ¿qué cuenta como incumplimiento?
Dos cosas incumplen una spec, y son distintas.
La implementación viola la spec. El agente construyó algo que no hace lo que dice el contrato. Cubre el camino feliz e ignora un invariante que la spec protegía de forma explícita. Este es el incumplimiento que todo el mundo imagina, y es el más fácil de atrapar.
El mundo cambia y la spec deja de describirlo. Nadie violó el contrato a propósito. Un cambio posterior tocó la misma superficie, el comportamiento se movió y ahora el código y la spec no coinciden. Ninguna parte faltó a su palabra, pero el contrato queda incumplido igual, porque ya no encaja con la realidad. Este es el spec drift visto con lente contractual, y es el incumplimiento del que nadie asigna la culpa, que es justo por lo que se pudre.
Una spec que solo puede romperse por lo primero y nunca se entera de lo segundo te protege del fallo fácil y deja el común abierto de par en par.
Un contrato se hace cumplir, o es decoración
Un incumplimiento que nadie detecta no es hacer cumplir. Esta es la parte que separa una spec que gobierna de una spec que decora.
La detección tiene que ser mecánica, porque la atención humana no escala a la velocidad a la que los agentes producen código. Los criterios de aceptación de la spec tienen que ser ejecutables contra el resultado real, y algo tiene que correrlos de verdad y unir el desenlace al contrato. Una suite de tests en verde no basta por sí sola, porque un build en verde no es una feature correcta: el build puede estar verde mientras el comportamiento concreto que el contrato prometía no se ejecutó nunca.
Por eso los criterios de aceptación hay que escribirlos para comprobarse, no solo para leerse. Un criterio vago como «gestiona los errores con elegancia» no se puede hacer cumplir, así que no es una cláusula del contrato, es una esperanza. Los criterios que un agente y un ejecutor pueden evaluar son la diferencia entre criterios de aceptación que se verifican y una checklist que alguien marca a ojo.
Y hacer cumplir tiene que ser continuo, porque el segundo tipo de incumplimiento ocurre después de secar la tinta. Comprobar el contrato una vez en el merge atrapa la violación de la implementación y se pierde cada drift que viene detrás. Hacer cumplir no es una puerta que cruzas una vez. Es una pregunta permanente que el sistema sigue repitiendo: ¿el código sigue satisfaciendo el contrato?
Fíjate en cuánto de esto lo hace hoy la persona a mano. Tú eres la parte que firmó. Tú eres el mecanismo de cumplimiento, leyendo el diff y decidiendo si honra lo acordado. Tú eres el detector de drift, quien acaba notando que la spec ya no coincide. Un contrato que se hace cumplir enteramente con la atención de una persona es un contrato que aguanta exactamente lo que esa persona tenga atención de sobra, que a velocidad de agente no es mucho. Las cláusulas no se debilitan. El que hace cumplir simplemente se desborda, y un contrato sin cumplir vuelve a ser decoración.
El contrato tiene que viajar con la mercancía
Un contrato no vale nada si las partes pierden su copia. Cuando la spec vive en un chat que se borra o en una carpeta que el siguiente agente no abre nunca, el contrato se anula solo en cuanto cambia el workflow.
Para que la spec siga siendo un contrato, tiene que moverse con el código y la evidencia, no quedarse clavada a la herramienta que la escribió. Esta es la razón práctica por la que las especificaciones deberían ser portables: un contrato solo vincula mientras ambas partes puedan seguir leyéndolo, y en un flujo de agentes las partes cambian sin parar.
Dónde encaja PaellaDoc
Hacer de la spec un contrato real es el trabajo alrededor del cual está organizado PaellaDoc. Una spec se acuerda y se registra, así que hay una firma de verdad en lugar de una suposición. Sus criterios de aceptación siguen conectados con las ejecuciones que los ponen a prueba, así que un incumplimiento del primer tipo se atrapa con evidencia en vez de con confianza. Y como la spec sigue ligada al código que la implementa, un incumplimiento del segundo tipo, el drift, sale a la superficie cuando el código se mueve en lugar de esconderse hasta que lo encuentra una incidencia.
La spec es el contrato solo cuando alguien lo firmó, algo puede romperlo y algo atrapa la ruptura. Responde esas tres y la frase significa lo que dice. Sáltatelas y tienes un documento que parece un contrato justo hasta el momento en que necesitas que aguante.
Preguntas frecuentes
¿Quién firma una spec-como-contrato? Quien responde de lo que el software debe hacer, dejando constancia, antes de que el agente construya. Ese acuerdo registrado es lo que convierte un borrador en un compromiso y zanja las disputas posteriores sobre qué se acordó de verdad.
¿No es ya una suite de tests en verde una forma de hacer cumplir? No por sí sola. Un build en verde demuestra que algo de código corrió y pasó, no que se ejecutara el comportamiento concreto que el contrato prometía. Hacer cumplir significa que los criterios de aceptación se corren contra el resultado real y el desenlace se une a la spec.
¿Cómo es el spec drift un incumplimiento si nadie rompió una regla? Porque un contrato queda incumplido cuando deja de encajar con la realidad, no solo cuando alguien lo viola a propósito. Un cambio posterior puede mover el comportamiento y dejar la spec describiendo un sistema que ya no existe. Nadie tiene la culpa, y el contrato está roto igual.