Cuando ya estás revisando el diff, la discusión es cara. El agente construyó la feature. Hay cuatrocientas líneas repartidas en nueve archivos, los tests están en verde y ahora te das cuenta de que todo dio por hecho que los cupones se acumulan cuando la regla es que no lo hacen nunca. Arreglarlo significa deshacer trabajo que ya existe, volver a correr el agente y revisarlo todo otra vez.
Podrías haberlo atrapado en la spec, antes de escribir una sola línea, en el tiempo que se tarda en leer una página. Revisar la spec en lugar de solo el diff es la review de mayor palanca que hay en el desarrollo guiado por especificaciones, y casi nadie la hace, porque el hábito de la revisión de software está atado al código.
El coste de un error sube con cada paso
Un malentendido es más barato de arreglar en el momento en que todavía es solo una frase. En la spec, una suposición equivocada es una línea que tachas y reescribes. Después de que el agente construya, esa misma suposición equivocada está repartida por la implementación, por los tests que ahora la codifican y por cualquier código que ya dependa de ella. El error no empeoró. Se volvió más caro de quitar, porque creció una estructura a su alrededor.
Los agentes hacen esta curva más empinada, no más suave. Una persona que entendió a medias una spec iría más despacio, dudaría y preguntaría. Un agente no duda. Toma tu instrucción ambigua y genera con toda confianza una implementación completa, plausible y equivocada a máxima velocidad, y luego escribe tests que dejan el malentendido cerrado. Cuanto más rápido el constructor, más cuesta revisar solo al final, porque simplemente hay más error ya construido que deshacer.
Revisar la spec es como atrapas el error mientras todavía es una frase. Esto es lo que la hace barata. No estás discutiendo con código. Estás corrigiendo la intención antes de que la intención se haya convertido en nada.
Qué busca de verdad una revisión de spec
Una revisión de spec no es una corrección de estilo. No estás comprobando la gramática. Estás comprobando si el contrato es el contrato correcto, y hay unos cuantos modos de fallo concretos que vale la pena cazar.
Ambigüedad que un agente resolverá mal. Lee cada frase y pregúntate cómo podría interpretarla un constructor literal y con exceso de confianza. «Valida la entrada» ¿contra qué? «Gestiona los errores» ¿cómo? Allá donde la spec deje una decisión implícita, el agente la tomará por ti, y te encontrarás con su elección en el diff. La revisión de spec es donde cierras esos huecos mientras cerrarlos es gratis.
Límites que faltan. ¿Qué tiene que seguir siendo cierto que la spec se olvidó de decir? Los invariantes que un agente rompe con más probabilidad son los que nadie escribió, porque el agente no puede proteger una restricción de la que nunca le hablaron. Una revisión de spec es en gran parte una caza del «y no rompas esto» no dicho.
Criterios que no podrías comprobar de verdad. Cada criterio de aceptación debería ser uno que te imagines verificando contra un resultado real. «Funciona correctamente» no es comprobable. Este es el momento de convertir el lenguaje blando en criterios de aceptación que un agente puede verificar, porque un criterio que no puedes comprobar en la spec es un criterio que tampoco puedes hacer cumplir en el código.
La cosa equivocada, bien especificada. El fallo más caro. La spec es clara, completa y describe una feature que nadie necesitaba. Ninguna revisión de diff atrapa esto, porque el código coincidirá fielmente con la spec. Solo leer la spec como una declaración de intención, y preguntarse si la intención es correcta, lo atrapa.
Un hábito útil es leer la spec dos veces con dos preguntas distintas. La primera pasada pregunta «¿construirá un agente la cosa equivocada a partir de esto?» y caza ambigüedad y límites que faltan. La segunda pregunta «¿es esto lo correcto que construir, siquiera?» e ignora del todo la redacción para interrogar la intención. Son lecturas de verdad distintas, y casi todo el mundo solo hace la primera, que es por lo que la spec clara-pero-equivocada pasa de largo. Todo el sentido de mover la revisión tan temprano es que ambas preguntas todavía son baratas de responder. Cambia de opinión sobre la intención aquí y cuesta reescribir una página. Cámbiala después del diff y cuesta el diff.
Es la válvula de escape para la fatiga de review
Hay una segunda razón para mover la revisión antes, y tiene que ver con tu propia atención. Cuando los agentes producen código más rápido de lo que nadie puede leerlo, la revisión se convierte en el cuello de botella y quien revisa se quema. Esto es la fatiga de review, y echarle más lectura de diffs no ayuda, porque los diffs siguen llegando más rápido de lo que puedes absorberlos.
La revisión de spec ataca el volumen aguas arriba. Una página de spec se lee en minutos y determina cientos de líneas de código. Atrapar un problema ahí significa que el diff malo no se genera nunca, no se revisa nunca y no se vuelve a revisar nunca tras el arreglo. No estás leyendo con menos cuidado. Estás leyendo el artefacto donde la lectura cuidadosa rinde más y el volumen es más pequeño.
También cambia para qué sirve la revisión del diff. Cuando la spec se revisó y se acordó primero, revisar el código que no escribiste se convierte en una comprobación de «¿coincide esto con el contrato?» en lugar de una caza abierta por código desconocido buscando problemas que aún no has definido. Primero el alcance, el diff al final. La revisión de spec es el alcance.
Este reordenamiento es también lo que hace la revisión posterior soportable siquiera. Una revisión de diff sin una spec acordada detrás es una tarea infinita, porque no hay un estándar de «hecho» definido, así que sigues leyendo hasta que te quedas sin energía en vez de hasta que te quedas sin contrato. Una revisión de diff contra una spec revisada es una tarea finita con un punto de parada claro: el código satisface los criterios o no los satisface. Mover la revisión antes no solo atrapa errores más pronto. Le da a todo el proceso de revisión un suelo y un techo.
Dónde encaja PaellaDoc
Poner la revisión antes de la construcción es el workflow alrededor del cual está moldeado PaellaDoc. Un cambio empieza como una spec que puedes leer y corregir mientras todavía es barato corregirla, con su intención, sus límites y sus criterios de aceptación delante de ti antes de que el agente corra. Como esa spec revisada sigue conectada con el código y la evidencia, la revisión posterior del diff tiene algo contra lo que comprobar, y la spec que acordaste es el estándar por el que se mide el resultado en lugar de un documento que nadie reabrió.
La review más barata que harás nunca es la que ocurre antes de que exista nada que revisar. Una página de intención, leída con cuidado, decide la forma de todo lo que el agente construya después. Sáltatela y pagarás cada malentendido a precio de diff, una y otra vez, a velocidad de agente.
Preguntas frecuentes
¿No es revisar la spec trabajo extra sobre revisar el código? No, mueve el trabajo antes y lo hace más pequeño. Una página de spec decide cientos de líneas de código. Atrapar un error en la spec significa que el diff equivocado no se genera ni se revisa nunca, así que el esfuerzo total de revisión baja.
¿Qué busco en una revisión de spec? Ambigüedad que un agente resolverá mal, límites que la spec se olvidó de declarar, criterios de aceptación que no podrías verificar de verdad, y el caso en que la spec es clara pero describe la feature equivocada. Este último es el único sitio donde se atrapa.
¿La revisión de spec sustituye a la revisión de código? No. Cambia para qué sirve la revisión de código. Con la spec revisada y acordada primero, la revisión del diff se convierte en una comprobación contra un contrato conocido en lugar de una búsqueda abierta de problemas sin definir en código desconocido.