OpenSpec
Comandos y capacidades de OpenSpec 1.16.0 comprobados el 31 de octubre de 2026.
OpenSpec, de Fission-AI, organiza el SDD alrededor de un cambio con las etapas propose, review, apply y archive. Las especificaciones permanentes describen el sistema, y los deltas registran los cambios propuestos a los requisitos.
OpenSpec soporta distintos agentes y asistentes de código, incluidos Claude Code, Codex, Cursor y GitHub Copilot.
Instalación
La instalación por npm requiere Node.js >=22.12.0. El binario independiente no requiere Node.js; elige el método en la guía oficial. A continuación se muestra la opción admitida mediante npm.
npm install -g @fission-ai/openspec@latest
openspec init
openspec init crea el directorio openspec/ y registra comandos slash con el prefijo /opsx:; openspec update actualiza las instrucciones para los agentes tras una actualización.
Flujo de trabajo
El conjunto de comandos depende del perfil. Elígelo con openspec config profile y luego ejecuta openspec update en el proyecto para aplicar la elección a las instrucciones del agente. El flujo básico recorre los siguientes pasos.
/opsx:exploreayuda a explorar el código y comparar opciones antes de preparar artefactos./opsx:propose <idea>crea un paquete de propuesta que revisas antes de implementar./opsx:applyejecuta las tareas del checklist./opsx:archivepropone sincronizar los deltas con las especificaciones permanentes, si aún no se ha hecho, y mueve el cambio al archivo.
Si cambian los requisitos tras preparar la propuesta, /opsx:update actualiza los artefactos de planificación. /opsx:sync incorpora los deltas a las especificaciones permanentes; también se puede sincronizar al archivar.
El perfil ampliado incluye /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive y /opsx:onboard. Dan soporte a la preparación por etapas, la verificación y el archivado de cambios grandes.
Al terminar un cambio, ejecuta /opsx:archive y confirma la sincronización de deltas propuesta. Si las especificaciones ya se actualizaron con /opsx:sync, no hace falta sincronizar de nuevo. El archivado conserva los artefactos del cambio; el orden respecto al merge lo decide el equipo en su propio proceso.
El diagrama sigue un cambio desde la propuesta hasta el archivo.
Mientras el cambio no se sincroniza, los requisitos aceptados viven en el delta dentro del paquete, y la especificación permanente describe el sistema tal como es. La sincronización se hace por separado o al archivar, y el archivo guarda la explicación y la historia del cambio.
La sintaxis depende del agente. Codex puede mostrar $openspec-propose, mientras que Cursor y GitHub Copilot usan la forma /opsx-propose. openspec init imprime la sintaxis exacta de la herramienta elegida.
Artefactos
El directorio openspec/ separa las especificaciones permanentes de los paquetes de cambio.
| Ruta | Qué contiene |
|---|---|
| openspec/specs/ | Especificaciones permanentes — el modelo actual de lo que ya está construido |
| openspec/changes/\ |
Por qué cambiamos esto |
| openspec/changes/\ |
Deltas de requisitos con escenarios concretos |
| openspec/changes/\ |
Enfoque técnico |
| openspec/changes/\ |
Checklist de implementación |
| openspec/changes/archive/ | Cambios completados |
Ejemplo de cambio de un requisito
En un servicio de entrega de eventos, un webhook se desactiva tras cinco fallos seguidos. La especificación permanente en openspec/specs/webhooks/spec.md contiene esta regla.
### Requirement: Delivery failure cutoff
El sistema SHALL desactivar el webhook tras cinco intentos fallidos seguidos.
#### Scenario: Failed deliveries reach cutoff
- **WHEN** el quinto intento de entrega seguido falla
- **THEN** el webhook se desactiva
El equipo acordó otro umbral para destinatarios temporalmente no disponibles. En el paquete de cambio, el agente crea un delta en openspec/changes/raise-cutoff/specs/webhooks/spec.md. Para el requisito modificado conserva el encabezado y da el nuevo requisito con su escenario completo.
## MODIFIED Requirements
### Requirement: Delivery failure cutoff
El sistema SHALL desactivar el webhook tras diez intentos fallidos seguidos.
#### Scenario: Failed deliveries reach cutoff
- **WHEN** el décimo intento de entrega seguido falla
- **THEN** el webhook se desactiva
En este ejemplo, MODIFIED Requirements indica la sustitución de un requisito existente. Tras la implementación y la verificación, el equipo confirma la sincronización en /opsx:archive. En el spec.md permanente, el requisito Delivery failure cutoff contiene ahora el umbral de diez y el escenario correspondiente; el marcador MODIFIED Requirements sigue formando parte del delta archivado. Si la propuesta se rechaza, la regla permanente con el umbral de cinco no cambia. El formato de secciones y escenarios se describe en la documentación de OpenSpec.
En qué se diferencia
- Las especificaciones permanentes describen el comportamiento requerido actual del sistema.
- Un delta registra la diferencia entre los requisitos actuales y los propuestos.
- El proceso está pensado para cambios sucesivos en una base de código existente.
- Las especificaciones compartidas ayudan al equipo a acordar los requisitos y la historia de sus cambios.
Cuándo elegirlo
OpenSpec encaja en un sistema existente cuyos requisitos hay que mantener junto con el código. Para un proceso basado en skills con puntos de control obligatorios, considera Superpowers, y para trabajar a través del tracker, compara el pack de Matt Pocock.