¿Qué es el desarrollo basado en especificaciones? La especificación como fuente de verdad

La especificación como fuente de la verdad, no como un documento secundario.

Índice

El desarrollo guiado por especificaciones es una de esas ideas a las que los ingenieros de software han recurrido en el pasado y luego han dejado de lado cuando el esfuerzo dejó de aportar beneficios.

Lo que cambió en 2025 es que los agentes de código de IA llegaron y hicieron que la ausencia de intención explícita fuera costosa. Los prompts son efímeros. Las sesiones de los agentes se reinician. El código cambia, pero el razonamiento detrás de él desaparece. La especificación es el artefacto que evita que esto ocurra.

¿Qué es el desarrollo guiado por especificaciones? – la especificación como fuente de verdad para la IA

La especificación se está convirtiendo en la fuente de verdad

Durante la mayor parte de la historia del desarrollo de software, la especificación era o bien un artefacto de planificación temporal o una reflexión posterior. Los requisitos vivían en tickets, las decisiones de diseño en hilos de chat y el código era la verdad fundamental. La documentación describía lo que existía a posteriori.

El desarrollo guiado por especificaciones invierte esa relación. La especificación se convierte en el artefacto principal. El código es lo que se genera o verifica contra la especificación, no al revés.

Esta no es una idea nueva. Los métodos formales, el diseño por contrato y el BDD (Desarrollo Guiado por Comportamiento) contienen versiones de esto. Lo nuevo es la motivación práctica: los agentes de código de IA necesitan un contexto explícito y duradero para producir un resultado correcto y consistente. Los prompts son demasiado efímeros. La especificación es el único artefacto que puede transportar la intención a través de las sesiones del agente, entre los miembros del equipo y a través del tiempo.

Qué significa realmente el desarrollo guiado por especificaciones

El desarrollo guiado por especificaciones, usualmente abreviado como SDD, es un flujo de trabajo donde una especificación versionada guía o genera la implementación. La especificación se escribe y revisa antes de que el agente escriba código. Captura:

  • Qué construir – problema del usuario, objetivos y no objetivos
  • Cómo se ve el comportamiento correcto – criterios de aceptación, casos límite, estados de error
  • Cómo construirlo – decisiones de arquitectura, modelo de datos, contratos de API, restricciones de seguridad
  • Cómo verificarlo – estrategia de pruebas, reglas de validación, trazabilidad hacia los requisitos

La especificación no es un documento de un solo uso. Se actualiza cuando la realidad difiere del diseño. Cuando el agente descubre algo durante la implementación que la especificación tuvo incorrecto, la especificación se corrige antes de continuar. La especificación se mantiene honesta porque se trata como código.

El trabajo académico reciente formaliza este marco: los investigadores describen el SDD como el tratamiento de las especificaciones como la fuente de verdad y el código como generado o verificado contra ellas. La interpretación práctica es que la especificación es el registro revisado y duradero de la intención que cualquier humano o herramienta de IA puede leer y confiar.

Tres términos capturan diferentes puntos en el espectro de uso de especificaciones:

Primero la especificación significa escribir la especificación completa antes de que comience cualquier implementación. Esta es la interpretación más estricta y la más cercana al modelo en cascada si no se hace con cuidado.

Anclado a la especificación significa mantener una especificación sincronizada con la implementación a lo largo del ciclo de vida de la funcionalidad. La especificación se actualiza a medida que cambian las decisiones. Esta es la versión más práctica para la mayoría de los equipos.

Especificación como fuente significa generar o validar la implementación desde la especificación, ya sea a través de agentes de IA o a través de herramientas que verifican el código contra las restricciones de la especificación. Esta es la dirección hacia la que se mueven herramientas como GitHub Spec Kit y Kiro.

Por qué el SDD importa ahora

La respuesta honesta es que el SDD no es convincente para un desarrollador individual que construye un script de un día. El sobrecosto no vale la pena.

El SDD se vuelve valioso cuando están presentes tres condiciones: la funcionalidad es lo suficientemente grande como para abarcar múltiples sesiones, el agente necesita tomar decisiones que afecten la arquitectura y el trabajo será revisado o continuado por otra persona.

