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

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

Índice

El Desarrollo Guiado por Especificaciones es una de esas ideas a la que los ingenieros de software han recurrido en el pasado y luego han dejado de lado cuando el esfuerzo dejó de ser rentable.

Lo que cambió en 2025 es que llegaron los agentes de codificación con IA y hicieron que la ausencia de una 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 un pensamiento posterior. Los requisitos vivían en tickets, las decisiones de diseño vivían en hilos de chat y el código era la verdad fundamental. La documentación describía lo que existía después del hecho.

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 ello. Lo nuevo es la motivación práctica: los agentes de codificación con 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, generalmente 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 el 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

Ese último punto es fácil de escribir y fácil de omitir en la práctica. Mantener especificaciones, pruebas y código sincronizados en el desarrollo con IA cubre cómo se ve realmente la trazabilidad hacia los requisitos como dato: IDs de requisitos, IDs de decisiones de diseño y pruebas vinculadas a las solicitudes de extracción (pull requests) que las implementaron.

La especificación no es un documento de una sola vez. Se actualiza cuando la realidad difiere del diseño. Cuando el agente descubre algo durante la implementación que la especificación hizo mal, la especificación se corrige antes de continuar. La especificación permanece honesta porque se trata como código.

El trabajo académico reciente formaliza este enfoque: los investigadores describen el SDD como tratar 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.

Especificación anclada significa mantener una especificación sincronizada con la implementación a lo largo del ciclo de vida de la característica. 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, cada una con una compensación diferente entre portabilidad y guía integrada en el IDE.

Por qué el SDD importa ahora

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

El SDD se vuelve valioso cuando se presentan tres condiciones: la característica es lo suficientemente grande como para abarcar múltiples sesiones, el agente necesita tomar decisiones que afecten a 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 la 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 reestablecer el contexto desde cero.

**La codificación por ambiente es más rápida para trabajos desechables; SDD vs Codificación por Ambiente cubre cuándo agregar especificaciones y cuándo continuar haciendo prompts libremente.

Artefactos principales

El SDD produce cuatro tipos de artefactos. Cada uno reduce un tipo diferente de ambigüedad antes de que el agente toque el código:

  • Especificación de requisitos – problema, usuarios, objetivos, no objetivos, criterios de aceptación
  • Especificación de diseño – arquitectura, modelo de datos, contratos de API, restricciones de seguridad para esta característica
  • Plan de tareas – porciones pequeñas de implementación con dependencias y criterios de validación
  • Registro de trazabilidad – mapeo desde los criterios de aceptación a las pruebas, decisiones de diseño a archivos, tareas a commits

Cómo producirlos y revisarlos paso a paso – especificar, planificar, tareas, implementar, validar – se cubre en Flujo de Trabajo de Desarrollo Guiado por Especificaciones Desde Requisitos hasta Código. Una característica simple puede cubrir las cuatro áreas en un archivo markdown corto. El hábito importa más que el formato.

Cómo el SDD difiere de la documentación

La confusión más común es tratar los artefactos del 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 después del hecho 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 se completa la implementación. 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 la validación. Las mejores especificaciones del 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 Decisión – ADRs, PDRs y DDRs – son complementarios a los artefactos del SDD pero sirven un propósito diferente. Los registros de decisión capturan por qué se tomó una elección y qué se rechazó. Las especificaciones del 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 (TDD) y el Desarrollo Guiado por Especificaciones (SDD) 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, que es por qué un buen SDD y un buen TDD son complementarios en lugar de competidores.

Una manera práctica de pensarlo: el SDD impulsa el 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 (BDD) usa 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 del negocio 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 del SDD. La especificación es el contenedor; los escenarios BDD son una manera de escribir lo que va dentro de ella.

La distinción importa en la práctica: las herramientas de BDD se centran en hacer que los escenarios sean ejecutables. La práctica del 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 usan 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 debe 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 viable mínimo)
  • 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 que la intención sea 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 adjunta a una especificación es más fácil de revisar que una solicitud de extracción 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 característica, 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 característica cambia de manos – entre ingenieros, entre sesiones de agente, entre sprints – la especificación es el artefacto de transferencia. Captura qué se decidió, qué estaba fuera de alcance y qué 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 características 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 ninguna 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. Un buen SDD requiere juicio sobre qué especificar y qué dejar implícito.

Bloqueo de herramientas. Algunas herramientas de SDD son opinadas sobre el formato, la estructura de archivos y el 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 lo que 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 caro de documentación: una que engaña con confianza. Un 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 de agente individual.

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 Arquitectura de Aplicaciones en Producción junto con registros de decisión, diseño de API y patrones de acceso a datos.

Enlaces útiles

Suscribirse

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