Análisis de por qué fallan las especificaciones técnicas de software, con el argumento de que la causa raíz es una brecha de traducción entre las partes interesadas y los equipos de ingeniería, no una falta de esfuerzo documental. Identifica tres modos de fallo: contexto implícito, redacción para una sola audiencia y ambigüedad que sobrevive a la revisión. Propone la generación de especificaciones específicas por audiencia como medida correctiva.
Por Qué Fallan las Especificaciones Técnicas Antes de Escribir una Línea de Código
Una especificación no falla por ser demasiado corta. Falla porque quien la escribió ya conocía la respuesta, y el documento nunca tuvo que sostener ese conocimiento por sí solo.
La Brecha Es de Traducción, No de Esfuerzo
Los equipos responden a las especificaciones fallidas escribiendo especificaciones más largas. Se agregan plantillas. Se agregan controles de revisión. Los documentos se vuelven más pesados y los resultados no mejoran, porque el volumen nunca fue la restricción.
La restricción es que un requisito se escribe en un dialecto y se lee en varios. Una gerente de producto escribe «los usuarios deberían poder deshacer». Un ingeniero lee eso y tiene que decidir si deshacer significa una reversión optimista en el cliente, un borrado lógico con ventana de restauración o un historial completo basado en eventos. Las tres son defendibles. Solo una era la intención, y el documento no dice cuál.
Tres Modos de Fallo
Contexto implícito. Quien escribe mantiene la restricción en su cabeza y nunca la enuncia. «Debe ser rápido» significa 200 ms para quien lo escribió y 2 s para quien lo lee. Ninguno se equivoca. Sencillamente, el documento no lo resuelve.
Redacción para una sola audiencia. Se espera que un mismo documento sirva a una desarrolladora junior, a un tech lead y a un SRE. La junior necesita pasos explícitos. El lead necesita compensaciones. El SRE necesita modos de fallo y reversión. Un documento afinado para cualquiera de ellos deja mal servidos a los otros dos, y un documento afinado para los tres normalmente no lo lee nadie.
Ambigüedad que sobrevive a la revisión. Quienes revisan aprueban lo que entienden. Como cada persona resuelve la ambigüedad con sus propias suposiciones, todos aprueban una especificación distinta. El desacuerdo aparece en la revisión de código, semanas después, presentado como un bug.
Lo Que Sí Ayuda
Escribe para una audiencia concreta, no para el archivo. Una especificación dirigida a un SRE debería abrir con los modos de fallo y la observabilidad. El mismo requisito dirigido a una desarrolladora junior debería abrir con pasos secuenciados y sin ambigüedad. Son documentos distintos que describen la misma funcionalidad, y producir ambos sale más barato que una sola ronda de retrabajo.
Enuncia la restricción que estás sosteniendo de forma implícita. Si tienes un número en la cabeza, ponlo en el documento. «Menos de 200 ms en el p95» no se puede malinterpretar. «Rápido» siempre se malinterpretará.
Haz que los casos límite sean responsabilidad de quien revisa —para rechazarlos— y no de quien escribe —para recordarlos—. Una especificación que enumera qué pasa cuando la cuenta ya existe, cuando el token expira a mitad de la operación y cuando el proveedor externo está caído le da a quien revisa algo concreto con lo que discrepar. Su ausencia produce acuerdos silenciosos.
La Parte Incómoda
Nada de esto es un consejo nuevo. Lleva veinte años en todos los manuales de ingeniería y sigue sin ser práctica habitual, porque hacerlo bien implica escribir el mismo requisito varias veces para varios lectores. Ese costo recae sobre la persona con menos tiempo disponible: normalmente quien está más cerca de la parte interesada.
Ese es el problema concreto que vale la pena automatizar. No el pensamiento, que sigue siendo humano, sino la traducción: tomar un enunciado claro de intención y expresarlo para cada audiencia que tiene que actuar sobre él. El criterio sobre qué debe hacer la funcionalidad no se delega. El trabajo mecánico de reformularlo cuatro veces, sí.