Spec-Driven Development: por qué la calidad se diseña antes de construir

El problema con construir primero

Muchos equipos comienzan donde creen que debe empezarse: escribiendo código. O pidiendo a la IA que genere componentes, flujos, integraciones. El resultado es predecible: funciona, pero nadie sabe con certeza qué hace, por qué lo hace así, o cómo cambiar una pieza sin romper otras.

Eso ocurre porque la calidad se convierte en un problema de inspección: esperas a tener algo terminado, lo pruebas, descubres defectos, vuelves atrás. Es como construir una casa, inspeccionar los cimientos después de la azotea y recién entonces descubrir que están mal. El costo de corrección es exponencial.

En Galaxy ocurre lo opuesto.

Qué es Spec-Driven Development

Spec-Driven Development (SDD) invierte el orden: antes de escribir una línea de código, escribes la especificación. No es documentación decorativa que nadie lee después. Es un artefacto verificable que define qué construir, cómo debe comportarse, y cómo sabrás que funciona.

La especificación es tu verdad única. Cada miembro del equipo, cada herramienta (incluida la IA), cada fase de verificación la consulta. No hay interpretaciones flotantes. No hay "creí que querías esto pero construí aquello".

Por qué primero la especificación

Escribir el spec antes de construir obliga a pensar. A hacer preguntas incómodas:

• ¿Cuál es el resultado deseado exactamente?
• ¿Bajo qué condiciones se considera completo?
• ¿Qué puede salir mal y cómo lo detectamos?
• ¿Qué sucede si el usuario hace X cuando esperábamos que hiciera Y?

Esta claridad es donde habita la calidad. No en el código elegante. En decisiones conscientes, registradas, comunicadas.

La IA aporta el volumen: puede generar funciones, escribir tests, sugerir flujos. Pero genera en función de qué le pidas. Si le pasas un spec preciso, el volumen es útil. Si le pasas vagas intenciones, el volumen es ruido.

El ciclo Spec → Plan → Build → Operate

Fase 1: Spec (Especificación)

Aquí escribes qué se construye, no cómo. Incluye:

• Descripción funcional del comportamiento esperado
• Criterios de aceptación (escenarios concretos)
• Casos límite y situaciones de error
• Interfaces de entrada y salida
• Restricciones técnicas o de negocio

Artefacto verificable: El documento de especificación en sí mismo. Puede ser un markdown estructurado, un modelo de datos anotado, o un conjunto de historias de usuario escritas con precisión.

Verificación: ¿Podría alguien que nunca vio esto construirlo solo con el spec? Si la respuesta es "no", el spec no está listo.

Fase 2: Plan (Planificación)

A partir del spec, diseñas cómo construirlo. Aquí:

• Desglosás el spec en tareas accionables
• Asignas responsabilidades (humanos o IA)
• Estimás esfuerzo y dependencias
• Definis qué herramientas usarás y por qué
• Planificás verificación incremental

Artefacto verificable: Un plan de ejecución trazable. Cada tarea conectada con su sección del spec, cada entregable con su criterio de aceptación.

Verificación: ¿Está claro cómo cada tarea cierra un requisito del spec? ¿Falta algún requisito? ¿Hay bloques que necesitan resolverse antes de avanzar?

Fase 3: Build (Construcción)

Ahora construyes. Con el spec y plan como brújula, la IA puede acelerar sin perder rumbo:

• Generas componentes, servicios, queries basados en el spec
• Cada construcción es verificable contra criterios específicos
• Los tests se escriben en paralelo, guiados por el spec
• Cada decisión de diseño queda documentada (por qué elegiste arquitectura A sobre B)

Artefacto verificable: Código que pasa los tests. Pero más importante: un registro de decisiones. Cada commit explica qué requisito del spec cierra.

Verificación: ¿El código refleja el spec? ¿Paso los tests? ¿Puedo rastrear cada línea de código hasta su requisito?

Fase 4: Operate (Operación)

En producción, el spec sigue siendo tu aliado:

• Cuando algo falla, vuelves al spec: ¿Era comportamiento esperado?
• Cuando necesitas escalar, el spec te dice qué no puede cambiar
• Cuando llegan nuevos requisitos, el spec viejo te muestra qué era la línea base
• Cuando nuevas personas se suman, el spec es su punto de entrada

Artefacto verificable: Métricas de operación conectadas con criterios del spec. SLOs, alerts, dashboards que miden exactamente lo que el spec prometió.

Verificación: ¿El sistema se comporta en producción como el spec lo definía? ¿Hay divergencias? ¿Aprendiste algo que requiera actualizar el spec para la próxima versión?

Por qué esto multiplica la trazabilidad

Cada decisión queda anclada en el spec. Eso significa:

Trazabilidad hacia atrás: Ves un bug en producción → verificas el spec → entiendes si fue mala interpretación, cambio de requisito, o fallo genuino.

Trazabilidad hacia adelante: Necesitas agregar una funcionalidad → consultas el spec existente → entiendes qué no puedes romper.

Trazabilidad transversal: Diferentes equipos trabajan en paralelo pero todos contra el mismo spec. No hay sorpresas de integración porque todos construyeron lo mismo.

La IA amplifica esto. Genera código más rápido, pero de un spec claro. Propone variaciones, pero siempre dentro de lo especificado. Detecta inconsistencias con mayor rapidez porque no está navegando por intuición.

La práctica en Galaxy

En Galaxy, especificar es el trabajo. No es un trámite. Es donde sucede el pensamiento real, la alineación de equipo, el diseño de calidad.

Cuando escribimos el spec:

• Nos hacemos preguntas incómodas juntos
• Discutimos trade-offs explícitamente
• Documentamos por qué elegimos un enfoque sobre otro
• Creamos un acuerdo registrado antes de que la máquina se ponga a trabajar

Luego, cuando la IA acelera la construcción, lo hace dentro de límites claros. No es un blanco móvil. No es "a ver qué se te ocurre". Es "construye exactamente esto, y veremos juntos si lo que construiste cumple". 💡

Cómo saber si tu spec está listo

Antes de pasar a Plan:

• ¿Alguien sin contexto técnico entiende qué se construirá?
• ¿Los criterios de aceptación son verificables sin ambigüedad?
• ¿Están documentados los casos límite?
• ¿Está claro cuál es el alcance y cuál no lo es?
• ¿Hay decisiones de diseño que necesitan ratificación técnica?

Si no puedes responder "sí" a todas, el spec no está listo. Y eso es bueno: mejor darte cuenta ahora que después de construir.