SDD#OpenSpec#Spec-Driven Development#AI Agents#Architecture#TypeScript

Spec-Driven Development, el fin del 'Prompt-and-Pray'.

Antonio Pérez
14 min de lectura
Spec-Driven Development, el fin del 'Prompt-and-Pray'.

La tarde del viernes en que el vibe coding se nos fue de las manos

Imagina la escena. Es viernes a las cuatro de la tarde y estás construyendo PayFlow, una plataforma de pagos y gestión de pedidos en TypeScript. Solo te falta una pieza para cerrar el sprint, proteger los endpoints de cobros con autenticación JWT. Abres tu asistente de código en la terminal, llámese Claude Code, Codex u OpenCode, y le lanzas una instrucción rápida y confiada.

"Añade un sistema de autenticación con JWT a PayFlow y actualiza los endpoints de usuarios y pagos."

Durante los primeros dos minutos todo parece magia. El agente lee un par de archivos, empieza a escupir código a toda velocidad, crea middlewares, toca seis ficheros distintos y, cuando termina, te saluda con un entusiasta "¡Listo! Autenticación implementada."

Pero entonces abres el git diff y empieza el sudor frío.

  1. Decisiones que nadie aprobó. El modelo ha decidido por su cuenta guardar los tokens de refresco en memoria local en lugar de usar la base de datos del proyecto, y ha inventado un formato de error HTTP que no coincide con el resto de tu API.
  2. Amnesia entre sesiones. Si cierras la terminal o la ventana de contexto se compacta, nadie en el equipo, ni siquiera el propio agente mañana por la mañana, recordará por qué eligió esa librería de firmado o qué casos límite dejó fuera.
  3. Roturas silenciosas. El asistente jura que todo funciona, pero ha introducido una dependencia circular entre el módulo de usuarios y el de pagos, y ha modificado rutas públicas sin escribir ni una sola prueba que lo respalde.

En mis artículos anteriores sobre LangChain y LangGraph ya vimos este mismo problema desde el lado del runtime. Reemplazar el viejo AgentExecutor por grafos explícitos nació de la necesidad de sacar el razonamiento de una caja negra impredecible. Cuando usamos la IA para escribir nuestro propio software, el problema es idéntico, pero con consecuencias más caras. A esa práctica de lanzar un deseo en prosa libre y cruzar los dedos la llamamos "Prompt-and-Pray" (o vibe coding).

Y aquí viene la verdad incómoda. Cambiar a un modelo más caro o más nuevo no resuelve el problema. Un modelo de lenguaje no falla porque sea "tonto", sino porque le pedimos que improvise arquitectura, requisitos de negocio y código de producción al mismo tiempo en un chat efímero. La solución no está dentro del modelo, sino en lo que construimos a su alrededor, el arnés (harness) y los contratos previos.

En esta primera entrega de la serie inauguramos el viaje por Spec-Driven Development (SDD) con OpenSpec, construyendo paso a paso las bases sobre nuestro proyecto PayFlow. En esta entrega veremos cuatro pilares.

  1. Qué es realmente el harness engineering. Por qué separar el motor (el LLM) del chasis que lo gobierna cambia por completo la fiabilidad del desarrollo asistido por IA.
  2. Los cuatro artefactos antes del código. Cómo OpenSpec obliga a pactar el porqué, el qué, el cómo y el plan en disco antes de tocar src/.
  3. Anatomía de un repositorio OpenSpec. Cómo se organizan las especificaciones maestras, los cambios aislados y el historial auditable.
  4. La tríada humano, agente y CLI. Cómo un contrato --json estricto evita que el asistente alucine sobre el estado del proyecto.

El modelo mental, el motor y el arnés (harness)

Para entender por qué necesitamos OpenSpec, piensa en un coche de Fórmula 1. El modelo de lenguaje (Claude, GPT, Gemini) es el motor. Tiene una potencia descomunal y puede generar cientos de líneas por minuto, pero por sí solo no sabe dónde está la pista ni cuándo frenar antes de una curva. Si sueltas un motor de 1.000 caballos sin chasis, dirección ni frenos, te estrellas en la primera esquina.

