¿Qué es el desarrollo basado en especificaciones?

Con la accesibilidad de las herramientas de IA y los asistentes de programación, como GitHub Copilot de Microsoft, Claude Code de Anthropic o Bob de IBM, la barrera de entrada para la generación de código se ha reducido. Un agente de IA impulsado por LLM que usa modelos de IA, puede ejecutar una serie de tareas iterativas en tiempo real en cualquier momento, todo con una única instrucción del usuario.

Para el desarrollo de software, esto significa que podemos optimizar y automatizar el flujo de trabajo de desarrollo para construir prototipos, nuevas características, pruebas unitarias y otros. Nunca ha sido tan fácil generar código. No obstante, hay una pendiente resbaladiza que los vibe coders deben tener en cuenta: la IA es tan buena como las instrucciones que recibe. 

Es probable que haya visto deuda técnica en el mundo real, tal vez sin siquiera darse cuenta. La deuda técnica es anterior al vibe coding y ha sido parte del desarrollo de software durante décadas, acumulándose cuando se toman atajos en nombre de la velocidad. No obstante, el vibe coding acelera la deuda técnica al facilitar la generación de grandes cantidades de código sin comprenderlo o validarlo completamente. Tal vez haya presión para enviar rápidamente, o el vibe coder simplemente no tiene los antecedentes técnicos para detener la deuda técnica antes de que comience.  

La deuda técnica en el desarrollo asistido por IA puede adoptar varias formas: 

• La desviación de contexto ocurre cuando un arreglo en un área afecta inadvertidamente el funcionamiento de otra; esto es un síntoma de que el código se generó sin una comprensión completa del sistema en su conjunto.  
• La fragmentación es otra manifestación común, en la que las características recién generadas no se ajustan a las convenciones arquitectónicas existentes, lo que va mermando gradualmente la coherencia y la facilidad de mantenimiento de la base del código.  
• También hay un costo operativo que considerar. Sin una especificación clara para anclar el proceso de generación, los desarrolladores pueden verse atrapados en largos ciclos de instrucciones. Este enfoque puede consumir miles de tokens para resolver errores que una especificación bien definida habría evitado por completo. 

Imagine un escenario que muchos desarrolladores de la industria conocen bien. Ha estado trabajando en una nueva característica durante varios días o semanas, casi lista para su envío. Luego, bajo la presión de una fecha límite que se acerca, apresura los ajustes finales a través de una serie de cambios impulsados por IA.

Las funciones del código generado, ya sea escrito en Python u otro lenguaje, pueden parecer correctas desde la perspectiva del usuario. Sin embargo, en el proceso, se expusieron varias vulnerabilidades, se introdujeron conflictos de dependencia y se olvidaron por completo el manejo y las pruebas de casos periféricos.

Una especificación formal establecida por adelantado brinda al equipo una fuente de información compartida para gobernar cada fase del ciclo de vida del desarrollo de software (SDLC), independientemente de quién esté escribiendo el código. 

Existen varios enfoques y plantillas para el desarrollo basado en especificaciones, con distintos niveles de mantenimiento y distintas compensaciones. En lugar de una progresión estricta “mejor”, la elección correcta depende de su base de código, equipo y espacio de problemas. Antes de seleccionar uno, tenga en cuenta las necesidades y limitaciones de su equipo.

En el desarrollo con prioridad en las especificaciones, la especificación se redacta antes de generar cualquier código, ya sea en forma de historia de usuario, criterios de aceptación o un documento formal de requisitos. Una vez que se establece la claridad inicial y se genera el código, no siempre se mantiene la especificación. La especificación puede quedar obsoleta a medida que el software evoluciona. Su propósito principal era brindar claridad inicial sin necesidad de continuar el mantenimiento de las especificaciones. Este aspecto se considera el “punto de entrada al SDD”. ¹

En el desarrollo basado en especificaciones, la especificación evoluciona junto con el software. A medida que cambian los requisitos y se agregan características, la especificación se actualiza para reflejar el estado actual del sistema. Esto resulta especialmente útil para proyectos que forman parte de iniciativas más amplias.

Las pruebas automatizadas sirven de puente entre la documentación y la implementación, y a menudo se integran en un proceso de CI/CD para garantizar que ambas permanezcan sincronizadas y sean ejecutables a lo largo de todo el ciclo de vida del desarrollo. Este equilibrio entre estructura y flexibilidad hace que el desarrollo basado en especificaciones sea un enfoque práctico y escalable para la mayoría de los equipos de ingeniería.¹

En el extremo opuesto del espectro se encuentra el desarrollo basado en especificaciones como fuente: la forma que más prioriza la IA. En el desarrollo basado en especificaciones como fuente, los cambios en las especificaciones desencadenan automáticamente cambios en el código. Ningún ser humano refactoriza directamente el código.

Este nivel de autoridad en la definición de especificaciones exige un alto grado de confianza en la calidad y la congruencia del proceso de generación de código mediante IA, el cual, a la fecha, sigue siendo intrínsecamente no determinista. En la práctica, eso significa que puede ser menos riguroso si no cuenta con una supervisión humana estricta. Antes de adoptar este enfoque, los equipos deben evaluar cuidadosamente la madurez de su pila tecnológica y su kit de especificaciones, el nivel de criticidad de los sistemas involucrados y su capacidad para validar los resultados generados por la IA.¹

En la práctica, muchos equipos adoptan enfoques híbridos:

