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.
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.