Introduccion a OpenSpec y SDD
Introduccion a OpenSpec y SDD
El problema: IA sin contexto
Si has trabajado con asistentes de IA para programar, conoces estos escenarios:
- Perdida de contexto: Le pides un cambio y la IA no recuerda las decisiones de arquitectura que tomaste ayer
- Codigo sin especificacion: La IA genera codigo que “funciona” pero no sigue tus convenciones ni tu arquitectura
- Bugs por ambiguedad: Describes algo vagamente, la IA interpreta diferente, y el resultado no es lo que esperabas
- Refactoring caotico: Cada vez que pides un cambio grande, la IA toca archivos que no deberia o rompe funcionalidad existente
El problema de fondo es que no hay una fuente de verdad compartida entre tu y la IA sobre que es el sistema, como funciona y que se espera de cada cambio.
Que es Spec-Driven Development
SDD (Spec-Driven Development) se resume en una frase:
Acuerda antes de construir.
En lugar de pedirle a la IA “agrega drag and drop al Kanban” y esperar lo mejor, SDD propone:
- Especificar que significa exactamente ese cambio
- Acordar los criterios de aceptacion antes de escribir una linea de codigo
- Implementar con la IA siguiendo esas especificaciones
- Verificar que la implementacion cumple lo acordado
No es waterfall. No necesitas un documento de 50 paginas. Es un proceso ligero e iterativo donde cada cambio tiene su propia especificacion pequena y enfocada.
Que es OpenSpec
OpenSpec es un framework de SDD creado por Fission AI, publicado bajo licencia MIT. Sus caracteristicas principales:
- Brownfield-first: Disenado para proyectos existentes, no solo greenfield
- Ligero: Se instala en menos de 5 minutos, genera ~250 lineas de artefactos por cambio
- Formato Gherkin: Las especificaciones usan GIVEN/WHEN/THEN, un formato probado en la industria
- Compatible con 40+ herramientas: Claude Code, Cursor, Copilot, Windsurf, Gemini CLI, Cline, Amazon Q, Kiro, Pi, Kimi CLI, Mistral Vibe, TRAE y mas
- CLI simple: Todo se maneja con comandos
/opsx:*
Los 4 principios de OpenSpec
| Principio | Significado |
|---|---|
| Fluido, no rigido | Acciones, no fases. No hay gates obligatorios entre pasos |
| Iterativo, no waterfall | Cambios pequenos y frecuentes, no especificaciones monoliticas |
| Simple, no complejo | Artefactos concisos (~250 lineas), no documentos de cientos de paginas |
| Brownfield-first | Funciona en proyectos existentes con codigo legado |
Comparativa: OpenSpec vs alternativas
| Aspecto | OpenSpec | BMAD | Spec-Kit |
|---|---|---|---|
| Filosofia | Brownfield-first, ligero | Greenfield-first, completo | Especificaciones formales |
| Setup time | ~5 minutos | ~30 minutos | Configuracion mas compleja |
| Ideal para | Codebases existentes | Proyectos nuevos | Proyectos con specs rigurosas |
| Output por cambio | ~250 lineas | ~800+ lineas | Variable |
| Formato specs | Gherkin (GIVEN/WHEN/THEN) | Markdown libre | Schemas tipados |
| Licencia | MIT | MIT | MIT |
El flujo de trabajo
OpenSpec ofrece dos perfiles. El Core (por defecto) incluye 6 comandos (/opsx:explore, /opsx:propose, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive), pero el flujo principal se reduce a 3 acciones:
graph LR
A[Propose] -->|/opsx:propose| B[Apply]
B -->|/opsx:apply| C[Archive]
C -->|/opsx:archive| D[Completado]Propose (Proponer)
Describes el cambio que quieres hacer. /opsx:propose crea el directorio del cambio y genera todos los artefactos de planificacion: proposal.md, design.md, tasks.md y delta specs.
Apply (Aplicar)
La IA implementa el cambio siguiendo las especificaciones generadas. No improvisa: tiene un plan claro de que hacer.
Archive (Archivar)
Una vez completado, el cambio se archiva. Las delta specs se fusionan con las specs principales y el directorio de cambio se mueve al archivo.
Para quienes necesiten mas control, existe el perfil Expandido con comandos adicionales como /opsx:new, /opsx:ff, /opsx:continue y /opsx:verify (ver capitulo 5).
Por que un Kanban como proyecto
Elegimos un tablero Kanban porque:
- Es familiar: Todos entienden que es un tablero con columnas y tarjetas
- Tiene complejidad real: CRUD, drag and drop, estado compartido, persistencia
- Permite iteracion: Podemos agregar features incrementalmente
- Backend + Frontend: Muestra como OpenSpec maneja cambios full-stack
El objetivo no es que termines con un Kanban perfecto, sino que internalices el flujo de trabajo de OpenSpec para aplicarlo a tus propios proyectos.
Requisitos previos
Antes de continuar, asegurate de tener:
- Node.js 20.19+: OpenSpec requiere esta version minima
node --version # Debe ser >= 20.19 - Un asistente de IA: Claude Code, Cursor, GitHub Copilot o cualquier herramienta compatible
- Conocimientos basicos: TypeScript, React y Express (para el proyecto Kanban)
No necesitas experiencia previa con SDD ni con OpenSpec.
Resumen
- SDD es “acuerda antes de construir”: especificar antes de implementar
- OpenSpec es un framework ligero de SDD, ideal para codebases existentes
- El flujo Core tiene 3 acciones: Propose -> Apply -> Archive
- Las especificaciones usan formato Gherkin (GIVEN/WHEN/THEN)
- Existe un perfil Expandido con comandos granulares para mayor control
- Construiremos un Kanban como vehiculo para aprender la metodologia
Indice | Siguiente -> Capitulo 2: Instalacion y Estructura del Proyecto