OpenSpec: Tutorial Completo

Version: Este tutorial esta actualizado para OpenSpec v1.2.0 (Febrero 2025). Si usas una version diferente, consulta la guia de migracion oficial.

Que es este tutorial

OpenSpec es un framework de Spec-Driven Development (SDD) creado por Fission AI. Su filosofia es simple: acuerda antes de construir. En lugar de escribir codigo directamente, primero defines especificaciones claras que sirven como fuente de verdad para ti y para la IA.

A diferencia de otros frameworks que asumen proyectos nuevos, OpenSpec esta disenado para codebases existentes (brownfield-first). Es ligero, se instala en segundos y genera artefactos concisos.

Que vamos a construir

A lo largo de este tutorial, construiremos un tablero Kanban (backend + frontend) como vehiculo para aprender la metodologia OpenSpec. El foco NO esta en el codigo del Kanban, sino en:

• Como proponer cambios de forma estructurada
• Como generar especificaciones que la IA pueda implementar
• Como verificar y archivar cambios completados
• Como manejar multiples cambios en paralelo

El Kanban es solo el pretexto. Lo que aprenderas es un flujo de trabajo que puedes aplicar a cualquier proyecto.

Capitulos

1. Introduccion a OpenSpec y SDD - Que problema resuelve y por que importa
2. Instalacion y Estructura del Proyecto - Setup en 5 minutos, perfiles y anatomia del directorio
3. Configurando el Contexto del Proyecto - CLAUDE.md, skills y schemas como fuente de contexto
4. Primer Cambio con Propose - Tu primera propuesta con /opsx:propose
5. Perfil Expandido: Control Granular - /opsx:new, /opsx:ff y /opsx:continue para flujos avanzados
6. Implementando con Apply - Dejar que la IA implemente segun las specs con /opsx:apply
7. Verificacion y Archivo - Validar y cerrar el ciclo con /opsx:archive
8. Iteracion: Agregando Drag and Drop - Segundo ciclo completo sobre codigo existente
9. Cambios Paralelos y Conflictos - Multiples cambios simultaneos sin caos
10. Mejores Practicas y Patrones Brownfield - Lecciones aprendidas y antipatrones
11. Roadmap y Futuro de OpenSpec - Que viene en las proximas versiones

Requisitos previos

• Node.js 20.19 o superior
• Un asistente de IA compatible (Claude Code, Cursor, Copilot, Windsurf y 20+ mas)
• Conocimientos basicos de TypeScript y React

---

Siguiente -> Capitulo 1: Introduccion a OpenSpec y SDD