Desarrollo Guiado por Especificaciones en la Era de la IA: OpenSpec vs. GitHub Spec Kit

Durante los primeros compases de la IA generativa, la industria del software se volcó en el “vibe coding”: chatear con un modelo en una ventana abierta, aplicar cambios y ajustar código hasta que la suite de pruebas o el navegador dejasen de arrojar errores.

Para prototipos de fin de semana y scripts desechables, el vibe coding parece magia. Pero al aplicarlo sobre monolitos en producción, microservicios distribuidos o bases de código consolidadas, degenera rápidamente en un caos inmanejable. La ventana de contexto se satura de asunciones fragmentadas, las directrices arquitectónicas se ignoran en silencio, los casos límite quedan sin cobertura y nadie en el equipo llega a saber por qué se adoptó una decisión determinada.

Aquí entra en juego el Desarrollo Guiado por Especificaciones (Spec-Driven Development o SDD): el paradigma de ingeniería que sustituye las conjeturas conversacionales por contratos estructurados y ejecutables.

En esta guía desgranamos la mecánica esencial de SDD, por qué las especificaciones son el canal óptimo para alinear humanos e IA, y realizamos una comparativa técnica entre los dos frameworks abiertos de referencia: OpenSpec de Fission-AI y Spec Kit de GitHub.

---

Por Qué Fracasa el “Vibe Coding” a Escala

Para entender el auge de SDD en organizaciones técnicas punteras, primero debemos diagnosticar las flaquezas del prompt engineering improvisado:

1. Degradación de Contexto y Alucinaciones Acumuladas: Los LLMs sufren pérdida de atención a medida que el historial conversacional se dilata. Tras 20 iteraciones en una sola sesión, las restricciones iniciales se diluyen, llevando al agente a deshacer correcciones previas o introducir regresiones inadvertidas.
2. Pérdida de la Intención Arquitectónica: Cuando el código emana directamente de prompts sueltos, el razonamiento técnico queda sepultado en el historial efímero del chat. Futuros desarrolladores (y futuros agentes) no tienen forma de saber si un patrón respondió a un diseño premeditado o a un atajo improvisado por el modelo.
3. Sesgo Hacia Proyectos en Blanco (Greenfield Bias): La mayoría de herramientas destacan creando ficheros desde cero, pero flaquean en repositorios preexistentes complejos (brownfield). Sin límites acotados, los agentes alteran módulos no relacionados, vulneran convenciones o incorporan dependencias redundantes.
4. Pull Requests Inaudibles: Revisar un diff de 1.500 líneas originado por múltiples prompts es agotador. Quien revisa no puede cotejar si el código satisface los requisitos porque estos jamás fueron codificados en el repositorio.

Programación Conversacional ("Vibe Coding"):
Prompt Ambiguo ──▶ La IA Adivina la Arquitectura ──▶ Genera Código ──▶ Fallos Ocultos y Deriva

Desarrollo Guiado por Especificaciones (SDD):
Intención Humana ──▶ Especificación y Reglas ──▶ Matriz de Tareas ──▶ Ejecución Autónoma ──▶ Verificación

---

¿Qué es el Desarrollo Guiado por Especificaciones (SDD)?

Spec-Driven Development (SDD) es una metodología de ingeniería donde especificaciones estructuradas y versionadas actúan como la única fuente de verdad tanto para ingenieros humanos como para agentes autónomos de IA.

En lugar de ordenar a la IA que programe directamente, SDD fragmenta el ciclo en fases verificables:

Principios Fundamentales de SDD

1. Separación de Responsabilidades:
   • Constitución / Normas: Directrices invariables del repositorio (guías de estilo, reglas de seguridad, dependencias vetadas).
   • Intención (Qué y Por qué): Requisitos funcionales, escenarios de usuario y criterios de aceptación.
   • Arquitectura (Cómo): Diseño técnico, modelos de datos, contratos de API y delimitación de componentes.
   • Ejecución (Tareas): Una lista ordenada de tareas atómicas e incrementales.
2. Especificaciones como Documentos Vivos: Viven dentro del repositorio Git junto al código fuente. Tienen control de versiones, respetan ramas y se examinan en las Pull Requests como cualquier archivo de la aplicación.
3. Independencia del Modelo (Agent Agnosticism): Se redactan en Markdown, YAML o JSON estándar. No dependen de funciones propietarias de ningún proveedor y pueden ser consumidas por Claude Code, Cursor, GitHub Copilot, Gemini CLI, Windsurf o Aider.
4. Verificación Determinista: Cada especificación formula escenarios claros (ej. aserciones Given/When/Then) que posibilitan a los agentes y a los pipelines de CI validar de manera autónoma la exactitud de la solución.

---

Análisis Técnico: OpenSpec (Fission-AI/OpenSpec)

OpenSpec es un framework open source creado por Fission-AI, orientado específicamente a proyectos brownfield consolidados y entornos multi-agente.

                     ┌────────────────────────────────┐
                     │          openspec/             │
                     ├────────────────────────────────┤
                     │  changes/                      │
                     │    ├── add-oauth-auth/         │
                     │    │   ├── proposal.md         │
                     │    │   ├── design.md           │
                     │    │   ├── tasks.md            │
                     │    │   └── specs/              │
                     │    │       └── auth.spec.md    │
                     │  specs/                        │
                     │    └── auth.spec.md (sync)     │
                     │  archive/                      │
                     └────────────────────────────────┘

