TIP
GitHub: https://github.com/Fission-AI/OpenSpec · Licencia open source MIT · Node.js 20.19.0+
Nivel inicial | ~15 minutos | dominarás los conceptos clave de OpenSpec (Delta Specs, grafo de dependencias de Artifact), el proceso de inicialización, el flujo de trabajo OPSX (propose → apply → archive) y la gestión en paralelo de múltiples cambios
Descripción del proyecto
Primero, admitamos un hecho: cuando usas un asistente de programación con IA, ¿te ha pasado alguna vez esto? Conversando, la IA termina cambiando también cosas que no querías modificar; o cambias el contexto de la conversación y la IA olvida por completo lo que se dijo antes; o cada vez que le pides que escriba una nueva funcionalidad, lo que entrega no se parece en absoluto a lo que realmente necesitabas.
Estos problemas no es que la IA sea “demasiado torpe”, sino que** las necesidades nunca se han “firmado y sellado”**. Solo existen dentro del historial de la conversación; el margen de improvisación de la IA es demasiado amplio.
OpenSpec lo hace de forma muy simple: antes de escribir código, alinea a las personas y a la IA en un documento de especificaciones, y luego la IA actúa siguiendo esa especificación. Lo desarrolla Fission-AI, admite 20+ herramientas de programación con IA (Claude Code, Cursor, Windsurf, etc.) y, en esencia, añade una capa ligera de gestión de especificaciones para asistentes de programación.
Perfil de público objetivo
- Desarrolladores que usan asistentes de programación con IA en el día a día
- Ingenieros que, en trabajo en equipo, sufren porque las personas y la IA no entienden las necesidades de la misma manera
- Product managers que quieren que la salida de la IA sea más controlable
Dependencias y entorno clave
- Node.js 20.19.0+
TIP
Para usuarios de macOS, se recomienda gestionar versiones de Node con nvm y cambiar en un solo comando: nvm install 20 && nvm use 20
Árbol de estructura completa del proyecto
openspec/
├── specs/ # Especificaciones de comportamiento del sistema actual (divididas por dominio)
│ └── <domain>/spec.md
├── changes/ # Propuestas de cambio (un archivo por carpeta de cambio)
│ ├── <change-name>/
│ │ ├── proposal.md # Motivación + alcance + enfoque
│ │ ├── specs/ # Delta Specs (ADDED/MODIFIED/REMOVED)
│ │ │ └── <domain>/spec.md
│ │ ├── design.md # Diseño técnico
│ │ └── tasks.md # Lista de verificación para la implementación
│ └── archive/ # Historial archivado
└── config.yaml # Configuración del proyecto (opcional)
Paso a paso
Paso 1: Instalar OpenSpec globalmente
npm install -g @fission-ai/openspec@latest
Una vez instalado, verifica:
openspec --version
# 1.2.0
WARNING
La versión de Node.js debe ser >= 20.19.0; con versiones inferiores aparecerá un SyntaxError. Si te ocurre, primero actualiza Node: nvm install 20 && nvm use 20
Paso 2: Inicializar el proyecto
Entra en el directorio de tu proyecto y ejecuta el comando de inicialización:
cd your-project
openspec init
Este comando hace tres cosas:
- Crea la estructura de directorios
openspec/ - Genera los archivos de habilidades bajo
.claude/(para que el asistente de IA reconozca los comandos/opsx:*) - Te pregunta si deseas crear el archivo de configuración del proyecto
config.yaml(opcional; sirve para inyectar contexto del proyecto)
Cuando termine la inicialización, tu proyecto tendrá estos directorios:
openspec/
├── specs/ # Especificaciones del comportamiento actual del sistema (carpeta vacía; espera ser completada)
├── changes/ # Carpeta de propuestas de cambio (carpeta vacía)
└── config.yaml # Configuración del proyecto (si elegiste crearla)
Paso 3: Habilitar el flujo de trabajo ampliado de OPSX
La OpenSpec recién instalada viene por defecto en modo core: solo tiene 4 comandos (propose, explore, apply, archive). Si quieres usar el flujo completo (incluyendo new, continue, ff, verify, bulk-archive, etc.), ejecuta:
openspec config profile
# elige expanded o full
openspec update
openspec update regenerará los archivos de habilidades de IA según el perfil que elijas, para que puedas usar más comandos en tus conversaciones con la IA.
TIP
¿No estás seguro de qué profile tienes ahora? Ejecuta openspec config show.
Paso 4: Crear tu primer cambio: añadir modo oscuro
Ahora haz que la IA te ayude a crear un cambio. Como ejemplo, “añadir modo oscuro a la aplicación”, díselo directamente a la IA:
/opsx:propose add-dark-mode
La IA creará automáticamente cuatro archivos de Artifact dentro de openspec/changes/add-dark-mode/:
openspec/changes/add-dark-mode/
├── proposal.md # ¿Por qué existe este cambio? ¿Alcance? ¿Enfoque?
├── specs/
│ └── ui/spec.md # Delta Specs del dominio UI
├── design.md # ¿Cómo se diseña la solución técnica?
└── tasks.md # ¿Qué hay que hacer exactamente? Lista paso a paso
proposal.md tiene este aspecto (generado automáticamente por la IA; tú y la IA pueden editarlo juntos):
# Proposal: Add Dark Mode
## Intent
El usuario solicita añadir un modo oscuro para reducir la fatiga ocular durante la noche.
## Scope
- Agregar un botón de cambio de tema en Configuración
- Soportar la detección de preferencias del sistema
- Persistir la preferencia en localStorage
## Approach
Usar variables CSS para el tema y manejar el estado con React Context.
specs/ui/spec.md es la Delta especificación clave; el formato es así:
# Delta for UI
## ADDED Requirements
### Requirement: Theme Selection
El sistema SHALL permitir a los usuarios cambiar entre temas claro y oscuro.
#### Scenario: Toggle manual
- GIVEN el usuario está en cualquier página
- WHEN el usuario hace clic en el botón de cambio de tema
- THEN el tema cambia inmediatamente y la preferencia se persiste entre sesiones
#### Scenario: Preferencia del sistema
- GIVEN el usuario no tiene una preferencia guardada
- WHEN la aplicación se carga
- THEN se utiliza la paleta de color preferida del sistema
TIP
El núcleo de las Delta Specs es el “cambio”: solo describen lo que se añade, modifica y elimina. Al archivar, estas Delta se combinan en el archivo de especificación principal.
tasks.md es la lista de verificación de implementación:
# Tasks
## 1. Infraestructura de Theme
- [ ] 1.1 Crear ThemeContext (estado light/dark)
- [ ] 1.2 Añadir definiciones de variables CSS para los colores
- [ ] 1.3 Implementar persistencia en localStorage
## 2. Componentes de UI
- [ ] 2.1 Crear el componente ThemeToggle
- [ ] 2.2 Añadir el botón de cambio en la página de Configuración
- [ ] 2.3 Añadir acceso rápido de cambio en el Header
## 3. Estilos
- [ ] 3.1 Definir paleta de colores del tema oscuro
- [ ] 3.2 Hacer que los componentes existentes usen variables CSS
Paso 5: Ejecutar tareas de implementación
Después de confirmar que el documento de especificaciones está correcto, ejecuta la implementación:
/opsx:apply
La IA revisará las tareas de tasks.md una por una: marca un visto bueno cuando complete cada una. Verás que el comportamiento de la IA cambia: ya no improvisa libremente, sino que avanza de forma estricta siguiendo tasks.md. Si durante la implementación detectas que hay un problema de diseño, puedes modificar directamente design.md y luego continuar con apply; la IA se ajustará automáticamente.
Paso 6: Verificar y archivar el cambio
Verificación (opcional, pero recomendado):
/opsx:verify
La IA comprobará tu implementación en tres dimensiones:
| Dimensión | Qué se verifica |
|---|---|
| Completeness | ¿Están completadas todas las tareas de tasks.md? ¿Cubre la especificación todos los escenarios? |
| Correctness | ¿La implementación coincide con la intención de la especificación? ¿Se manejan los casos borde? |
| Coherence | ¿Las decisiones de diseño de design.md se reflejan en el código? |
Archivo:
/opsx:archive
El archivado hace dos cosas:
- Combina las Delta Specs en la especificación principal
openspec/specs/ui/spec.md - Mueve la carpeta del cambio a
openspec/changes/archive/2026-04-11-add-dark-mode/
Cuando el archivado termina, el archivo de especificación del sistema se actualiza y obtienes un historial completo del cambio.
Paso 7: Gestión en paralelo de múltiples cambios
En desarrollo real, a menudo te interrumpen a mitad de camino para resolver otros problemas. OpenSpec admite cambios en paralelo:
# Supongamos que estás haciendo add-dark-mode, pero de repente hay que corregir un bug
/opsx:new fix-login-redirect
# Completar normalmente la corrección del bug
/opsx:ff
/opsx:apply
/opsx:archive
# Volver al trabajo de modo oscuro anterior
/opsx:apply add-dark-mode
Cuando tengas varios cambios completados, archívalos juntos:
/opsx:bulk-archive
OpenSpec detectará automáticamente los conflictos de especificación (por ejemplo, que dos cambios modifiquen specs/ui/) y los combinará en orden cronológico.
Paso 8: Personalizar el Schema
El flujo de trabajo OPSX de OpenSpec se define mediante Schema; puedes personalizar por completo los tipos de Artifact y sus relaciones de dependencia. Por ejemplo, si quieres un flujo “primero investigar, luego proponer”:
# Derivar un nuevo schema del schema predeterminado
openspec schema fork spec-driven research-first
La estructura del Schema generado será:
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.md
El grafo de dependencias correspondiente queda así:
research ──► proposal ──► tasks
En schema.yaml defines:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research]
- id: tasks
generates: tasks.md
requires: [proposal]
TIP
Si colocas el Schema en el directorio del proyecto openspec/schemas/, se controlará por versiones junto con el proyecto; así todo el equipo puede usar el mismo flujo de trabajo.
Paso 9: Resumen rápido de comandos CLI comunes
# Inicializar
openspec init
# Actualizar archivos de habilidades de IA (hay que ejecutarlo cada vez que actualices o después de cambiar de profile)
openspec update
# Ver la configuración actual
openspec config show
# Cambiar el profile del flujo de trabajo
openspec config profile
# Ver cambios activos
openspec list
# Ver detalles de un cambio
openspec show add-dark-mode
# Validar formato
openspec validate add-dark-mode
# Dashboard interactivo
openspec view
# Gestión de Schema
openspec schemas # listar schemas disponibles
openspec schema which --all # ver el origen de los schemas
openspec schema validate my-schema # validar schema
Resolución de problemas frecuentes
1. La IA no encuentra el comando /opsx:propose
Este es el problema más común. Después de ejecutar openspec init, el asistente de IA necesita recargar los archivos de habilidades. Ejecuta:
openspec update
Luego reabre la conversación. Si la IA aún no lo reconoce, revisa manualmente si existe el directorio .claude/.
2. openspec init falla por un error de versión de Node.js
node --version
# confirmar >= 20.19.0
# Si la versión es demasiado baja, actualiza con nvm
nvm install 20 && nvm use 20
3. Conflicto al combinar Delta Specs
Al ejecutar /opsx:bulk-archive, si dos cambios modifican el mismo archivo de especificación, OpenSpec lo detectará y te lo avisará. Combinar por orden cronológico es el comportamiento por defecto; si necesitas tratarlo manualmente:
# Archivar primero uno de forma individual
/opsx:archive fix-login-redirect
# Luego archivar el otro
/opsx:archive add-dark-mode
4. Fallo al cargar un Schema personalizado
Normalmente se debe a un error de sintaxis en schema.yaml. Revisa:
openspec schema validate my-schema
Errores comunes: indentación YAML incorrecta, o el campo requires del artifact hace referencia a un ID que no existe (dependencias cíclicas).
5. El formato de las especificaciones generadas por la IA no cumple los requisitos
Puedes añadir reglas en openspec/config.yaml:
rules:
specs:
- usar el formato GIVEN/WHEN/THEN para describir cada escenario
- cada Requirement debe tener al menos un Scenario
Estas reglas se inyectan en las instrucciones para la generación de especificaciones.
6. Durante /opsx:apply, la IA se salta algunas tareas
Dile directamente a la IA:
Por favor, ejecuta las tareas en el orden de tasks.md. La tarea 1.3 aún no está completada; no la saltes.
La característica fluid de OpenSpec te permite editar el Artifact en cualquier momento: modifica tasks.md y luego vuelve a ejecutar apply; la IA continuará desde donde se detuvo.
Lectura ampliada / Direcciones de nivel avanzado
Delta Specs: profundización del formato: existen tres tipos de cambio (ADDED/MODIFIED/REMOVED) con su propio significado: ADDED añade requisitos, MODIFIED reemplaza requisitos existentes y REMOVED elimina requisitos obsoletos. Dominar sus reglas de combinación es clave para aprovechar OpenSpec.
Comparación OPSX vs flujo Legacy: OpenSpec v1.x usa el flujo Legacy (/openspec:proposal), mientras que v1.2+ impulsa principalmente OPSX. La diferencia esencial es: Legacy es phase-locked (todo o nada), mientras que OPSX es fluid (cualquier Artifact se puede editar en cualquier momento).
Guía de integración de 20+ herramientas de IA: OpenSpec genera archivos de habilidades usando el directorio .claude/skills/, compatible con herramientas comunes como Claude Code, Cursor, Windsurf y Copilot. Consulta docs/supported-tools.md.
Integración con Slack en equipo: los equipos empresariales pueden contactar con [email protected] para obtener soporte en un canal de Slack dedicado; es ideal para flujos de gestión y revisión de especificaciones en escenarios de colaboración de varias personas.
Personalización profunda de la configuración del proyecto: además de context y rules, también puedes configurar por defecto un Schema mediante config.yaml e inyectar información del stack técnico del proyecto (por ejemplo, frameworks de pruebas, normas de estilo de código), para que las especificaciones generadas por la IA se ajusten mejor a tu proyecto real.