En ingeniería con IA, ese chasis, esa dirección y esos frenos son el arnés (harness), el conjunto de archivos estructurados, reglas deterministas y herramientas de verificación que rodean al modelo para encauzar su potencia.

Diagrama
Renderizando diagrama...

Qué está pasando en este diagrama

Observa la diferencia estructural entre ambos caminos.

  • En el enfoque tradicional (Prompt-and-Pray). No existe ningún punto de control entre tu frase en el chat y los archivos de producción en src/. Cuando detectas que el modelo asumió mal una regla de negocio de PayFlow, ya tienes 400 líneas mezcladas en seis archivos y te cuesta más depurarlas que haberlas escrito tú desde cero.
  • En el paradigma OpenSpec SDD. Se introduce una aduana declarativa antes de escribir código. Con un comando como /opsx:propose, el agente no toca src/, sino que redacta cuatro documentos en Markdown versionados dentro del repositorio. Tú los revisas con un simple git diff en menos de dos minutos. Si algo no cuadra, se corrige en el plano antes de levantar los muros.

Para que ese plano no sea un ensayo literario ambiguo, OpenSpec exige articular exactamente cuatro dimensiones.

  1. El porqué (proposal.md). El problema de negocio y los límites del cambio. En PayFlow, aquí dejamos claro que queremos proteger las rutas de pago con JWT, y explicitamos qué queda fuera (por ejemplo, que el login social con Google no entra todavía).
  2. El qué (specs/). El contrato funcional observable. No dice qué librería usar, sino qué debe pasar cuando un usuario envía un token caducado o sin cabecera, redactado con escenarios estructurados WHEN / THEN.
  3. El cómo (design.md). La arquitectura técnica elegida. Aquí decidimos si usamos jose o jsonwebtoken, cómo modelamos los tipos en TypeScript y qué secuencia de llamadas sigue cada petición.
  4. El plan (tasks.md). Un checklist de subtareas atómicas y verificables. Es la hoja de ruta que el agente irá marcando de [ ] a [x] conforme implemente y pruebe cada pieza.

Anatomía de un repositorio OpenSpec

Una de las mayores preocupaciones cuando un equipo evalúa una herramienta nueva es cuánto invade su proyecto actual. La respuesta con OpenSpec es directa, cero invasión en tu código fuente. No tienes que importar ninguna librería en package.json ni cambiar cómo compilas TypeScript, Go o Python. Todo el arnés vive aislado en la carpeta openspec/ en la raíz de tu repositorio.

text
payflow-api/
├── openspec/
│   ├── config.yaml          # Constitución del proyecto (stack, arquitectura, reglas)
│   ├── changes/             # Cambios activos en vuelo (aislados del código maestro)
│   │   ├── add-jwt-auth/
│   │   │   ├── .openspec.yaml  # Metadatos del cambio (esquema activo y flags)
│   │   │   ├── proposal.md     # Motivación, alcance e impacto
│   │   │   ├── design.md       # Decisiones técnicas y diagramas
│   │   │   ├── tasks.md        # Lista de tareas atómicas [-] rastreadas por el CLI
│   │   │   └── specs/          # Especificaciones delta de este cambio
│   │   │       └── auth/
│   │   │           └── spec.md
│   │   └── archive/         # Historial inmutable de cambios cerrados (YYYY-MM-DD-*)
│   ├── specs/               # Especificaciones maestras (fuente de verdad viva del sistema)
│   │   └── auth/
│   │       └── spec.md
│   └── schemas/             # (Opcional) Flujos de trabajo personalizados
├── .agent/skills/           # Habilidades inyectadas para Antigravity / Claude / Cursor
└── src/                     # Tu código de aplicación (intacto hasta /opsx:apply)

