Esta es la queja que más oigo sobre el desarrollo guiado por especificaciones, y no le falta razón: «Lo intenté y pasé más tiempo alimentando el proceso que construyendo la cosa». Propuesta, spec, plan, tareas, puertas de revisión. Para alguien que trabaja solo o un equipo pequeño que va rápido, la ceremonia puede costar más que el código que se supone que protege.
La respuesta habitual es que solo te hace falta más disciplina. Creo que está del revés. Si un proceso solo funciona con disciplina heroica, el proceso pesa demasiado. El arreglo no es esforzarse más. Es escribir una spec más pequeña.
La sobrecarga es real, y fingir lo contrario pierde gente
Los pipelines completos de spec-driven se moldearon en parte con herramientas pensadas para equipos y cambios grandes. Spec Kit formaliza un flujo por propuesta, especificación, plan y tareas. Esa estructura se gana su coste cuando mucha gente toca un cambio, cuando el radio de impacto es grande o cuando la decisión necesita un rastro documental.
Deja de ganárselo en una feature de doscientas líneas que estás construyendo tú solo esta tarde. Ahí, la misma estructura es fricción. Escribes una propuesta para convencerte a ti mismo, un plan que ya tienes en la cabeza y una lista de tareas que no volverás a leer. Cuando terminas la ceremonia, has gastado tu energía en el artefacto en vez de en el trabajo, y el artefacto empieza a derivar del código en cuanto lo cierras.
Decirle a esa persona que sea más rigurosa no ayuda. Ya conoce el proceso completo. Lo abandonó porque no compensaba. El movimiento que funciona es admitir que la sobrecarga existe y diseñarla a la baja.
Para qué sirve una spec en realidad
Quita las plantillas y una spec hace un solo trabajo: es el contrato que dice qué tiene que cambiar, qué no, y cómo sabrás que funcionó. Todo lo que hay en una spec que no sirve a ese trabajo es sobrecarga que puedes recortar.
Ese replanteo es todo el truco. No intentas documentar la feature. Intentas escribir el contrato más pequeño que un agente, un compañero o tu yo futuro necesitan para construir lo correcto y demostrarlo. La mayor parte de una spec pesada no es contrato. Es reformulación, cautelas y artefactos de proceso que existen para satisfacer la plantilla, no el trabajo.
La receta ligera
Esta es la versión que uso de verdad para un cambio normal. Una página, tres secciones, escritas antes de que arranque el agente.
Intención (2-4 frases)
Qué comportamiento cambia y para quién. Nada de ritual de historia de usuario, solo la frase que dirías en voz alta. «Los usuarios invitados pueden comprar sin cuenta; el flujo tiene tres pasos; nada de la compra con sesión iniciada cambia.» Si no puedes decirlo en unas frases, todavía no entiendes el cambio lo bastante como para dárselo a un agente.
Límites (una lista corta)
Qué tiene que seguir siendo cierto y qué queda explícitamente fuera. Es la parte de mayor valor de una spec ligera y la que la gente se salta. Cuando un agente puede generar código plausible rápido, las restricciones valen más que las instrucciones. «No toques la integración con la pasarela de pago. No guardes datos de tarjeta. No cambies el camino con sesión iniciada.» Tres líneas aquí te ahorran un día de desenredo más tarde.
Criterios de aceptación (comprobables, no prosa)
Cómo sabrás que está hecho, escrito para que una máquina pudiera comprobarlo, no para que un humano asienta. «Dado un invitado con artículos en el carrito, cuando completa los tres pasos, entonces se crea un pedido y no se persiste ningún token de tarjeta.» Son criterios de aceptación que un agente puede verificar de verdad, que es lo que evita que una spec ligera se vuelva teatro ligero.
Esa es la spec. Intención, límites, aceptación. Sin propuesta, sin plan aparte, sin desglose de tareas salvo que el cambio sea lo bastante grande como para necesitarlo. Para la mayoría de los cambios, cabe en una pantalla y lleva diez minutos.
Qué recortas y qué no debes recortar
Los recortes: el documento de propuesta, el ensayo de diseño, la lista de tareas para cualquier cosa que puedas tener en la cabeza, la puerta de revisión en un cambio que solo tocarás tú, y toda sección que reformula otra sección con otras palabras.
Los innegociables: intención, límites y criterios de aceptación. Recorta uno de esos tres y no tienes una spec ligera, tienes una nota. Los límites son el que más tentación da de soltar y el que más paga, porque son lo que impide que un agente rompa una feature que funcionaba mientras añade una nueva.
El otro innegociable es mantenerla al día. Una spec de una página que actualizas cuando el cambio aterriza es una spec viva. Una spec de una página que escribes y abandonas es solo drift más rápido. Ligero solo funciona si barato de escribir también significa barato de actualizar.
Cuándo devolver el peso
Ligero es un valor por defecto, no una religión. Añade estructura cuando el cambio se la gane:
- Más gente lo toca. Un cambio compartido necesita el artefacto compartido. Una propuesta y una puerta de revisión dejan de ser ceremonia y pasan a ser coordinación.
- El radio de impacto es grande. Migraciones, auth, pagos, cualquier cosa donde un error es caro, merecen la sección de diseño y el plan explícito.
- La decisión necesita registro. Cuando dentro de seis meses te pregunten «por qué lo hicimos así», el registro de decisiones merece escribirse en el momento.
El error no es usar spec-driven pesado. El error es usar un solo peso para todos los cambios. Ajusta la ceremonia al riesgo, y la mayoría de los cambios se llevan la versión de una página.
Cuándo no escribir ninguna spec
Todo lo anterior baja el peso hasta una página. Por debajo de una página hay un suelo, y no nombrarlo es parte de por qué el spec-driven se ha ganado su fama de ceremonia. Hay dos casos que merecen cero.
El primero es el código sin futuro. Un script que responde a una única pregunta, una prueba rápida para ver si una API se comporta como dice su documentación, un prototipo construido para tirarlo después de la demo. Escribir un contrato para código que vas a borrar cuesta minutos reales y no protege nada. Esa zona es del vibe coding, y ahí el vibe coding es el modo correcto.
El segundo caso es el que nadie te avisa, y no tiene que ver con el tamaño. A veces todavía no sabes qué aspecto tiene lo correcto. La exploración es justo la forma de averiguar cuál es el requisito. En ese momento no tienes un contrato que escribir, tienes una pregunta, y una spec escrita encima de una pregunta no registra una decisión. Congela una suposición. Y cuanto mejor la escribas, más cuesta abandonarla, porque ya hay un artefacto defendiéndola. Una spec escrita antes de entender el requisito convierte la exploración en coste hundido.
Es el modo de fallo que más me pasa en mi propio trabajo, y cuando ocurre no parece dejadez. Parece diligencia. Escribo la intención, los límites y los criterios de aceptación de algo que aún no he entendido, el agente construye exactamente eso, y el resultado es una implementación correcta de la idea equivocada. La spec hizo su trabajo. El problema es que yo no tenía por qué estar escribiéndola todavía.
La prueba: ¿este camino ya sostiene peso?
La regla para decidir cuándo añadir tests y arquitectura se traslada limpia a la spec, y es la única versión observable de «cuando empieza a importar» que conozco. Un cambio se gana un contrato escrito cuando romperlo haría daño a un usuario real y cuando cuentas con seguir tocándolo.
Las dos mitades trabajan. Si haría daño pero no vas a volver a tocarlo, lo que necesitas es un test, no un contrato. Si vas a cambiarlo cada día pero todavía nada depende de ello, sigues explorando, y el artefacto que sirve es una nota con lo que has aprendido. Cuando se cumplen las dos, esos diez minutos son la depuración más barata de la semana. Cuando no se cumple ninguna, esos mismos diez minutos son la ceremonia de la que se queja la gente, y hacen bien en quejarse.
La secuencia que funciona es explorar primero, escribir la spec después y lanzar al agente al final. Prototipa hasta que puedas enunciar la intención y los límites sin cautelas. Esa frase es la señal: si no puedes escribir el contrato en unas líneas, no has terminado de explorar, y la respuesta es explorar más, no alargar el documento.
Dónde encaja PaellaDoc
Una spec ligera sigue necesitando un sitio donde vivir que la conecte al código y a la evidencia, o deriva tan rápido como cualquier otra. PaellaDoc guarda el contrato pequeño en un modelo local conectado al repositorio y a los resultados de las ejecuciones, de modo que una spec de una página se mantiene barata de escribir y barata de actualizar. Consigues la disciplina del spec-driven al peso de una nota, y añades estructura solo donde el riesgo la pide.
Preguntas frecuentes
¿Una spec de una página no es solo una spec incompleta? No. Incompleta significa que al contrato le faltan piezas, normalmente los límites y los criterios de aceptación. Ligera significa que el contrato está completo y no hay nada más. Una página bien apretada puede estar más completa que un documento de diez páginas que entierra el contrato en reformulación.
¿El spec-driven ligero funciona con agentes? Funciona mejor, porque las partes que conservas son justo las que un agente necesita: intención para construir lo correcto, límites para no romper lo incorrecto y criterios de aceptación que puede verificar. Las partes que recortas eran sobre todo para el proceso humano.
¿Cuándo no debería ir ligero? Cuando el cambio se comparte entre personas, es de alto riesgo o necesita un registro de decisión. Ajusta el peso al radio de impacto. Ligero es el valor por defecto correcto para la mayoría de los cambios, no una regla para todos.