Desarrollo Dirigido por Especificación
Metodología de desarrollo donde la especificación se escribe antes del código, sirviendo como contrato entre equipos y como fuente de verdad para la implementación.
¿Qué es?
Spec-Driven Development (SDD) es una metodología donde se escribe una especificación detallada antes de escribir código. La especificación — no el código — es la fuente de verdad del proyecto.
Es lo opuesto al enfoque «code-first» donde primero se implementa y luego se documenta (si es que se documenta). En SDD, la especificación funciona como un contrato: define qué debe hacer el sistema, cómo se comunican sus partes y qué esperar de cada interfaz.
¿Por qué importa ahora?
SDD no es nuevo — el diseño API-first con OpenAPI/Swagger existe desde hace años. Pero la llegada de agentes de IA que generan código ha hecho que esta metodología sea más relevante que nunca.
Cuando un agente de IA genera código, necesita instrucciones claras y no ambiguas. Una especificación bien escrita es exactamente eso: un documento estructurado que define comportamiento esperado, tipos de datos, contratos de interfaz y criterios de aceptación.
Sin especificación, el agente adivina. Con especificación, el agente implementa.
El ciclo SDD
- Definir: escribir la especificación en un formato estructurado (OpenAPI, JSON Schema, protobuf, o incluso un documento de requisitos detallado)
- Validar: revisar la especificación con todos los involucrados antes de escribir código
- Generar: crear código base, mocks y tests a partir de la especificación
- Implementar: escribir la lógica de negocio dentro de la estructura generada
- Verificar: confirmar que la implementación cumple con la especificación
Aplicaciones
APIs (el caso clásico)
El uso más establecido. Se escribe la especificación OpenAPI primero, se generan stubs de servidor y clientes, y luego se implementa la lógica.
Beneficios concretos:
- Frontend y backend pueden trabajar en paralelo desde el día uno
- Los contratos de API son explícitos y versionados
- Los tests de contrato se generan automáticamente
Desarrollo asistido por IA
Cuando se usa un agente de IA para generar código, la especificación actúa como prompt estructurado:
- Define los tipos y modelos de datos exactos
- Establece los comportamientos esperados con ejemplos
- Especifica restricciones y casos borde
- Proporciona criterios de aceptación verificables
Esto reduce significativamente las alucinaciones y el código incorrecto porque el agente tiene un contrato claro contra el cual trabajar.
Protocolos (MCP, A2A)
El Model Context Protocol es un ejemplo de SDD aplicado a protocolos de IA. La especificación define exactamente cómo deben comunicarse clientes y servidores, qué mensajes son válidos y qué respuestas esperar. Cualquier implementación que cumpla la especificación es interoperable.
Formatos de especificación comunes
| Formato | Uso principal |
|---|---|
| OpenAPI | APIs REST |
| JSON Schema | Validación de datos |
| Protocol Buffers | APIs gRPC, serialización |
| AsyncAPI | APIs basadas en eventos |
| JSON-RPC | Protocolos como MCP |
¿Cuándo no usar SDD?
- Prototipos rápidos: cuando se explora una idea y la especificación cambiaría cada hora
- Proyectos de una persona: el overhead de mantener una especificación formal puede no justificarse
- Dominios desconocidos: si no se entiende bien el problema, escribir una especificación prematura puede ser contraproducente
En estos casos, un enfoque iterativo donde la especificación emerge del código puede ser más práctico.
Referencias
- What Is Specification-Driven API Development? — Nordic APIs. Introducción clara al concepto.
- Using spec-first API development for speed and sanity — Atlassian, 2024. Caso práctico de adopción en equipos grandes.
- OpenAPI Specification — El estándar más usado para especificaciones de API REST.
- Model Context Protocol Specification — Ejemplo de SDD aplicado a un protocolo de IA.