Desgranando cada carpeta clave

  • openspec/config.yaml (la constitución). Es el archivo donde fijas las reglas inmutables del proyecto. Por ejemplo, que PayFlow usa TypeScript estricto, Vitest para tests y Clean Architecture. Cada vez que el agente vaya a planificar o programar, OpenSpec le inyectará estas directrices automáticamente.
  • openspec/changes/ (el taller de trabajo). Cada iniciativa vive en su propia subcarpeta (add-jwt-auth/). Mientras estás diseñando o programando, las especificaciones maestras del sistema no se ensucian con borradores a medio hacer.
  • openspec/specs/ (la fuente de verdad viva). Representa lo que PayFlow hace hoy en producción. Es el mapa canónico que tanto un ingeniero recién llegado como un agente de IA pueden leer para entender el sistema sin tener que hacer ingeniería inversa sobre miles de líneas de código.
  • openspec/changes/archive/ (la caja negra histórica). Cuando terminas un cambio, su carpeta se mueve aquí con fecha (2026-11-12-add-jwt-auth). Si dentro de ocho meses alguien se pregunta por qué la expiración de los tokens se fijó en 15 minutos, la respuesta y el contexto siguen intactos en el repositorio.

La tríada de ejecución, humano, agente y CLI

Mucha gente piensa que OpenSpec es un conjunto de prompts bonitos en Markdown. Si fuera solo eso, el agente seguiría cometiendo errores, olvidaría qué archivo va primero, crearía carpetas con nombres inventados o marcaría tareas terminadas sin haber comprobado nada.

Por eso OpenSpec funciona como una tríada donde cada actor tiene un papel muy claro. Tú decides la intención y apruebas el plan, el agente razona y escribe, y la CLI de OpenSpec actúa como el árbitro determinista que valida el estado real en disco.

Diagrama
Renderizando diagrama...

Qué ocurre bajo el capó paso a paso

Fíjate en los pasos 2 al 5 del diagrama. Cuando tú escribes /opsx:propose en tu asistente.

  1. El agente no crea carpetas a mano. Invoca openspec new change add-jwt-auth. Así nos aseguramos de que el directorio nace con su archivo .openspec.yaml válido y en la ruta correcta.
  2. El agente pide instrucciones a la CLI. Ejecuta openspec instructions proposal --change add-jwt-auth --json. La CLI lee config.yaml, carga la plantilla oficial de proposal.md y le devuelve al modelo un paquete exacto con lo que debe redactar y las restricciones que debe respetar.
  3. Separación estricta entre modo humano y modo máquina (--json). Este detalle es oro puro en harness engineering. Cuando tú ejecutas un comando en la terminal, quieres tablas bonitas, colores y spinners de carga. Pero si un agente intenta leer esa salida decorada, los códigos de color ANSI o un texto inesperado pueden romper su análisis. Por contrato (agent-contract), al pasar --json, OpenSpec emite exclusivamente un documento JSON válido por stdout y envía cualquier aviso o progreso auxiliar a stderr. El modelo nunca tiene que "adivinar" si algo falló, lee "valid": true o "valid": false y actúa en consecuencia.

Dos velocidades de trabajo, perfil core vs. expanded

No todos los cambios en PayFlow tienen el mismo nivel de riesgo. Añadir un botón en el panel interno no requiere la misma ceremonia que rediseñar la pasarela de cobros. Por eso, al inicializar OpenSpec, puedes elegir entre dos perfiles operativos.

  • Perfil core (ágil por defecto). Pensado para el 80% de tu día a día. Concentra todo el flujo en tres comandos esenciales, /opsx:propose (genera toda la planificación de golpe), /opsx:apply (implementa el checklist) y /opsx:archive (consolida las especificaciones en openspec/specs/ y archiva el cambio).
  • Perfil expanded (control granular). Pensado para cambios arquitectónicos delicados o equipos con revisiones estrictas. Desdobla la planificación en pasos individuales (/opsx:new para crear solo el cascarón, /opsx:continue para avanzar artefacto por artefacto revisando cada uno) e incorpora /opsx:verify para auditar formalmente el código contra los escenarios antes de archivar.

Lo interesante es que ambos perfiles trabajan sobre los mismos archivos en disco. Puedes empezar un cambio con el flujo ágil y, si la complejidad crece, pasar a auditarlo paso a paso sin migrar nada.


Laboratorio práctico, tu primer arnés en PayFlow