Filosofía: Delta Specs y Ciclo Centrado en Cambios

La innovación distintiva de OpenSpec son las Delta Specs (especificaciones diferenciales). En vez de forzar a documentar toda una base de código heredada de antemano, OpenSpec opera mediante “cambios” atómicos:

• Propones un cambio acotado a una funcionalidad o corrección.
• Redactas especificaciones delta que reflejan únicamente las modificaciones respecto al sistema actual.
• Al culminar la implementación y las pruebas, el cambio se consolida en la carpeta global specs/ y se traslada a archive/.

Ciclo de Comandos en OpenSpec

OpenSpec introduce el espacio de comandos /opsx::

---

Análisis Técnico: GitHub Spec Kit (github/spec-kit)

Spec Kit es el conjunto de herramientas de código abierto de GitHub para SDD, articulado sobre la CLI Python specify-cli.

                     ┌────────────────────────────────┐
                     │          .specify/             │
                     ├────────────────────────────────┤
                     │  memory/                       │
                     │    └── constitution.md         │
                     │  specs/                        │
                     │    └── api-rate-limiter/       │
                     │        ├── spec.md             │
                     │        ├── plan.md             │
                     │        └── tasks.md            │
                     │  templates/                    │
                     └────────────────────────────────┘

Filosofía: Gobernanza Constitucional y Plantillas Estructuradas

GitHub Spec Kit prioriza las Barreras Constitucionales. Antes de formular cualquier funcionalidad, el proyecto define un archivo constitution.md que fija reglas inquebrantables sobre:

• Estilo arquitectónico (ej. arquitectura hexagonal, patrones funcionales).
• Estándares de desarrollo, nomenclatura y linter.
• Umbrales de cobertura de tests y requisitos de seguridad.
• Librerías autorizadas y dependencias vetadas.

Al invocar comandos de Spec Kit, esta constitución se inyecta como contexto obligatorio, impidiendo infracciones arquitectónicas.

Flujo de Trabajo en Spec Kit

---

Tabla Comparativa: OpenSpec frente a GitHub Spec Kit

---

Cómo SDD Erradica la Contaminación de Contexto

El beneficio técnico principal de SDD radica en cómo optimiza las ventanas de atención de los modelos de lenguaje:

Interacción Conversacional Tradicional:
[Prompt 1] ──▶ [Respuesta 1] ──▶ [Prompt 2] ──▶ ... ──▶ [Prompt 20]
▲ La ventana se satura de código desfasado, errores de depuración y alucinaciones.

Desarrollo Guiado por Especificaciones:
┌─────────────────────────┐
│     constitution.md     │ (Directrices globales comprimidas ~500 tokens)
├─────────────────────────┤
│        spec.md          │ (Requisitos de la funcionalidad ~800 tokens)
├─────────────────────────┤
│        plan.md          │ (Diseño técnico del componente ~1.000 tokens)
├─────────────────────────┤
│  Tarea #4: En ejecución │ (Alcance atómico de la tarea activa ~400 tokens)
└─────────────────────────┘
▲ Cada tarea se procesa en una ventana limpia con 100% señal y 0% ruido.

En el desarrollo conversacional clásico, cada prompt arrastra el lastre de todos los turnos previos. Al prompt #15, el LLM consume el 80% de su atención en asimilar sus propios errores pasados.

En SDD, cada punto de tasks.md se acomete en un contexto aislado y conciso, logrando mayor fidelidad, ausencia de regresiones y costes de tokens predecibles.

---

5 Pautas Clave para Redactar Especificaciones que la IA Ejecute a la Perfección

1. Explicita las Restricciones No Funcionales: No asumas que el modelo inferirá tus límites de latencia o memoria. Especifica: "El bundle no debe superar los 5KB comprimidos" o "La consulta a la base de datos debe usar el índice compuesto (user_id, created_at)".
2. Utiliza Given / When / Then para Criterios de Aceptación: Frases ambiguas como “El login debe ser seguro” generan desvíos. Prefiere: “Dado un token caducado, Cuando se consulta el endpoint, Entonces devuelve HTTP 401 con código TOKEN_EXPIRED”.
3. Declara los Tipos de Error y Enums de Antemano: Define códigos de error y respuestas en la spec antes de codificar. Esto evita que la IA invente estructuras dispares.
4. Acota Tareas a Ficheros o Funciones Únicas: Una tarea como "Implementar autenticación" es inabarcable. Desgránala en "Crear utilidad de firma JWT", "Programar middleware de verificación", "Añadir rate limiting en /auth/login".
5. Exige Aprobación Humana de la Spec Antes de Codificar: Jamás consientas la generación de código productivo antes de revisar y validar proposal.md o spec.md. Enmendar un fallo en una especificación de 30 líneas toma 30 segundos; rehacer un error arquitectónico en 20 ficheros consume horas.

---

Conclusión: De Prompt Engineers a Arquitectos de Especificaciones

La consolidación del Desarrollo Guiado por Especificaciones certifica la madurez de la ingeniería de software asistida por IA.

Dejamos atrás la etapa del “prompt hacking” para adentrarnos en la figura del Arquitecto de Especificaciones:

• Los ingenieros humanos aportan la estrategia, los requerimientos de negocio y el criterio técnico.
• Las especificaciones actúan como contratos inequívocos y auditables en control de versiones.
• Los agentes de IA operan como compiladores autónomos, transformando la intención humana en software robusto, cubierto por pruebas y fácil de mantener.