Integrar OpenSpec con Claude Code: el flujo OPSX paso a paso
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. OpenSpec es un framework open source de spec-driven development creado por Fission-AI que guarda lo acordado — propuesta, diseño, tareas y spec — en archivos Markdown versionados dentro del repo, para que Claude Code los lea antes de tocar código. En esta guía lo instalamos, lo inicializamos con openspec init y recorremos el flujo OPSX completo sobre un proyecto que ya existe.
OpenSpec no es OpenAPI: la diferencia en una tabla
Comparten cuatro letras y nada más.
| OpenSpec | OpenAPI | |
|---|---|---|
| Qué es | Framework de spec-driven development para asistentes de código | Especificación para describir APIs REST |
| Quién lo mantiene | Fission-AI | OpenAPI Initiative (Linux Foundation) |
| Formato | Markdown dentro del repo | YAML o JSON |
| Para qué sirve | Que un agente implemente lo acordado | Que un cliente sepa llamar a tu API |
Si has llegado buscando Swagger, este no es tu post.
Cómo instalar OpenSpec para Claude Code (y el error de scope de npm)
OpenSpec se instala como CLI global. Requiere Node.js 20.19.0 o superior, y la versión actual es la 1.8.0.
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: openspec a secas es la versión 0.0.0 publicada el 9 de abril de 2019, sin relación alguna con el framework y sin una sola actualización desde entonces. Es el fallo más repetido en tutoriales, 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/.
Qué crea openspec init en un proyecto con 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.
Qué poner en openspec/config.yaml (y por qué no es opcional)
openspec/config.yaml es el archivo donde defines el schema por defecto, el contexto del proyecto y las reglas por artefacto. No es documentación que el agente abre si le apetece: es entrada del modelo. La doc oficial lo dice sin rodeos — "When generating any artifact, your context and rules are injected into the AI prompt".
Sus claves de nivel superior son cuatro:
| Clave | Para qué |
|---|---|
schema |
El schema por defecto de los artefactos |
context |
La información de tu proyecto. Aparece en todos los artefactos |
rules |
Restricciones por artefacto. Solo aparecen en el artefacto que coincide |
operations |
Guía opcional para apply y archive |
Ese matiz de context y rules importa: el contexto viaja siempre, las reglas solo cuando toca. Así que lo que quieras que el agente tenga presente en cada decisión va en context.
Dedica cinco minutos a describir de verdad tres cosas ahí: 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. El detalle de cada clave está en la doc de customization.
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.
El flujo OPSX paso a paso en Claude Code
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:archive — cerrar el cambio
/opsx:archive
Mueve el cambio a openspec/changes/archive/ y consolida lo implementado en openspec/specs/, que es la fuente de verdad del proyecto — "Specs are the source of truth — they describe how your system currently behaves". A partir de ahí eso ya no es un cambio pendiente: es cómo funciona tu sistema.
Los otros dos del perfil por defecto
/opsx:update revisa los artefactos de planificación de un cambio y los mantiene coherentes entre sí, en cualquier dirección: si editas el diseño, la propuesta se ajusta.
/opsx:sync fusiona las delta specs en openspec/specs/ sin archivar el cambio. Útil cuando quieres consolidar antes de cerrar.
Los extendidos, y por qué /opsx:verify no te va a funcionar todavía
Aquí está el detalle que hace perder media hora a mucha gente: el perfil por defecto no trae verify.
El perfil core son los seis de arriba — propose, explore, apply, update, sync, archive. Los extendidos son otros seis: /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive y /opsx:onboard. Si escribes /opsx:verify recién instalado, no autocompleta y no pasa nada.
Para activarlos:
openspec config profile # selecciona el perfil ampliado
openspec update # aplica los cambios en el proyecto
Con el perfil ampliado activo, /opsx:verify contrasta la implementación contra la spec. No es un test runner: es la comprobación de que no se ha colado nada que nadie pidió y de que no falta nada que sí se pidió.
Empieza por los seis del perfil core. Los extendidos los necesitarás cuando tengas el ciclo rodado y lleves varios cambios a la vez.
Delta specs: por qué esto sirve en un proyecto que ya existe
Una delta spec es una spec que describe solo lo que cambia — lo añadido, lo modificado y lo eliminado — en vez de redescribir el sistema entero. Es lo que hace viable OpenSpec en un proyecto que ya existe.
Así se ve una:
## ADDED Requirements
### Requirement: Filtrado por categoría
El listado DEBE permitir filtrar productos por categoría.
#### Scenario: Usuario selecciona una categoría
- GIVEN el listado de productos cargado
- WHEN el usuario selecciona la categoría "Audio"
- THEN el listado muestra solo productos de esa categoría
## MODIFIED Requirements
### Requirement: Paginación del listado
El listado DEBE conservar el filtro activo al cambiar de página.
Dos cosas que conviene saber antes de copiar esto. Las etiquetas son literales y no se traducen: ADDED, MODIFIED, REMOVED, Requirement:, Scenario: y GIVEN/WHEN/THEN van en inglés aunque el cuerpo esté en español. Y solo incluyes las secciones que uses — si el cambio no elimina nada, no dejes un ## REMOVED Requirements vacío.
Sobre los escenarios: es vocabulario Gherkin, pero en Markdown plano. Sin ficheros .feature, sin Cucumber, 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. La lista completa está en la tabla de herramientas soportadas, que cubre más de treinta.
Cómo migrar del flujo antiguo de OpenSpec al flujo OPSX
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: ejecuta openspec update, que regenera los ficheros de skills y comandos para las herramientas que tengas configuradas.
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.
Dos avisos antes de que te lances. 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.
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í.
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.
¿Por qué no me funciona el comando /opsx:verify?
Porque no viene en el perfil por defecto. OpenSpec usa el perfil core, que trae seis comandos: propose, explore, apply, update, sync y archive. El comando verify pertenece al perfil ampliado, junto a new, continue, ff, bulk-archive y onboard. Para activarlo ejecuta openspec config profile y después openspec update.
¿Qué comandos trae OpenSpec por defecto?
El perfil core incluye seis: propose para generar la propuesta, explore para planificar sin compromiso, apply para implementar, update para mantener coherentes los artefactos de planificación, sync para fusionar las delta specs en openspec/specs/ y archive para cerrar el cambio.
¿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 ejecutar openspec update en el proyecto, que regenera skills y comandos, 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.
¿Te resultó útil este artículo?
Compártelo con tu comunidad y ayuda a otros desarrolladores.