← Volver al listado de tecnologías ← Índice de OpenSpec

Instalacion y Estructura del Proyecto

24 de febrero de 2025 Por: Artiko

openspecinstalacionestructuraconfiguracion

Instalacion y Estructura del Proyecto

Instalar OpenSpec

OpenSpec se instala globalmente con npm:

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

Verifica la instalacion:

openspec --version

Crear el proyecto Kanban

Primero creamos la estructura basica del proyecto:

mkdir kanban-openspec && cd kanban-openspec
npm init -y

Ahora inicializamos OpenSpec dentro del proyecto:

openspec init

Esto genera la estructura completa de OpenSpec y configura las integraciones con tu herramienta de IA.

Referencia: `openspec init [path]`

Opcion	Descripcion
`--tools <lista>`	Herramientas de IA. Acepta `all`, `none` o lista separada por comas
`--force`	Limpia archivos legacy sin preguntar
`--profile <perfil>`	`core` (default) o `custom` (expanded workflow)

Herramientas soportadas (--tools): amazon-q, antigravity, auggie, claude, cline, codex, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, kilocode, kiro, opencode, pi, qoder, qwen, roocode, trae, windsurf

openspec init                         # Interactivo
openspec init --tools claude,cursor   # Solo Claude y Cursor
openspec init --tools all --force     # Todas las herramientas, sin prompts
openspec init --profile custom        # Perfil expandido

Estructura generada

Despues de openspec init, tu proyecto tiene esta estructura:

kanban-openspec/
├── openspec/
│   ├── specs/           # Fuente de verdad del sistema
│   ├── changes/         # Cambios propuestos (aislados)
│   └── config.yaml      # Configuracion del proyecto
├── .claude/             # (Si usas Claude Code)
│   ├── commands/opsx/   # Slash commands: propose, explore, apply, archive
│   └── skills/          # Skills de OpenSpec
└── package.json         # Tu proyecto existente

Nota: La estructura de .claude/ se genera automaticamente para Claude Code. Para otros IDEs (Cursor, Copilot, Windsurf), OpenSpec genera los archivos de configuracion correspondientes segun la herramienta detectada o especificada con --tools.

specs/: La fuente de verdad

El directorio specs/ contiene las especificaciones actuales del sistema. Aqui se describe lo que el sistema ya hace, no lo que queremos que haga.

openspec/specs/
└── <dominio>/
    └── spec.md

Las specs usan formato Gherkin (GIVEN/WHEN/THEN):

Feature: Board Management

  Scenario: Create a new board
    GIVEN the user is authenticated
    WHEN the user creates a board with name "Sprint 1"
    THEN the system creates a board with 3 default columns
    AND the board appears in the user's board list

Inicialmente este directorio esta vacio. Se va llenando conforme completas ciclos de cambio.

changes/: Cambios aislados

El directorio changes/ es donde ocurre la magia. Cada cambio propuesto tiene su propio subdirectorio con artefactos independientes:

openspec/changes/
└── add-board-model/
    ├── .openspec.yaml   # Metadata del cambio (schema, estado)
    ├── proposal.md      # Descripcion del cambio
    ├── design.md        # Decisiones de arquitectura
    ├── tasks.md         # Lista de tareas concretas
    └── specs/           # Delta specs que este cambio introduce
        └── board-model/
            └── spec.md

Este aislamiento es clave: puedes tener multiples cambios en paralelo sin que interfieran entre si.

Perfiles: Core vs Custom

OpenSpec ofrece dos perfiles que controlan que slash commands estan disponibles:

Core (por defecto)

4 comandos esenciales para el flujo rapido:

Comando	Funcion
`/opsx:explore`	Explorar ideas sin crear artefactos
`/opsx:propose`	Crear cambio y generar todos los artefactos
`/opsx:apply`	Implementar tareas secuencialmente
`/opsx:archive`	Archivar cambio y fusionar specs

Custom / Expanded (opcional)

El perfil custom (tambien llamado “expanded workflow” en la documentacion oficial) agrega 7 comandos adicionales para control granular:

Comando	Funcion
`/opsx:new`	Crear solo el scaffold del cambio
`/opsx:continue`	Generar un artefacto a la vez
`/opsx:ff`	Fast-forward: generar todos los artefactos
`/opsx:verify`	Validar implementacion contra specs
`/opsx:sync`	Fusionar delta specs antes de archivar
`/opsx:bulk-archive`	Archivar multiples cambios a la vez
`/opsx:onboard`	Tutorial guiado con tu codebase real

Para activar el perfil Custom/Expanded:

openspec config profile
openspec update