• Tratar las especificaciones como artefactos versionados apilables, como registros de decisiones de arquitectura (ADR), en lugar de mantenerlas siempre completamente actualizadas.
• Usar sistemas externos (por ejemplo, rastreadores de problemas) como fuente de información para introducir una separación intencional.
• Evitar la automatización excesiva en proyectos de alta complejidad o impulsados por la comunidad, donde un control estricto sobre los cambios es crítico.

Cada enfoque tiene fortalezas y limitaciones; el contexto importa más que el estricto cumplimiento de cualquier modelo.

Dependiendo del nivel de autoridad de especificación que prefiera, una especificación efectiva puede verse diferente. Sin embargo, suponiendo que se encuentre en algún punto intermedio del espectro y seleccione el desarrollo basado en especificaciones, una especificación debe describir lo que el sistema debe hacer en términos claros y comprobables. Esta especificación evita que usted se bloquee prematuramente en cómo se implementará.

Las especificaciones deben ser lo suficientemente detalladas como para incluir definiciones de entradas y salidas, el esquema de datos, los casos periféricos y los criterios de éxito. No obstante, deben ser lo suficientemente ligeras como para evolucionar a medida que el problema se va entendiendo mejor. Por encima de todo, una buena especificación debería acelerar el desarrollo: si no está ayudando a escribir mejor código más rápido o reduciendo malentendidos, probablemente sea más detallada de lo necesario. 

Para ilustrar cómo se ve una especificación efectiva en la práctica, considere este ejemplo para una característica de autenticación de usuario: 

Está implementando una característica de inicio de sesión de usuario para una aplicación web.  
Use la siguiente especificación como su única fuente de información.  
No haga suposiciones sobre ningún requisito que no se mencione aquí. 
 
CARACTERÍSTICA: Inicio de sesión de usuario 
 
DESCRIPCIÓN GENERAL: 
Permita que los usuarios registrados se autentiquen de forma segura utilizando su dirección de correo electrónico y contraseña. 
 
CRITERIOS DE ACEPTACIÓN: 
1. El formulario de inicio de sesión debe aceptar una dirección de correo electrónico y una contraseña. 
2. Si las credenciales son válidas, se redirige al usuario al panel de control. 
3. Si las credenciales no son válidas, se muestra un mensaje de error genérico  
   sin especificar qué campo es incorrecto. 
4. Se bloquea la cuenta durante 15 minutos después de 5 intentos fallidos de  
   inicio de sesión consecutivos. 
5. Transmita contraseñas solo a través de HTTPS; nunca las almacene en texto sin formato 
 
FUERA DE ALCANCE: 
- Inicio de sesión social (OAuth) 
- Autenticación de dos factores 
- Flujo de restablecimiento de contraseña 
 
CASOS PERIFÉRICOS: 
- Capturar campos vacíos del lado del cliente antes del envío 
- Redirigir sesiones caducadas a la página de inicio de sesión con un mensaje informativo 
- El formulario debe seguir funcionando si JavaScript está deshabilitado 
 
No comience la implementación hasta que haya confirmado que comprende  
los criterios de aceptación.

Estas son similares a las especificaciones funcionales que escriben los gerentes de producto, pero se limitan estrechamente a lo que debe incluir la implementación, o sus criterios de aceptación, y cómo manejar adecuadamente los casos periféricos.

Más comúnmente, esta especificación viviría en el repositorio del proyecto en GitHub como un archivo Markdown comoSPEC.md o/docs/auth-login.md , versionado a través de Git junto con la base de código. El agente de programación de IA podría acceder a este si el usuario lo pega en la instrucción o, preferiblemente, hace referencia al archivo a través de una CLI y el agente lo lee desde el directorio del proyecto. Por ejemplo, “Implementar la característica descrita en /docs/auth-login.md ”.

En los flujos de trabajo más automatizados, el archivo de especificaciones se transmite como parte de la línea de comandos del sistema o de la ventana de contexto al inicio de la tarea, lo que le da al agente sus instrucciones antes de que comience.

Por mucho tiempo y deuda técnica que el desarrollo basado en especificaciones puede ahorrarle, también es importante recordar que es posible dedicar demasiado tiempo a la “ingeniería excesiva”. Si pasa tres semanas debatiendo el nombre de una sola clave JSON o endpoints de API específicos para una característica que podría eliminarse en un mes, esto frustra el propósito del desarrollo basado en especificaciones.  

No se centre demasiado en modelar todos los posibles futuros. Es preferible usar especificaciones ligeras y en constante evolución en lugar de especificaciones exhaustivas y “definitivas”. Escriba lo que necesita para avanzar, valide rápidamente en código y adapte a medida que cambia la realidad. Un principio general es que el costo de refinar la especificación siempre debe ser menor que el costo de arreglar malentendidos en la implementación. Cuando ese equilibrio se invierte, es una señal para dejar de pulir y empezar a construir.

Con la aparición de la programación de IA, el desarrollo impulsado por pruebas (TDD) y el desarrollo impulsado por el comportamiento (BDD) inspiraron una nueva ola: el desarrollo impulsado por especificaciones. Donde el TDD pide a los desarrolladores que definan los resultados esperados a través de pruebas, y el BDD les pide que definan el comportamiento a través de la colaboración, el desarrollo basado en especificaciones hace primero una pregunta más fundamental: ¿hemos definido claramente lo que estamos construyendo y para quién?^2,3

A medida que los agentes de IA asumen una mayor parte del trabajo de implementación, la calidad de ese trabajo se vuelve directamente proporcional a la calidad de las instrucciones que reciben. Una especificación bien redactada no restringe el proceso de desarrollo, sino que lo acelera dentro del sistema de software moderno.