¿Qué es el Spec-Driven Development?

El Spec-Driven Development (SDD) es una práctica donde escribes una especificación detallada antes de escribir cualquier línea de código. La spec actúa como un contrato: describe qué debe hacer una funcionalidad, cuáles son las entradas y salidas, qué casos borde hay que contemplar y qué restricciones aplican.

No es una idea nueva. Comparte raíces con el Test-Driven Development y el Design-by-Contract. Lo que cambió es que las herramientas de IA ahora pueden consumir estas especificaciones y producir código funcional a partir de ellas, lo que hace que la práctica sea mucho más valiosa que hace apenas dos años.

Por qué el SDD funciona mejor con IA

Cuando le das un prompt a un modelo de IA sin contexto, obtienes resultados genéricos. Cuando le das una especificación detallada, obtienes algo mucho más cercano a lo que realmente necesitas.

La spec te obliga a pensar el problema antes de que la IA lo toque. Ese pensamiento previo es la parte más valiosa. Una funcionalidad mal especificada genera interfaces inventadas, manejo incorrecto de casos borde y código que terminarás reescribiendo de todas formas. Una funcionalidad bien especificada genera código que puedes revisar y desplegar.

El otro beneficio es la consistencia a lo largo de una base de código. La spec se convierte en un artefacto reutilizable. Nuevos integrantes del equipo, asistentes de IA e incluso tu yo del futuro pueden entender qué hace un componente — y por qué — sin leer la implementación.

El flujo de trabajo

1. Exploración del problema

Empieza entendiendo el problema. Aquí la IA es genuinamente útil como socio de pensamiento.

Prompt: Necesito agregar rate limiting a nuestra API pública. ¿Cuáles son los
tradeoffs entre token bucket, leaky bucket y ventana fija para una app Rails?

Usa la respuesta para informar tus decisiones de diseño. Haz preguntas de seguimiento. El objetivo no es generar código todavía — es entender el espacio de soluciones.

2. Escribir la especificación

Ahora escribe la especificación. Es texto plano o markdown que describe lo que vas a construir:

## Funcionalidad: Rate Limiting en API

**Objetivo**: Limitar las requests autenticadas a 1.000 por hora por usuario.

**Algoritmo**: Token bucket implementado con Redis.

**Comportamiento**:
- Cada usuario comienza con el bucket lleno (1.000 tokens).
- Cada request consume 1 token.
- Los tokens se recargan a razón de 1.000/hora (continuo, no por lotes).
- Las requests que superen el límite reciben una respuesta 429 con header Retry-After.
- Las requests no autenticadas no están limitadas en esta etapa.

**Headers devueltos en cada request**:
- X-RateLimit-Limit: 1000
- X-RateLimit-Remaining: <tokens actuales>
- X-RateLimit-Reset: <unix timestamp cuando se recarga el bucket>

**Casos borde**:
- Redis no disponible: fallar abierto (permitir la request, registrar el error).
- Diferencia de relojes: usar la hora del servidor Redis, no del servidor de app.

Esto tomó 10 minutos escribirlo. Va a ahorrar horas de iteración.

3. Planificar

Antes de escribir código, usa la IA para producir un plan técnico:

Prompt: En base a esta spec, describe las clases, métodos y estructura de claves
Redis necesarios para implementar esto en una API Rails. Lista las dependencias.

Revisa el plan. Cuestiona lo que no encaje con tu arquitectura. Este es el momento de detectar malentendidos antes de que se conviertan en bugs.

4. Generar el código

Ahora deja que la IA escriba la implementación:

Prompt: Implementa la clase RateLimiter del plan anterior. Usa la gema redis-rb.
Incluye tests unitarios con RSpec y mockea las llamadas a Redis.

Obtendrás código que puedes usar de verdad. Como la spec fue clara, la IA tuvo suficiente contexto para tomar decisiones razonables.

5. Revisión

Lee el código generado de forma crítica. Verifica:

  • ¿Coincide con la spec?
  • ¿Están manejados los casos borde (Redis no disponible, diferencia de relojes)?
  • ¿La estructura de claves en Redis es coherente?
  • ¿Hay algún problema de seguridad (inyección de claves, timing attacks)?

