OpenSpec: Guía de inicio rápido, instalación, flujo de trabajo y errores comunes

«Especificaciones como deltas, no como un PRD de 40 páginas.»

Índice

OpenSpec es una CLI gratuita y de código abierto de Fission AI que permite que tú y tu agente de codificación acuerden un cambio en Markdown plano antes de que se escriba cualquier código, sin la ceremonia de fases restringidas de los frameworks más pesados dirigidos por especificaciones.

La mayoría de los equipos que intentan el Desarrollo Dirigido por Especificaciones (SDD) se atascan en el mismo compromiso: suficiente proceso para evitar que un agente adivine, sin tanta estructura andamiaje que una corrección de errores de cincuenta líneas necesite un documento de propuesta. La respuesta de OpenSpec es saltarse por completo la instintiva idea de “documentar todo el sistema primero” y escribir especificaciones solo para lo que un cambio afecta realmente, usando deltas de ADDED, MODIFIED y REMOVED en lugar de una reescritura completa cada vez.

Flujo de trabajo de desarrollo dirigido por especificaciones de OpenSpec con un asistente de codificación de IA

Ese diseño centrado en el cambio es también la razón por la que OpenSpec sigue apareciendo junto a GitHub Spec Kit, Kiro y Superpowers en la comparación de categorías de herramientas SDD – suele ser la elección cuando un equipo quiere especificaciones revisables sin una fase de planificación de 800 líneas. Esta guía cubre la instalación de la CLI, el flujo de trabajo de cuatro comandos que realmente usas a diario, cómo se ve un cambio en el disco y las preguntas y quejas que aparecen con más frecuencia en Reddit y en el propio registrador de problemas de OpenSpec.

¿Qué es OpenSpec?

OpenSpec describe su propia filosofía en cuatro líneas: fluido no rígido, iterativo no cascada, fácil no complejo, construido para entornos existentes (brownfield) no solo para nuevos (greenfield). En la práctica, esto significa que no hay fases bloqueadas: puedes editar una propuesta, una especificación o una lista de tareas en cualquier punto de un cambio, en lugar de ser forzado a pasar por especificar-entonces-planificar-entonces-implementar en un orden estricto, como lo describe el flujo de trabajo SDD neutral de herramientas.

Un cambio en OpenSpec produce hasta cuatro artefactos Markdown en su propia carpeta:

Artefacto Propósito
proposal.md Por qué existe el cambio y qué modifica, en lenguaje claro
specs/ Requisitos delta y escenarios: la especificación testeable para este cambio
design.md Enfoque técnico opcional, para cambios que lo necesiten
tasks.md La lista de verificación de implementación por la que el agente trabaja

Una vez que un cambio se implementa y se archiva, sus especificaciones delta se fusionan en openspec/specs/, que se convierte en la descripción duradera y del estado actual de tu sistema: la misma idea de “especificación como fuente de verdad” cubierta en ¿Qué es el Desarrollo Dirigido por Especificaciones?, solo que con alcance por un cambio a la vez en lugar de escrito todo de una vez.

Instalando OpenSpec

OpenSpec es una CLI de Node.js, por lo que necesitas Node 20.19.0 o más reciente en tu máquina.

node --version

Instala la CLI globalmente con npm, luego verifica que haya llegado a tu PATH:

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

Deno, pnpm, yarn, bun y nix también son rutas de instalación admitidas si se adapta mejor a tu configuración que npm. Una vez instalado, inicialízalo dentro de un proyecto:

cd tu-proyecto
openspec init

openspec init pregunta qué herramientas de IA usas y escribe los archivos de habilidades y comandos correspondientes; OpenSpec admite más de 30 asistentes, incluyendo Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex, Kiro y OpenCode. Para CI o configuración scriptada, omite el selector por completo:

openspec init --tools claude,cursor   # configurar herramientas específicas
openspec init --tools all             # cada herramienta admitida
openspec init --tools none            # solo estructura openspec/, sin archivos de herramientas

