¿Qué es el desarrollo orientado a 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 (Spec-Driven Development) es una de esas ideas a la que los ingenieros de software han recurrido antes 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 convirtieron la ausencia de intención explícita en algo costoso. 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 impide que esto ocurra.

What Is Spec-Driven Development – the spec as source of truth for AI coding

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 fue un artefacto de planificación temporal o un pensamiento tardío. 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 primario. 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 todas versiones de esto. Lo que es nuevo es la motivación práctica: los agentes de codificación con IA necesitan un contexto explícito y duradero para producir una salida correcta y consistente. Los prompts son demasiado efímeros. La especificación es el único artefacto que puede llevar la intención a través de las sesiones de agentes, entre miembros del equipo y a través del tiempo.

Lo que realmente significa 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 código. Captura:

  • Qué construir – problema del usuario, objetivos y no-objetivos
  • Cómo se ve un 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 saltarse 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 datos: 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 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 tenía mal, 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 enfoque: 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 herramienta humana o de IA puede leer y confiar.

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

Spec-first (Especificación primero) 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 cascada (waterfall) si no se hace con cuidado.

Spec-anchored (Anclado a la especificación) significa mantener una especificación sincronizada con la implementación a lo largo de todo el 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.

Spec-as-source (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 mediante herramientas que comprueben el código contra las restricciones de la especificación. Esta es la dirección hacia la que se dirigen herramientas como GitHub Spec Kit y Kiro, cada una con un intercambio diferente entre portabilidad y orientación integrada en el IDE. Los paquetes de habilidades como Superpowers se sitúan más cerca del extremo de “anclado a la especificación” – aplican la disciplina de revisión automáticamente en lugar de generar código directamente desde la especificación.

Por qué el SDD importa ahora

La respuesta honesta es que el SDD no es convincente para un desarrollador solitario que construye un guion de un solo día. La sobrecarga no vale la pena.

El SDD se vuelve valioso cuando se presentan tres condiciones: la funcionalidad es lo suficientemente grande como para abarcar múltiples sesiones, el agente necesita tomar decisiones que afectan 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 la digitación – 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.

**Vibe coding es más rápido para trabajo desechable; SDD vs Vibe Coding cubre cuándo agregar especificaciones y cuándo seguir usando 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 funcionalidad
  • Plan de tareas – pequeñas porciones de implementación con dependencias y criterios de validación
  • Registro de trazabilidad – mapeo desde los criterios de aceptación hacia las pruebas, de las decisiones de diseño hacia los archivos, y de las tareas hacia los commits

Cómo producir y revisar estos pasos a paso – especificar, planificar, tareas, implementar, validar – se cubre en Flujo de trabajo de Desarrollo Guiado por Especificaciones de requisitos a código. Una funcionalidad simple puede cubrir las cuatro áreas en un archivo de 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 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 después del hecho y se actualiza cuando el sistema cambia.

Las especificaciones restringen. Una especificación le dice al agente qué le está permitido construir y qué no le 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 se construyó realmente – en lugar de restringir lo que debe ser construido – ya ha fallado en su propósito.

Las especificaciones ejecutables guían la generación y la 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. Criterios de aceptación escritos como “el endpoint debe rechazar las solicitudes no autenticadas con una respuesta 401” es 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 a un propósito diferente. Los registros de decisiones capturan por qué se tomó una elección y qué fue rechazado. 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 (Test-Driven Development) y el Desarrollo Guiado por Especificaciones a menudo se confunden porque ambos producen artefactos explícitos antes de que exista 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 hacerla pasar. 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 pruebas, antes de que se decida la arquitectura, la especificación responde: quién tiene este problema, cómo se ve un 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 competidores.

Una forma práctica de pensar en esto: el SDD dirige 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 (Behavior-Driven Development) usa escenarios en lenguaje natural – típicamente en formato Gherkin – para describir el comportamiento esperado desde la perspectiva del usuario. Estos escenarios sirven de puente entre la intención de 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 de SDD. La especificación es el contenedor; los escenarios BDD son una forma de escribir lo que va dentro de ella.

La distinción importa en la práctica: las herramientas de BDD se enfocan en hacer que los escenarios sean ejecutables. La práctica de SDD se enfoca 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 demostrar propiedades de 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 de 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 en prosa informal (SDD mínimamente 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 demostración automatizada

La mayoría de los equipos operan en la mitad 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 con 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 intentó 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 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 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: ¿cada criterio de aceptación está cubierto por al menos una prueba?

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

Costos del Desarrollo Guiado por Especificaciones

Esfuerzo previo. Escribir una buena especificación antes de escribir cualquier código toma tiempo. Para pequeñas funcionalidades, esta sobrecarga 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 a los 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 fuertes sobre formato, estructura de archivos y flujo de trabajo. Una especificación escrita en un formato propietario es más difícil de llevar entre herramientas que un archivo de markdown con encabezados claros y criterios de aceptación.

Conclusión

El Desarrollo Guiado por Especificaciones no es una nueva metodología. Es una vieja disciplina 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 intentas 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 revisión, pruebas y entrega.

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. El buen SDD es la práctica de mantener las especificaciones honestas – lo suficientemente pequeñas para mantenerlas, lo suficientemente precisas para restringir, y lo suficientemente duraderas para sobrevivir a cualquier sesión individual de agente.

El SDD se sitúa 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 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.