En este tutorial usaremos el perfil Core para los primeros capitulos y exploraremos el Expanded en el capitulo 5.

Comandos CLI

OpenSpec ofrece comandos de terminal que complementan los slash commands. La mayoria soportan --json para uso programatico por agentes de IA.

Navegacion

Comando	Opciones clave	Descripcion
`openspec list`	`--specs`, `--changes`, `--sort <order>`, `--json`	Lista cambios o specs
`openspec show [nombre]`	`--type <change\|spec>`, `--json`, `--deltas-only`	Detalles de un cambio o spec
`openspec view`	(ninguna)	Dashboard interactivo en terminal

Workflow

Comando	Opciones clave	Descripcion
`openspec status`	`--change <id>`, `--schema <name>`, `--json`	Estado de artefactos de un cambio
`openspec instructions [artefacto]`	`--change <id>`, `--schema <name>`, `--json`	Instrucciones enriquecidas para la IA
`openspec validate [nombre]`	`--all`, `--changes`, `--specs`, `--strict`, `--json`	Verifica formato de specs y cambios
`openspec archive [nombre]`	`--yes`, `--skip-specs`, `--no-validate`	Archiva un cambio y fusiona specs

Configuracion

Comando	Opciones clave	Descripcion
`openspec update [path]`	`--force`	Regenera instrucciones tras upgrade
`openspec config profile [preset]`	(interactivo)	Cambia entre Core y Custom
`openspec config list`	`--json`	Muestra configuracion actual
`openspec schemas`	`--json`	Lista schemas de workflow
`openspec schema fork <base> [nombre]`	`--force`, `--json`	Crea schema custom basado en otro
`openspec schema init <nombre>`	`--artifacts <lista>`, `--default`	Crea schema nuevo
`openspec templates`	`--schema <name>`, `--json`	Muestra paths de templates

config.yaml

El archivo openspec/config.yaml permite configurar el contexto del proyecto y reglas por artefacto:

# Contexto del proyecto (la IA lo recibe al generar artefactos)
context: |
  Este es un proyecto TypeScript con React en el frontend.
  El backend usa Express con Drizzle ORM y PostgreSQL.
  Idioma: Espanol. Todos los artefactos en espanol.

# Reglas por artefacto (restricciones adicionales)
rules:
  proposal: |
    Mantener proposals bajo 500 palabras.
    Enfocarse en el "por que", no en el "como".
  specs: |
    Usar formato Given/When/Then para todos los escenarios.
  tasks: |
    Maximo 10 tareas por cambio.

El campo context es especialmente importante: es lo que OpenSpec le envia a la IA via openspec instructions para que los artefactos se alineen con tu proyecto. Es complementario a CLAUDE.md (que es especifico de Claude Code).

Sintaxis segun herramienta

Los slash commands varian ligeramente segun la herramienta de IA:

Herramienta	Sintaxis	Ejemplo
Claude Code	`/opsx:comando`	`/opsx:propose`
Cursor	`/opsx-comando`	`/opsx-propose`
Copilot (IDE)	`/opsx-comando`	`/opsx-propose`
Windsurf	`/opsx-comando`	`/opsx-propose`
Trae	Skill-based	`/openspec-propose`

En este tutorial usaremos la sintaxis de Claude Code (/opsx:comando).

Verificacion rapida

Para confirmar que todo esta listo:

# Ver la estructura generada
ls -la openspec/

# Listar cambios activos (deberia estar vacio)
openspec list

# Ver el dashboard interactivo
openspec view

Resumen

OpenSpec se instala con npm install -g @fission-ai/openspec@latest
openspec init genera toda la estructura y configura tu IDE automaticamente
specs/: Fuente de verdad del sistema actual (formato Gherkin)
changes/: Cambios propuestos, cada uno aislado en su directorio
Perfil Core: 4 comandos esenciales (explore, propose, apply, archive)
Perfil Custom/Expanded: 11 comandos para control granular
openspec view ofrece un dashboard interactivo del proyecto

Capitulo 1: Introduccion a OpenSpec y SDD | Siguiente -> Capitulo 3: Configurando el Contexto

Instalacion y Estructura del Proyecto

Instalacion y Estructura del Proyecto

Instalar OpenSpec

Crear el proyecto Kanban

Referencia: openspec init [path]

Estructura generada

specs/: La fuente de verdad

changes/: Cambios aislados

Perfiles: Core vs Custom

Core (por defecto)

Custom / Expanded (opcional)

Comandos CLI

Navegacion

Workflow

Configuracion

config.yaml

Sintaxis segun herramienta

Verificacion rapida

Resumen

Referencia: `openspec init [path]`