Vamos a llevar la teoría a la terminal para comprobar cómo se inicializa OpenSpec en un proyecto real y qué ve exactamente el agente cuando inspecciona el repositorio.

Paso 1. Comprobar la CLI e inicializar el entorno

Abre una terminal en la raíz de tu proyecto de pruebas (imaginemos que es el repositorio payflow-api) y verifica que tienes la herramienta instalada antes de inicializar el arnés para tu asistente.

bash
# 1. Confirmar que la CLI de OpenSpec responde correctamente
openspec --version

# 2. Inicializar OpenSpec e instalar las skills para tu asistente (ej. claude, cursor, antigravity)
openspec init --tools claude

Qué acaba de ocurrir en tu disco. El comando openspec init no ha tocado ni un solo archivo dentro de src/. Lo que ha hecho es crear la carpeta openspec/ con sus subdirectorios vacíos (changes/, specs/), generar un openspec/config.yaml base comentado y copiar las definiciones de los comandos /opsx:* dentro de la configuración de tu asistente para que sepa interactuar con la CLI.

Paso 2. Consultar el estado del proyecto como lo hace el agente

Ahora ejecuta el validador en modo máquina para ver exactamente la respuesta que recibe tu asistente de IA antes de empezar a trabajar.

bash
openspec validate --json

La terminal imprimirá un bloque JSON limpio y predecible como este.

json
{
  "items": [
    {
      "id": "init-check",
      "type": "project",
      "valid": true,
      "issues": []
    }
  ],
  "summary": {
    "totals": { "items": 1, "passed": 1, "failed": 0 }
  },
  "version": "1.0"
}

Fíjate en la potencia de esta salida. No hay prosa ambigua ni conjeturas. El bloque summary.totals le entrega al agente un veredicto binario ("failed": 0) y una lista issues donde, si algún archivo tuviera un error de formato, aparecería el diagnóstico exacto para corregirlo antes de seguir adelante.


Autoevaluación

Pon a prueba lo que acabas de aprender antes de avanzar al siguiente capítulo.

  1. ¿En qué se diferencia fundamentalmente el Spec-Driven Development (SDD) del prompt engineering tradicional? El prompt engineering optimiza un mensaje puntual en una sesión de chat efímera que se pierde al cerrar la ventana. Spec-Driven Development construye un arnés de ingeniería duradero en el repositorio mediante cuatro artefactos versionados (proposal, specs, design, tasks) que humano y agente acuerdan y revisan mediante git diff antes de escribir una sola línea de código en producción.
  2. ¿Por qué OpenSpec separa openspec/specs/ de openspec/changes/? Porque openspec/specs/ es la fuente de verdad viva de lo que el sistema hace hoy en producción, mientras que openspec/changes/<id>/ actúa como un taller aislado para cada cambio en curso. Así puedes planificar e iterar funcionalidades nuevas sin contaminar ni corromper la documentación maestra hasta que el trabajo esté validado.
  3. ¿Por qué el contrato --json de la CLI separa estrictamente stdout de stderr? Porque los agentes de IA consumen la salida estándar (stdout) mediante parsers estructurados. Si la CLI imprimiera spinners, barras de progreso o mensajes decorativos en stdout, rompería el JSON y obligaría al modelo a adivinar el estado del repositorio. Canalizando todo el ruido humano a stderr, stdout queda reservado para un único JSON determinista.

En el próximo artículo...

Ya tenemos el arnés montado en PayFlow y sabemos por qué necesitamos pactar contratos antes de programar. Pero aquí suele saltar la alarma de cualquier ingeniero con experiencia, "¿Tener que definir propuesta, especificaciones, diseño y tareas antes de programar no es volver a la burocracia rígida del modelo en cascada (Waterfall)?"

En la segunda entrega desmontaremos ese mito explorando La anatomía de un cambio y el grafo DAG de artefactos. Veremos cómo OpenSpec modela las dependencias como habilitadores y no como puertas cerradas, y aprenderemos la gramática exacta con la que debemos redactar requisitos para que un LLM nunca malinterprete un caso de negocio.