La IA no va a detectar todo. Tu rol como ingeniero es revisar, no aprobar a ciegas.

Beneficios

Velocidad: Pasar de la spec a un borrador funcional en minutos en lugar de horas cambia la economía de un proyecto. Funcionalidades que antes se postergaban ahora se construyen.

Documentación: La spec es documentación. A diferencia de los comentarios en el código, no se desactualiza — representa el comportamiento intencional en el momento del diseño.

Incorporación de nuevos integrantes: Un desarrollador que recibe una spec más su implementación puede entender la funcionalidad en 15 minutos.

Calidad del prompt: Escribir specs te hace mejor para hacer prompts. Los hábitos son los mismos: sé específico, define límites, describe el comportamiento y no la implementación.

Errores comunes

Tratar el código generado como código terminado. Es un borrador. Siempre revisa. Los modelos de IA pueden producir código que parece correcto pero tiene errores sutiles, especialmente en concurrencia, seguridad y casos borde.

Subespecificar. Una spec de una línea produce una respuesta de una línea. Si la spec es vaga, el código va a asumir cosas — y esas suposiciones pueden no coincidir con tu sistema.

Saltarse el paso de planificación. Ir directamente de la spec al código aumenta la probabilidad de un desajuste arquitectónico. El paso de planificación lo detecta antes de escribir el código.

No testear el resultado. El código generado debe testearse como cualquier otro código. Si la spec incluye expectativas de comportamiento, esas se traducen directamente en casos de test.

Spec Kit: SDD como toolkit open source

GitHub lanzó Spec Kit — un toolkit open source que formaliza el SDD en un proceso estructurado con tres fases claras y comandos listos para usar con agentes de IA como Copilot, Claude Code y Gemini CLI.

Las 3 fases de Spec Kit

1. Specify (/speckit.specify): Transforma ideas vagas en documentos de requisitos completos. Se enfoca en necesidades de negocio y valor para el usuario, sin detalles de implementación. Las ambigüedades se marcan explícitamente con [NEEDS CLARIFICATION].

2. Plan (/speckit.plan): Convierte especificaciones en planes de implementación técnicos. Mapea requisitos a decisiones arquitectónicas con justificación documentada. Genera modelos de datos, contratos de API y escenarios de prueba.

3. Tasks (/speckit.tasks): Deriva listas de tareas ejecutables a partir del plan. Identifica oportunidades de trabajo paralelo y produce entregables concretos listos para generación de código.

La inversión de poder

La filosofía central de Spec Kit es que las especificaciones no sirven al código — el código sirve a las especificaciones. El PRD no es una guía para la implementación; es la fuente que genera la implementación. Cuando la spec dirige todo, no hay brecha entre intención y ejecución — solo transformación.

En la práctica, esto significa que Spec Kit trata el lenguaje natural como un artefacto ejecutable. Templates estructurados restringen el output de la IA para producir specs de mayor calidad, y principios constitucionales (como “test-first” y “library-first”) garantizan que el código generado mantenga consistencia.

Por qué importa

Antes de Spec Kit, cada equipo improvisaba su flujo de SDD. Ahora existe un proceso estandarizado, con templates validados y gates de calidad integrados. Si trabajas con agentes de IA para desarrollo, vale la pena probarlo.

Herramientas

  • Spec Kit — Framework de SDD con fases y templates estructurados
  • Claude Code (Anthropic) — Funciona bien con specs largas y ventanas de contexto amplias
  • Cursor — IA integrada en el IDE con buena conciencia del codebase existente
  • GitHub Copilot — Mejor para completado inline y tareas pequeñas bien definidas

SDD es una disciplina, no una herramienta

Las herramientas cambian. Claude va a ser reemplazado por algo mejor. Cursor va a ganar nuevas funciones. Spec Kit puede evolucionar en algo diferente. La práctica de fondo — pensar bien, especificar con precisión, luego construir — sigue siendo valiosa independientemente de cómo evolucione el stack de IA.

El Spec Kit de GitHub formalizó este proceso en algo replicable y open source. Si ya escribes buenas specs antes de codear, incorporar IA al flujo es directo. Si no lo haces, el SDD vale la pena adoptarlo por sus propios méritos. La integración con IA es simplemente el acelerador.

Referencias