Instalación e Inicialización de OpenSpec: 5 Minutos para Tener tu Proyecto Listo para Especificaciones

Este artículo es práctico, sin teoría — instalar, inicializar, entender la estructura, y estás listo para avanzar.

Requisitos Previos

Necesitas Node.js 20.19.0 o posterior. Verifica tu versión:

node --version

Si la versión es suficientemente alta, continúa. De lo contrario, actualiza Node.js primero.

Instalar OpenSpec

Instalar de forma global:

npm install -g @fission-ai/openspec@latest

O si usas pnpm / yarn / bun:

pnpm add -g @fission-ai/openspec@latest
yarn global add @fission-ai/openspec@latest
bun add -g @fission-ai/openspec@latest

Verificar la instalación:

openspec --version

Si se imprime un número de versión, estás listo.

Inicializar tu Proyecto

Navega al directorio de tu proyecto:

cd tu-proyecto
openspec init

Una vez completado, aparecerá una carpeta openspec/ en tu proyecto.

Cómo Se Ve la Estructura de Directorios

openspec/
├── specs/              # Cómo se ve tu sistema ahora mismo (fuente de verdad)
│   └── <domain>/
│       └── spec.md
├── changes/            # Cada cambio pendiente (una carpeta por cambio)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta spec para este cambio
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Configuración del proyecto (opcional)

Dos directorios principales:

specs/ es la documentación actual de tu sistema — describe cómo se comporta el sistema hoy, organizado en carpetas por dominio. Puedes organizar por área de funcionalidad (auth/, payments/), por componente (api/, frontend/), o por límite de negocio — lo que mejor se adapte a cómo está estructurado tu proyecto.

changes/ contiene las modificaciones en progreso — cada funcionalidad que quieres agregar o modificar vive aquí en su propia carpeta, conteniendo su propuesta, diseño, lista de tareas y delta spec. Una vez terminado, lo archivas y el delta spec se fusiona de vuelta en specs/.

Empieza a Decirle a tu IA que Use OpenSpec

Una vez inicializado, abre tu asistente de IA (Cursor, Claude Code, Windsurf, etc.) y escribe:

/opsx:propose <lo que quieres hacer>

Por ejemplo:

/opsx:propose add-dark-mode

La IA comenzará a construir la carpeta de cambios y los artefactos relacionados para ti.

¿No estás seguro de qué hace /opsx:propose? El siguiente artículo explica primero los conceptos fundamentales, luego recorreremos el flujo de trabajo completo.

Habilitando Flujos de Trabajo Avanzados

La instalación predeterminada usa el perfil core, que incluye cuatro comandos básicos (propose, explore, apply, archive). Si quieres acceder a más comandos como /opsx:new, /opsx:ff, y /opsx:verify, puedes cambiar de perfil:

openspec config profile

Después de seleccionar un perfil, ejecuta esto en tu proyecto:

openspec update

Esto envía instrucciones de comandos actualizadas a tu IA, haciendo que los nuevos slash commands estén disponibles.

Mantener OpenSpec Actualizado

OpenSpec se mantiene activamente. Ejecuta estos dos comandos periódicamente para mantenerte al día:

npm install -g @fission-ai/openspec@latest  # Actualizar el paquete
openspec update                              # Actualizar instrucciones de comandos de IA

El entorno está listo. El siguiente artículo explica specs, changes y artifacts — los tres conceptos fundamentales. Entender estos es lo que hace que el propósito de cada comando sea claro.

Siguiente: specs, changes, artifacts: Los Tres Conceptos Fundamentales de OpenSpec