OpenSpec y Claude Code: integración paso a paso del flujo OPSX
DominicodeEl lunes le pedí a Claude Code que añadiera paginación a un listado. Lo hizo bien.
El miércoles abrí una sesión nueva en el mismo proyecto y le pedí un filtro. Se inventó otra forma de paginar, distinta a la del lunes, y reescribió la que ya funcionaba.
No fue culpa del modelo. El contexto de Claude Code vive en la sesión: cierras la terminal y se evapora.
OpenSpec con Claude Code resuelve eso: lo acordado vive en archivos versionados dentro del repo y el agente los lee antes de tocar código.
Tutorial de integración OpenSpec Claude Code, paso a paso: instalación, inicialización y el flujo OPSX de principio a fin.
Aviso rápido: OpenSpec no es OpenAPI
Comparten cuatro letras y nada más.
OpenSpec es un framework open source de spec-driven development para asistentes de código, de Fission-AI. No describe endpoints REST. Si has llegado buscando Swagger, este no es tu post.
Lo que hace es meter una capa de especificación entre tú y el agente: propuesta, diseño, tareas y spec del cambio. Todo en Markdown, todo dentro del repo, todo bajo control de versiones.
Paso 1: instalar (y el error de scope que arrastran los tutoriales viejos)
npm install -g @fission-ai/openspec@latest
Fíjate bien en el scope, porque esto:
# ❌ NO es OpenSpec
npm install -g openspec
instala otro paquete distinto, sin relación con el framework. Es el fallo más repetido en tutoriales de hace unos meses, y luego pasas media hora preguntándote por qué openspec init no hace lo que dice la documentación.
Instala siempre el paquete con scope @fission-ai/.
Paso 2: inicializar OpenSpec en Claude Code
Desde la raíz del repo:
cd tu-proyecto
openspec init
El init te pregunta qué herramienta usas. Selecciona Claude Code.
Y aquí el detalle que casi nadie explica bien: para Claude Code te crea las dos cosas.
.claude/skills/openspec-*/SKILL.md ← una skill por cada acción del flujo
.claude/commands/opsx/<id>.md ← los slash commands
openspec/config.yaml ← la configuración del proyecto
Las skills las carga Claude Code solo, sin que tú hagas nada. Los comandos son la puerta de entrada manual cuando quieres disparar una fase concreta. No eliges entre unas y otros: conviven.
El config.yaml guarda además tus preferencias entre ejecuciones de init y update. Si mañana actualizas OpenSpec, no te vuelve a preguntar todo.
Paso 3: llena el config.yaml antes de pedir nada
Este paso parece opcional. No lo es.
openspec/config.yaml no es un README que el agente abre si le apetece. Su contenido se inyecta en cada petición de planificación. Va dentro del prompt, siempre.
Dedica cinco minutos a describir de verdad tres cosas: el stack real con sus versiones, las convenciones que sigues (naming, estructura de carpetas, patrón de tests) y lo que está prohibido en el proyecto — esa librería que ya migraste, ese patrón que odias.
La diferencia se nota en la primera propuesta. Con el config vacío recibes una propuesta genérica de manual. Con el config bien puesto recibes una que usa tus carpetas, tus nombres y tu forma de testear.
Un apunte honesto: no inventes claves en el YAML. Completa las que el propio init deja generadas y, si necesitas un campo que no existe, mira la doc oficial.
Es la misma lógica que trabajamos en el curso Construye con IA: el resultado de un agente depende mucho menos del prompt del momento que del contexto estable que le dejaste montado antes.
Paso 4: el flujo OPSX de principio a fin
En Claude Code los comandos van con dos puntos: /opsx:<id>. Este detalle importa y ahora verás por qué.
/opsx:explore — pensar sin comprometerte
/opsx:explore
Fase de planificación pura. Exploras el problema, discutes enfoques, descartas caminos. No genera artefactos ni te ata a nada.
Es el comando que más se omite en los tutoriales y el que más rentabilidad da. Cuando saltas directo a propose, el agente propone algo — y lo propone bien argumentado, con lo cual te lo crees. En explore es donde descubres que el problema real era otro, antes de tener cuatro archivos que revisar.
/opsx:propose — generar la propuesta
/opsx:propose añadir filtros por categoría al listado de productos
Aquí se materializa el trabajo:
openspec/changes/<nombre-del-cambio>/
├── proposal.md ← qué se va a hacer y por qué
├── design.md ← cómo, a nivel técnico
├── tasks.md ← el desglose ejecutable
└── specs/ ← la delta spec del cambio
Y ahora tu parte: leerlo. Este es el punto exacto donde el flujo funciona o no funciona. Corriges asunciones, ajustas el diseño, partes tareas demasiado grandes. Cuesta minutos ahora y ahorra horas después.
/opsx:apply — implementar contra la spec
/opsx:apply
El agente implementa tarea por tarea, referenciando la spec acordada. La diferencia con pedirle código a pelo es que ya no hay margen de interpretación.
/opsx:update y /opsx:sync — mantener la spec viva
Antes de archivar, el perfil por defecto trae dos comandos más que casi nadie menciona: /opsx:update revisa los artefactos de un cambio si algo se movió a mitad de camino, y /opsx:sync fusiona la delta spec del cambio dentro de las specs generales del proyecto, para que la spec principal quede al día sin tocarla a mano.
/opsx:archive — cerrar el cambio
/opsx:archive
Mueve el cambio a openspec/changes/archive/ y actualiza la fuente de verdad del proyecto. A partir de ahí eso ya no es un cambio pendiente: es cómo funciona tu sistema.
El perfil extendido (y dónde vive /opsx:verify)
El perfil por defecto (core) trae los seis comandos que acabas de ver: explore, propose, apply, update, sync y archive. Si necesitas control más granular, cambias de perfil:
openspec config profile
openspec update
Eso desbloquea /opsx:new, /opsx:continue, /opsx:ff, /opsx:bulk-archive, /opsx:onboard y, el que más se echa en falta, /opsx:verify: contrasta la implementación contra la spec acordada. No es un test runner, es la comprobación de que no se coló nada que nadie pidió y que no falta nada que sí se pidió.
Empieza sin el perfil extendido. Actívalo cuando el ciclo base (explore → propose → apply → archive) te sepa corto.
Delta specs: por qué esto sirve en un proyecto que ya existe
Aquí está la decisión de diseño que hace a OpenSpec usable en el mundo real.
La spec de un cambio no describe tu sistema entero. Describe solo lo que se mueve:
## ADDED Requirements
### Requirement: Filtrado por categoría
El listado DEBE permitir filtrar productos por categoría.
#### Scenario: Usuario selecciona una categoría
- WHEN el usuario selecciona la categoría "Audio"
- THEN el listado muestra solo productos de esa categoría
## MODIFIED Requirements
## REMOVED Requirements
Escenarios en Markdown plano con sintaxis WHEN/THEN. Sin Gherkin, sin herramientas extra, sin plugins.
Piensa en la alternativa: especificar entera una aplicación con tres años de historia para poder añadir un filtro. No lo hace nadie, y por eso la mayoría de intentos de SDD en brownfield mueren en la segunda semana. Con deltas, la unidad de trabajo es el cambio, no el sistema.
Si quieres el marco completo detrás de esto — cómo se escribe una spec que un agente pueda ejecutar sin rellenar huecos por su cuenta — lo desarrollo en el libro de Spec-Driven Development. Y para el reverso de la moneda, ya escribí sobre por qué una spec falla con un agente de IA.
La sintaxis cambia según la herramienta
Dato práctico que ahorra confusión cuando copias comandos de un tutorial grabado con otro editor:
| Herramienta | Sintaxis |
|---|---|
| Claude Code | /opsx:propose |
| Cursor | /opsx-propose |
| GitHub Copilot | /opsx-propose |
| Amazon Q | @opsx-propose |
| Codex | $openspec-propose |
Mismo flujo, distinto prefijo. Si el comando no autocompleta en tu editor, casi siempre es esto.
Si vienes de un tutorial de hace unos meses
El flujo pre-OPSX está muerto. Pasó de fases cerradas a acciones, y la traducción es esta:
| Antes | Ahora |
|---|---|
/openspec:proposal |
/opsx:propose |
openspec/project.md |
openspec/config.yaml |
changes/active/ |
openspec/changes/ |
Si tienes un proyecto con la estructura antigua, no lo migres a mano. Vuelve a ejecutar openspec init y deja que la herramienta reconstruya lo suyo.
Qué hacer hoy con esto
Abre un proyecto que ya tengas — uno real, con código feo dentro — y no empieces por una feature grande.
Instala, ejecuta openspec init, dedica cinco minutos de verdad al config.yaml y lanza un /opsx:explore sobre el próximo cambio pequeño que tenías pendiente. Sigue hasta /opsx:archive. Media hora, un ciclo completo.
Lo que vas a notar no es velocidad. Es que la siguiente sesión de Claude Code arranca sabiendo lo que se decidió en la anterior. Eso es lo que compras aquí.
Dos avisos para terminar. Esto no sustituye a revisar el código: sustituye a discutir el mismo diseño tres veces. Y no todo cambio merece el ciclo completo — un fix de dos líneas no necesita una propuesta, y sobre eso escribí en cuándo NO usar spec-driven development.
Si quieres ver este flujo aplicado a proyectos completos, con los casos donde se rompe y cómo se arregla, lo trabajamos dentro de Dominicode Labs.
Preguntas frecuentes
¿OpenSpec es lo mismo que OpenAPI?
No. OpenSpec es un framework open source de spec-driven development para asistentes de código, creado por Fission-AI. OpenAPI es una especificación para describir APIs REST. Comparten cuatro letras y nada más.
¿Por qué mi instalación de OpenSpec no funciona?
Lo más probable es que hayas instalado el paquete equivocado. El comando correcto es npm install -g @fission-ai/openspec@latest, con el scope @fission-ai. El paquete llamado openspec a secas es otro proyecto distinto, y es el error que arrastran muchos tutoriales antiguos.
¿OpenSpec sirve en un proyecto que ya existe o solo en proyectos nuevos?
Sirve en proyectos existentes, y esa es su mejor característica. La spec de cada cambio es una delta: solo describe lo que se añade, se modifica o se elimina, con las secciones ADDED, MODIFIED y REMOVED Requirements. No necesitas especificar tu sistema entero para empezar.
¿Se puede usar OpenSpec con Cursor o Copilot en vez de Claude Code?
Sí. El flujo es el mismo y lo que cambia es el prefijo de los comandos. Claude Code usa /opsx:propose con dos puntos, Cursor y Copilot usan /opsx-propose con guion, Amazon Q usa @opsx-propose y Codex usa $openspec-propose. Lo seleccionas al ejecutar openspec init.
¿Puedo saltarme el comando explore e ir directo a propose?
Puedes, pero es donde más gente pierde tiempo. El comando explore es la fase de planificación sin compromiso y sirve para descartar enfoques antes de generar propuesta, diseño, tareas y spec. Si vas directo a propose, acabas revisando cuatro artefactos de una solución que quizá resuelve el problema equivocado.
¿Qué hago si seguí un tutorial con el flujo antiguo de OpenSpec?
Ese flujo ya no es válido. El comando /openspec:proposal pasó a /opsx:propose, el archivo openspec/project.md pasó a openspec/config.yaml y la carpeta changes/active/ pasó a openspec/changes/. Lo más limpio es volver a ejecutar openspec init en el proyecto en lugar de renombrar archivos a mano.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.