Reinicia tu IDE después para que detecte las habilidades y comandos recién escritos. Si prefieres que tu asistente haga toda la instalación por ti, OpenSpec incluye un prompt de configuración que puedes pegar en Claude Code u otro agente, que ejecuta la instalación, ejecuta openspec init e informa de lo que configuró.

El Flujo de Trabajo Central: Explorar, Proponer, Aplicar, Archivar

Esta es la única cosa que casi a todos les causa problemas en su primer día: los comandos de openspec se ejecutan en tu terminal, pero los comandos /opsx: se ejecutan en la ventana de chat de tu asistente de IA. No hay un “modo interactivo” separado que ingresar: escribir el comando de barra diagonal en el chat es cómo inicias.

flowchart LR A["/opsx:explore (opcional)"] --> B["/opsx:propose nombre-cambio"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|specs fusionadas| E["openspec/specs/"]
  • /opsx:explore es un compañero de pensamiento sin riesgos. Lee la parte relevante de tu base de código, expone opciones y forma un plan antes de que se escriba algo en el disco: vale la pena formarlo como hábito específicamente porque detiene a un agente entusiasta de construir confiadamente lo incorrecto.
  • /opsx:propose <nombre> crea openspec/changes/<nombre>/ y redacta la propuesta, las especificaciones delta, el diseño opcional y la lista de tareas en un solo paso. Aquí revisas el plan, antes de que comience la implementación.
  • /opsx:apply trabaja a través de la lista de tareas, marcando elementos a medida que avanza. Debido a que el progreso vive en archivos y no solo en el historial del chat, puedes limpiar tu ventana de contexto o iniciar una nueva sesión y retomar exactamente donde /opsx:apply se quedó.
  • /opsx:archive archiva el cambio completado en openspec/changes/archive/YYYY-MM-DD-<nombre>/ y fusiona sus especificaciones delta en el árbol canónico openspec/specs/.

El perfil core predeterminado instala exactamente esos cuatro comandos más update y sync. Un perfil expandido agrega new, continue, ff, verify, bulk-archive y onboard para equipos que quieren crear un artefacto a la vez en lugar de todos de una vez; cámbialo con openspec config profile seguido de openspec update.

Cada herramienta escribe el mismo comando de manera diferente dependiendo de cómo cargue instrucciones personalizadas: /opsx:propose en Claude Code, /opsx-propose en Cursor y GitHub Copilot, @opsx-propose en Amazon Q, o $openspec-propose en Codex. openspec init imprime la forma exacta para las herramientas que elegiste, por lo que la solución más rápida para “no pasó nada cuando escribí el comando” suele ser volver a leer esa pista impresa en lugar de adivinar.

Cómo se ve un cambio en el disco

Una carpeta de cambio bajo openspec/changes/add-dark-mode/ típicamente contiene una propuesta, una especificación delta y una lista de tareas como esta:

## Requisitos ADDED

### Requisito: Selección de tema
La app DEBE permitir a los usuarios cambiar entre temas claro y oscuro,
por defecto a la preferencia del sistema.

#### Escenario: El usuario activa el modo oscuro
- **CUANDO** el usuario hace clic en el interruptor de tema
- **ENTONCES** la app cambia al modo oscuro y persiste la elección

Ese formato de delta ADDED/MODIFIED/REMOVED es el mecanismo que permite a OpenSpec evitar reescribir un archivo de especificación entero por un cambio de un solo campo. También es la razón por la que OpenSpec es explícitamente primero-para-entornos-existentes (brownfield-first) en lugar de primero-para-nuevos (greenfield-first): nunca documentas toda tu aplicación antes de obtener valor, solo documentas la porción que cada cambio real toca, y openspec/specs/ se completa de manera natural a lo largo de meses de trabajo normal.

Comandos útiles de CLI para verificar ese estado sin salir de la terminal:

openspec list                 # cambios activos
openspec show add-dark-mode   # ver los artefactos de un cambio
openspec validate --all       # verificar el formato de especificaciones en todo el proyecto
openspec view                 # panel de control interactivo

Compara la carpeta completa openspec/ a git. Los cambios activos y el archivo están destinados a convertirse en un registro duradero y versionado de lo que hace tu sistema y por qué cambió: no un borrador que se borra después de fusionar.

Adoptando OpenSpec en una base de código existente

La preocupación más común de los equipos que evalúan OpenSpec en un proyecto real es alguna versión de “mi app tiene 80,000 líneas de antigüedad, ¿tengo que especificarlo todo primero?” No. La propia guía de OpenSpec es franca sobre esto: elige algo pequeño y real que ya ibas a construir esta semana, ejecuta /opsx:explore en el área que estás a punto de tocar para que el agente mapee cómo funcionan las cosas realmente primero, luego /opsx:propose un cambio con alcance solo para esa porción.

Si ya tienes PRDs, documentos SRS o documentos de diseño en Notion o Confluence, trátalos como material fuente para la exploración en lugar de algo que convertir masivamente en especificaciones. Pega la sección relevante en una sesión de /opsx:explore y deja que el agente forme una delta enfocada a partir de ella; una conversión mecánica de una sola vez de un PRD de cuarenta páginas tiende a producir una especificación a la que nadie confía seis meses después. Para equipos que quieren una primera ejecución guiada y narrada en lugar de saltar directamente a un cambio real, el comando expandido /opsx:onboard escanea tu base de código en busca de una mejora pequeña y segura y recorre el ciclo completo sobre ella.

Preguntas y Problemas Comunes

Estos son los problemas que aparecen repetidamente en el Discord de OpenSpec, los problemas de GitHub y los hilos de Reddit en subreddits como r/cursor, r/RooCode y r/opencodeCLI.

“Escribí el comando de barra diagonal y no pasó nada.” Casi siempre es uno de los siguientes: lo escribiste en la terminal en lugar del chat de tu asistente, tu IDE no se ha reiniciado desde que se ejecutó openspec init, o la versión de la CLI es tan antigua que openspec update informa que todo está actualizado sin nunca escribir los archivos de flujo de trabajo más nuevos. Ejecuta openspec update, reinicia el IDE y confirma que las carpetas de habilidades existen (.claude/skills/openspec-* para Claude Code, o el equivalente de tu herramienta de la lista de herramientas admitidas).

“La IA genera mucha más especificación de la que necesito.” Esta es la queja más citada en artículos más largos: un agente puede convertir una función de treinta minutos en una especificación de 800 líneas. OpenSpec limita el campo context: inyectado en cada solicitud a 50KB específicamente para forzar disciplina, pero las especificaciones delta en sí no tienen límite duro, por lo que reducir las especificaciones generadas a lo que realmente es portante es un hábito que debes mantener tú mismo, no algo que la herramienta te impone.

“Dos cambios tocaron el mismo requisito y uno eliminó silenciosamente el escenario del otro.” Este es un caso límite real y documentado: archivar aplica una delta MODIFIED como un reemplazo de bloque completo claveado por nombre de requisito, por lo que si dos cambios en curso ambos modifican el mismo requisito, archivar el segundo solía sobrescribir los escenarios del primero sin aviso. Las versiones actuales agregan una verificación de deriva que interrumpe el archivo y te indica que actualices la especificación del cambio primero: pero todavía vale la pena saber que el modo de falla existe si ejecutas varios cambios en el mismo área en paralelo.

"¿Qué modelo de IA debería usar realmente con esto?" Los propios documentos de OpenSpec recomiendan modelos de alto razonamiento para ambos, planificación e implementación: se mencionan específicamente modelos de clase Opus y de clase Codex y limpiar tu ventana de contexto antes de la implementación, ya que un contexto limpio produce resultados mediblemente mejores que una sesión larga y acumulada.

"¿Cómo es esto diferente de Spec Kit, Kiro, Superpowers o BMAD?" Esta es la pregunta de Reddit más frecuente y la respuesta honesta es “peso del proceso”. El propio README de OpenSpec enmarca la comparación directamente: Spec Kit es exhaustivo pero más pesado, con más Markdown y puertas de fase rígidas; Kiro es poderoso pero te encierra en el IDE de AWS y los modelos de Claude; OpenSpec intercambia parte de esa estructura inicial por la capacidad de iterar libremente y trabajar con cualquier asistente que ya tengas abierto. Para el desglose completo contra Spec Kit, Kiro, habilidades de Claude Code, BMAD-METHOD y Superpowers, ver la comparación de herramientas SDD dedicada.

"¿La IA sigue realmente la especificación que acaba de escribir?" No siempre, y esto es un problema documentado en las herramientas SDD en general, no único de OpenSpec: una ventana de contexto grande no significa que el agente atienda igualmente a cada parte de ella. El comando /opsx:verify existe específicamente para detectar código generado que contradice su propia especificación, y vale la pena ejecutarlo en cualquier cosa no trivial en lugar de confiar ciegamente en la implementación.

"¿Necesito esto para una corrección de una línea?" No. El propio FAQ de OpenSpec lo dice: úsalo donde el acuerdo importe, que es la mayor parte del trabajo no trivial de varios archivos, y omítelo para una corrección de error tipográfico o un prototipo descartable que borrarás en una semana.

Cuando OpenSpec Encaja y Cuando No

Buen ajuste:

  • Bases de código existentes (brownfield) donde quieres especificaciones revisables sin documentar todo el sistema de antemano.
  • Desarrolladores solitarios y equipos pequeños que quieren menos ceremonia que Spec Kit pero aún obtener un plan escrito antes del código.
  • Trabajo que abarca varios archivos, un cambio de esquema o cualquier cosa por la que un ingeniero junior querría razonablemente una corta documentación de diseño.
  • Equipos ya comprometidos a revisar planes en pull requests: las especificaciones delta difieren limpiamente ya que solo describen lo que cambió.

Ajuste más débil:

  • Correcciones de errores de una línea y prototipos descartables, donde el paso de propuesta-revisión cuesta más de lo que ahorra.
  • Equipos que necesitan la estructura más pesada y prescriptiva de Spec Kit o una experiencia nativa de AWS e integrada con IDE como Kiro: ver el marco de decisión en la comparación de herramientas para dónde gana cada herramienta.
  • Características entre repositorios hoy, a menos que estés dispuesto a probar la función beta stores de OpenSpec, que mueve la planificación a su propio repositorio compartido para que múltiples bases de código y agentes puedan leer el mismo plan.
  • Cualquiera que aún está decidiendo si una característica dada merece una especificación en absoluto: lee Desarrollo Dirigido por Especificaciones vs Vibe Coding primero, ya que OpenSpec solo ayuda una vez que ya has decidido que la estructura vale el sobrecosto.

Conclusión

La apuesta de OpenSpec es que la mayor parte del dolor del Desarrollo Dirigido por Especificaciones proviene de la ceremonia, no de la idea subyacente de acordar un plan antes de que exista código. Deltas en lugar de reescrituras completas, sin fases bloqueadas y un flujo de trabajo primero-para-entornos-existentes (brownfield-first) lo hacen notablemente más ligero que Spec Kit o Kiro para adoptarlo en una base de código que no construiste desde cero. Los compromisos son reales también: el hinchazón de especificaciones es un riesgo genuino sin disciplina, el manejo de conflictos alrededor de cambios simultáneos a un requisito aún está madurando, y el ecosistema es más joven que el propio herramienta de GitHub. Instálalo en un proyecto real, ejecuta un cambio pequeño a través de explorar-proponer-aplicar-archivar de principio a fin, y decide desde ahí si la ceremonia más ligera gana su costo contra tu carga de trabajo real.

Enlaces Útiles

Suscribirse

Recibe nuevas publicaciones sobre sistemas, infraestructura e ingeniería de IA.