Las tres condiciones son cada vez más comunes con el desarrollo asistido por IA.

Los LLMs necesitan contexto, no solo prompts. Un modelo que recibe un prompt vago toma decisiones vagas. Un modelo que recibe una especificación revisada con restricciones explícitas, no objetivos y criterios de aceptación toma mejores decisiones y es más fácil de corregir cuando se desvía. Esto se conecta con cómo funcionan la recuperación y representación: darle a un agente una especificación versionada es una forma de recuperación estructurada de la intención del proyecto.

La generación de código es barata; decidir qué construir sigue siendo difícil. El cuello de botella en el desarrollo asistido por IA ya no es escribir – es saber qué construir y cómo restringir al agente. El SDD desplaza el esfuerzo a donde importa: especificar la intención claramente antes de que comience la generación.

Los prompts son efímeros. El agente no recuerda lo que le dijiste en la última sesión. Una especificación versionada almacenada en el repositorio sí lo hace. Cada nueva sesión puede leer la misma especificación e implementar contra la misma intención sin restablecer el contexto desde cero.

La “vibe coding”](https://www.glukhov.org/es/ai-devtools/vibe-coding/ “¿Qué es Vibe Coding – Significado, Herramientas, Beneficios y Riesgos en 2026”) funciona hasta que no lo hace. Para prototipos y trabajo desechable, el prompting ad-hoc es más rápido y apropiado. En cuanto una funcionalidad requiere restricciones de seguridad, decisiones de arquitectura multiarchivo o una transferencia de equipo, la ausencia de una especificación se convierte en la principal fuente de desviación y defectos. Ver la comparación en SDD vs Vibe Coding para saber cuándo aplica cada enfoque.

Artefactos principales

Un flujo de trabajo práctico de SDD produce cuatro artefactos principales. Cada uno reduce un tipo específico de ambigüedad antes de que llegue al agente.

Especificación de requisitos. La declaración del problema, los usuarios afectados, los objetivos, los no objetivos explícitos y los criterios de aceptación. Los no objetivos son tan importantes como los objetivos – le dicen al agente qué no construir y previenen la expansión del alcance. Los criterios de aceptación son lo suficientemente precisos para que cada uno se mapee a al menos una prueba.

Especificación de diseño. Las decisiones arquitectónicas relevantes para esta funcionalidad: módulos afectados, cambios en el modelo de datos, contratos de API, migraciones, restricciones de seguridad, requisitos de observabilidad y modos de falla conocidos. Este no es un documento de diseño de sistema completo – es el subconjunto de decisiones de arquitectura necesarias para implementar esta funcionalidad correctamente.

Plan de tareas. Una secuencia de pequeñas tareas de implementación, cada una con dependencias explícitas, cambios de archivos esperados y criterios de validación. Las tareas son lo suficientemente pequeñas para implementarse en una sola sesión del agente y verificarse con un diff enfocado. Cada tarea tiene un punto de control de revisión humana.

Registro de trazabilidad. Un mapeo desde los criterios de aceptación hacia las pruebas, desde las decisiones de diseño hacia los archivos afectados y desde las tareas hacia los commits. Esto es lo que separa al SDD de la documentación que se vuelve obsoleta: la trazabilidad hace posible verificar que la especificación fue realmente implementada, no solo escrita.

Estos artefactos no tienen que ser pesados. Una funcionalidad simple podría producir un único documento markdown de dos páginas cubriendo las cuatro áreas. El formato importa menos que el hábito de escribir la intención antes de que comience la implementación.

Cómo el SDD difiere de la documentación

La confusión más común es tratar los artefactos de SDD como documentación. No son documentación en el sentido convencional.

La documentación describe. Te dice qué hace el sistema, cómo usarlo y qué contiene. Se escribe a posteriori y se actualiza cuando el sistema cambia.

Las especificaciones restringen. Una especificación le dice al agente qué está permitido construir y qué no está permitido hacer. Es autoritativa antes de que comience la implementación. Se valida después de que la implementación se completa. Una especificación que describe lo que realmente se construyó – en lugar de restringir lo que debería construirse – ya ha fallado en su propósito.

Las especificaciones ejecutables guían la generación y validación. Las mejores especificaciones de SDD están lo suficientemente cerca de ser legibles por máquina para que un agente pueda implementar contra ellas y un conjunto de pruebas pueda verificarlas. Los criterios de aceptación escritos como “el endpoint debe rechazar solicitudes no autenticadas con una respuesta 401” son una especificación ejecutable; “el endpoint es seguro” es documentación.

Registros de decisiones – ADRs, PDRs y DDRs – son complementarios a los artefactos de SDD pero sirven un propósito diferente. Los registros de decisiones capturan por qué se tomó una elección y qué se rechazó. Las especificaciones de SDD capturan qué construir y cómo verificarlo. Ambos pertenecen en el repositorio. Juntos le dan a los agentes de IA la imagen completa: la intención actual y el razonamiento detrás de ella.

Cómo el SDD difiere del TDD

El Desarrollo Guiado por Pruebas y el Desarrollo Guiado por Especificaciones a menudo se confunden porque ambos producen artefactos explícitos antes de que exista el código. La diferencia es el punto de partida.

El TDD comienza con pruebas. Escribes una prueba fallida que describe el comportamiento que deseas, luego escribes el código mínimo para que pase. El TDD es un bucle de retroalimentación a nivel de unidad. Produce buenas pruebas pero no responde a la pregunta de si estás construyendo la cosa correcta.

El SDD comienza con la intención. Antes de que existan las pruebas, antes de que se decida la arquitectura, la especificación responde: quién tiene este problema, cómo se ve el comportamiento correcto, qué está explícitamente fuera de alcance. La especificación luego informa qué pruebas escribir, por lo que el buen SDD y el buen TDD son complementarios en lugar de competitivos.

Una manera práctica de pensarlo: el SDD impulsa al TDD. Los criterios de aceptación en la especificación se convierten en los escenarios de prueba. La especificación de diseño identifica los límites de integración que necesitan pruebas de contrato. El plan de tareas identifica qué comportamientos de unidad necesitan cobertura de pruebas antes de que el agente los implemente.

Cómo el SDD difiere del BDD

El Desarrollo Guiado por Comportamiento utiliza escenarios de lenguaje natural – típicamente en formato Gherkin – para describir el comportamiento esperado desde la perspectiva del usuario. Estos escenarios puentean la brecha entre la intención comercial y la implementación técnica.

El SDD es más amplio. Incluye descripciones de comportamiento (que pueden usar lenguaje estilo BDD o prosa simple) pero también cubre decisiones de arquitectura, modelos de datos, restricciones de seguridad, planificación de tareas y trazabilidad. El BDD puede ser un formato útil para escribir criterios de aceptación dentro de una especificación de requisitos de SDD. La especificación es el contenedor; los escenarios de BDD son una manera de escribir lo que va dentro.

La distinción importa en la práctica: las herramientas de BDD se centran en hacer que los escenarios sean ejecutables. La práctica de SDD se centra en hacer que la intención sea duradera – a través de herramientas, a través de sesiones y a través de miembros del equipo.

Cómo el SDD difiere de los Métodos Formales

Los métodos formales utilizan notación matemática y verificación automatizada para probar propiedades de los sistemas de software. Son extremadamente rigurosos y extremadamente costosos para la mayoría de los contextos de desarrollo de producción.

El SDD no requiere notación formal. Un archivo markdown con criterios de aceptación y decisiones de arquitectura es una especificación. Restringe sin ser matemáticamente formal. El nivel de rigor escala con las apuestas: una especificación para un servicio de facturación debería ser más precisa y revisada con más cuidado que una especificación para una página de documentación.

La relación es un espectro:

  • Especificación de prosa informal (SDD mínimo viable)
  • Markdown estructurado con criterios de aceptación y no objetivos
  • Especificación legible por máquina con validación de esquema
  • Pruebas de contrato derivadas directamente de la especificación
  • Especificación formal con prueba automatizada

La mayoría de los equipos operan en el medio de ese espectro. El objetivo no es el rigor matemático – es hacer la intención lo suficientemente explícita para que un agente de IA pueda implementar contra ella y un revisor humano pueda verificar el resultado.

Beneficios del Desarrollo Guiado por Especificaciones

Menos deriva de intención. La especificación es la referencia. Cuando el agente se desvía – y lo hará – el revisor tiene algo contra qué comparar la implementación. Sin una especificación, la deriva es invisible hasta que algo se rompe.

Mejores salidas de IA. Los agentes dados restricciones explícitas, no objetivos y criterios de aceptación producen implementaciones que están más cerca de lo que se pretendía y son más fáciles de corregir cuando fallan. La calidad del contexto determina directamente la calidad de la salida.

Revisión más fácil. Una solicitud de extracción (pull request) adjunta a una especificación es más fácil de revisar que una que requiere que el revisor reconstruya la intención desde el código. La especificación es la lista de verificación para la revisión.

Alineación del equipo. Cuando varias personas o agentes trabajan en la misma funcionalidad, la especificación es el contrato compartido. Sin ella, cada contribuyente optimiza localmente y las piezas pueden no encajar.

Mejor planificación de pruebas. Los criterios de aceptación en la especificación se mapean directamente a casos de prueba. La cobertura de pruebas se convierte en una pregunta de cobertura de especificación: ¿está cada criterio de aceptación cubierto por al menos una prueba?

Transferencia duradera. Cuando una funcionalidad cambia de manos – entre ingenieros, entre sesiones de agentes, entre sprints – la especificación es el artefacto de transferencia. Captura lo que se decidió, lo que estaba fuera de alcance y lo que queda por validar.

Costos del Desarrollo Guiado por Especificaciones

Esfuerzo inicial. Escribir una buena especificación antes de escribir cualquier código toma tiempo. Para funcionalidades pequeñas, este sobrecosto es real y a veces no vale la pena.

Falsa confianza. Una especificación que existe pero no se valida contra la implementación da una falsa sensación de corrección. Las especificaciones obsoletas a veces son peores que no tener especificación: engañan a los revisores y agentes que las leen.

Especificaciones obsoletas. Las especificaciones se desvían cuando el equipo las trata como artefactos de planificación en lugar de documentos vivos. Actualizar la especificación cuando la implementación difiere del diseño no es opcional – es lo que separa al SDD de la documentación que se acumula y se pudre.

Burocracia generada. Los agentes de IA pueden generar listas de tareas exhaustivas y especificaciones verbosas rápidamente. Una especificación de 200 tareas generada en treinta segundos no es una especificación útil – es un generador de burocracia. El buen SDD requiere juicio sobre qué especificar y qué dejar implícito.

Bloqueo de herramientas. Algunas herramientas de SDD tienen opiniones sobre formato, estructura de archivos y flujo de trabajo. Una especificación escrita en un formato propietario es más difícil de transportar entre herramientas que un archivo markdown con encabezados claros y criterios de aceptación.

Conclusión

El Desarrollo Guiado por Especificaciones no es una metodología nueva. Es una disciplina antigua que se vuelve práctica nuevamente porque el costo de la intención implícita ahora es visible en el código generado por IA.

La disciplina es simple: escribe qué pretendes construir, revisado y versionado, antes de que el agente lo construya. Mantén ese registro honesto actualizándolo cuando la realidad difiera. Úsalo como referencia para la revisión, las pruebas y la transferencia.

La especificación no es magia. Una especificación que no se valida se convierte en el tipo más costoso de documentación: uno que engaña con confianza. El buen SDD es la práctica de mantener las especificaciones honestas – lo suficientemente pequeñas para mantener, lo suficientemente precisas para restringir y lo suficientemente duraderas para sobrevivir a cualquier sesión individual de agente.

El SDD se encuentra en la intersección de la práctica de documentación, la arquitectura de pruebas y el diseño de código – todo cubierto en el clúster de Arquitectura de Aplicaciones en Producción junto con registros de decisiones, diseño de API y patrones de acceso a datos.

Enlaces útiles

Suscribirse

Recibe nuevas publicaciones sobre sistemas, infraestructura e ingeniería de IA.