¿Qué es una especificación viva?

Explicación

Una especificación viva describe qué debe hacer un sistema y cómo encajan sus partes, y se guarda en el mismo repositorio que el código, actualizándose cada vez que el sistema cambia. Suele combinar documentos legibles con artefactos que entiende una máquina: contratos de API como ficheros OpenAPI, registros de decisiones de arquitectura (ADR), políticas y definiciones de evaluación. Como se versiona y se revisa igual que el código, sigue fiel al sistema que funciona en vez de desfasarse como un PDF. Las herramientas de IA pueden leerla para generar código y pruebas, detectar diferencias entre especificación e implementación y proponer cambios cuando cambian los contratos.

Qué contiene

• Descripciones funcionales: objetivos, usuarios, flujos y criterios de aceptación.
• Contratos: definiciones de API (por ejemplo, OpenAPI), esquemas de eventos y modelos de datos.
• Registros de decisiones de arquitectura que explican por qué las cosas se construyen así.
• Políticas y restricciones: reglas de seguridad, privacidad, rendimiento y cumplimiento.
• Pruebas y definiciones de evaluación que comprueban el sistema frente a la especificación.

Especificación viva frente a documento estático

Una especificación estática se escribe una vez, se aprueba y se queda atrás mientras el código avanza. Tras unas cuantas versiones, nadie se fía de ella.

Una especificación viva cambia en la misma pull request que el código. La revisión cubre las dos cosas, el historial muestra cuándo y por qué cambió cada requisito y las comprobaciones automáticas pueden parar la build cuando la implementación ya no cumple el contrato. La especificación pasa a ser una herramienta de trabajo, no un archivo.

Por qué importa con la IA

Los asistentes y agentes de programación con IA funcionan mejor con un contexto claro y actual. Una especificación viva les da la intención, las reglas y los contratos que necesitan, y así adivinan menos y el código sale más coherente.

También funciona al revés. La IA puede comparar especificaciones y código, proponer migraciones cuando cambia un contrato, regenerar pruebas y resumir qué cambió entre versiones. Enfoques como el desarrollo guiado por especificaciones ponen la especificación en el centro de ese ciclo.

Preguntas frecuentes

Guías de decisión que usan este término

• Reescribir el legacy o modernizarlo con IA: ¿empezar de cero o descifrar lo que ya tienes?

Para seguir leyendo

• Plataformas composables: los bloques de la agilidad empresarial
• DevOps y Ingeniería de plataformas: escalabilidad, autonomía y gobernanza en la era nativa de la nube
• Ingeniería de software agéntica: cómo la IA autónoma crea código empresarial

Términos relacionados

• API Interfaz definida que permite a un sistema pedir datos o acciones a otro; es la forma en que las aplicaciones llaman a los modelos de IA y los conectan con los sistemas de negocio.
• Evaluación Proceso de medir lo bien que funciona un modelo o una aplicación de IA: exactitud, relevancia, seguridad, sesgo, coste y otros criterios.
• Automatización Que el software ejecute tareas sin que una persona haga cada paso, cada vez más con IA para decidir y entender datos no estructurados.
• Catálogo de skills Registro gobernado de las skills que pueden usar los agentes de IA, con nombres, versiones, responsables, herramientas necesarias y dependencias.
• Downtime Periodo en el que un sistema, máquina o servicio no está disponible. La IA predictiva ayuda a reducir el no planificado anticipando averías antes de que ocurran.
• Especificación de API Una descripción formal y legible por máquina de los endpoints, esquemas de datos, autenticación y errores de una API, como un documento OpenAPI.