OpenSpec y el desarrollo guiado por especificaciones: de una imagen a código funcional en minutos

El problema que todos conocemos

Cualquier desarrollador ha vivido esta situación: recibes una captura de pantalla, un mensaje en Slack o un correo con algo como «necesitamos un botón para exportar a Excel». Lo que sigue suele ser un ciclo de interpretaciones, idas y vueltas, código que no encaja con lo esperado y retrabajos.

El Specification-Driven Development (SDD) propone una alternativa: antes de escribir una sola línea de código, define formalmente qué hay que construir, por qué, cómo y en qué orden. Y OpenSpec es la herramienta que hace que este proceso sea práctico, rápido y compatible con tu flujo de trabajo habitual.

Qué es OpenSpec

OpenSpec es una CLI ligera que estructura el proceso de desarrollo en artefactos secuenciales. En lugar de saltar directamente al código, te guía a través de un pipeline de documentación que actúa como contrato entre la idea y la implementación.

Instalación: un solo comando

npm install -g openspec

Eso es todo. Una vez instalado, inicializas tu proyecto con openspec init y ya puedes empezar a crear cambios estructurados. Se integra de forma natural con Cursor IDE a través de skills y comandos slash, pero funciona perfectamente desde cualquier terminal.

Un caso real: «Añade un botón para exportar a Excel»

Para ilustrar el flujo completo, voy a recorrer un caso real. El punto de partida fue esta petición junto con una captura de pantalla de la aplicación:

«Necesitamos un botón que permita exportar los resultados del buscador de empleados a un fichero Excel. Debe estar junto al botón de buscar, deshabilitado hasta que haya resultados, y el Excel debe tener las mismas columnas que la tabla.»

A partir de esa imagen y esa descripción, OpenSpec generó todo el proceso.

Paso 1: Crear el cambio

openspec new change "export-results-excel"

Esto crea una carpeta openspec/changes/export-results-excel/ con el esqueleto del workflow spec-driven, que define 4 artefactos en secuencia:

proposal → design → specs → tasks

Cada artefacto desbloquea el siguiente. No puedes saltar pasos.

Paso 2: Proposal (el «por qué»)

El primer artefacto responde a la pregunta fundamental: por qué necesitamos este cambio.

A partir de la imagen suministrada, OpenSpec analizó la interfaz existente (estructura de la tabla, columnas, botones, modelo de datos) y generó una propuesta que incluye:

• Motivación: Los usuarios copian datos manualmente de la tabla, un proceso lento y propenso a errores.
• Qué cambia: Nuevo botón «Exportar a Excel», generación de fichero .xlsx en el frontend, codificación UTF-8, 11 columnas con encabezados.
• Capabilities: Se identifica una nueva capacidad data-export-excel que necesitará su propia especificación.
• Impacto: Solo frontend, sin cambios en backend. Nueva dependencia npm (xlsx).

Paso 3: Design (el «cómo»)

El segundo artefacto documenta las decisiones técnicas con sus alternativas consideradas:

Decisión	Elección	Alternativas descartadas
Librería Excel	SheetJS (~180KB)	ExcelJS (pesada), Apache POI backend (duplica lógica), CSV (problemas UTF-8)
Arquitectura	Servicio dedicado ExcelExportService	Lógica en el componente (viola responsabilidad única)
Mapeo de datos	Configuración externa de columnas	Hardcoded en el servicio (no reutilizable)
Nombre fichero	directorio_empleados_YYYYMMDD_HHmmss.xlsx	Nombre fijo (colisiones)

También documenta riesgos y mitigaciones: tamaño del bundle, volumen de datos, compatibilidad de navegadores.

Paso 4: Specs (el «qué exactamente»)

Aquí es donde el SDD brilla. Las especificaciones definen requisitos formales con escenarios verificables. Cada requisito usa el formato WHEN/THEN, lo que los convierte directamente en casos de test:

6 requisitos, 15 escenarios, entre ellos:

• El botón debe estar deshabilitado antes de buscar, durante la carga, y cuando no hay resultados.
• El fichero debe tener exactamente 11 columnas con encabezados específicos.
• La columna «Dirección Centro» debe concatenar 4 campos en un formato concreto.
• Los campos vacíos deben aparecer como celdas vacías, no como «—–«.
• El orden de exportación debe respetar el ordenamiento actual de la tabla.

Paso 5: Tasks (el desglose)

El artefacto final es el que más impresiona. A partir de la imagen original y los artefactos anteriores, OpenSpec generó un desglose de 28 tareas agrupadas en 6 bloques, cada una con checkbox para seguimiento:

1. Dependencia y configuración (2 tareas)

• Instalar la librería xlsx con npm
• Crear la interfaz ExcelColumnConfig con las propiedades header, field y transform

2. Servicio ExcelExportService (6 tareas)

• Crear el servicio con providedIn: 'root'
• Implementar el método genérico exportToExcel()
• Lógica de mapeo de encabezados y filas de datos
• Generación del fichero .xlsx con SheetJS y UTF-8
• Helper para generar timestamps en formato YYYYMMDD_HHmmss
• Gestión de valores null/undefined/vacíos

3. Integración en HomeComponent (4 tareas)

• Inyectar el servicio en el constructor
• Definir la configuración de 11 columnas
• Implementar la función transform para concatenar la dirección
• Crear el método exportarExcel()

4. Botón en la plantilla HTML (4 tareas)

• Añadir el botón en el contenedor de acciones
• Aplicar clases CSS del styleguide y el icono
• Vincular el evento click
• Controlar el estado deshabilitado con binding

5. Estilos CSS (2 tareas)

• Verificar renderizado con clases existentes
• Ajustes responsive si es necesario

6. Verificación y pruebas manuales (10 tareas)

• Verificar estado disabled al cargar, tras buscar con/sin resultados
• Verificar UTF-8, columnas, concatenación de dirección, campos vacíos
• Verificar orden de exportación, nombre del fichero, responsive

El resultado

Con los 4 artefactos generados, la implementación fue directa. Cada tarea tenía un alcance claro y verificable. El código resultante fueron solo 3 ficheros nuevos y 3 modificados, y el proyecto compiló sin errores al primer intento.

Todo el proceso, desde la imagen inicial hasta el código funcionando, se completó en una sola sesión.

Por qué funciona

1. Primero piensas, luego codificas. La propuesta y el diseño obligan a tomar decisiones antes de abrir el editor.
2. Las specs son el contrato. No hay ambigüedad sobre qué debe hacer el código. Cada escenario WHEN/THEN es un criterio de aceptación.
3. Las tareas son atómicas. Cada checkbox es completable en minutos, no en horas. Sabes exactamente cuándo has terminado.
4. Todo queda documentado. Los artefactos no son documentación que se escribe después: son el proceso mismo. Cuando otro desarrollador abra el proyecto, entenderá no solo qué se hizo, sino por qué se tomó cada decisión.

Para empezar

npm install -g openspec
cd tu-proyecto
openspec init
openspec new change "mi-primera-feature"

Cuatro comandos. Cero configuración. Y un cambio radical en cómo abordas el desarrollo.

---

OpenSpec es open source y está disponible en npm. Compatible con cualquier stack tecnológico y especialmente potente cuando se combina con Cursor IDE y asistentes de IA.