Inicio rápido de OpenSpec: instalación, flujo de trabajo y errores habituales

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 logra que tú y tu agente de codificación alcancen un acuerdo sobre un cambio en Markdown plano antes de que se escriba cualquier código, sin la ceremonia de fases rigurosas de los frameworks de desarrollo basado en especificaciones más pesados.

La mayoría de los equipos que prueban el Desarrollo Basado en Especificaciones (SDD) se estancan en el mismo compromiso: suficiente proceso para evitar que un agente adivine, sin un andamiaje tan excesivo que una corrección de errores de cincuenta líneas requiera un documento de propuesta. La respuesta de OpenSpec es saltarse por completo el instinto de “documentar todo el sistema primero” y escribir especificaciones solo para lo que un cambio realmente toca, utilizando deltas ADDED, MODIFIED y REMOVED en lugar de una reescritura completa cada vez.

Flujo de trabajo de desarrollo basado en especificaciones con OpenSpec y 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 rastreador de problemas de OpenSpec.

¿Qué es OpenSpec?

OpenSpec describe su propia filosofía en cuatro líneas: fluido, no rígido; iterativo, no en cascada; fácil, no complejo; diseñado para brownfield, no solo 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 seguir el orden estricto de especificar-entonces-planificar-entonces-implementar de la manera que el flujo de trabajo SDD neutral respecto a la herramienta lo describe.

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

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

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 Basado en Especificaciones?, solo que acotada a un cambio a la vez en lugar de escrita toda de una vez.

Instalando OpenSpec

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

node --version

Instala la CLI globalmente con npm y luego verifica que se haya colocado en tu PATH:

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

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

cd your-project
openspec init

openspec init pregunta qué herramientas de IA usas y escribe los archivos de habilidad y comando 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 mediante guiones, omite por completo el selector:

openspec init --tools claude,cursor   # configura herramientas específicas
openspec init --tools all             # todas las herramientas compatibles
openspec init --tools none            # solo estructura openspec/, sin archivos de herramienta

Reinicia tu IDE después para que tome las nuevas habilidades y comandos 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, el cual ejecuta la instalación, lanza openspec init e informa sobre lo que configuró.

El flujo de trabajo central: Explorar, Proponer, Aplicar, Archivar

Esta es la única cosa que hace tropezar a casi todos en su primer día: los comandos 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 al que entrar: escribir el comando de barra en el chat es cómo empiezas.

flowchart LR A["/opsx:explore (opcional)"] --> B["/opsx:propose nombre-del-cambio"] B --> C["/opsx:apply"] C --> D["/opsx:archive"] D -->|especificaciones fusionadas| E["openspec/specs/"]
  • /opsx:explore es un socio de pensamiento sin riesgos. Lee la parte relevante de tu base de código, expone opciones y da forma a un plan antes de que se escriba algo en el disco; vale la pena formarlo como hábito específicamente porque evita que un agente ávido construya con confianza la cosa equivocada.
  • /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. Revisas el plan aquí, antes de que comience la implementación.
  • /opsx:apply trabaja a través de la lista de tareas, marcando elementos mientras avanza. Dado que el progreso reside en archivos y no solo en el historial del chat, puedes limpiar tu ventana de contexto o iniciar una sesión nueva y retomar exactamente donde /opsx:apply se quedó.
  • /opsx:archive archiva el cambio completado en openspec/changes/archive/AAAA-MM-DD-<nombre>/ y fusiona sus especificaciones delta en el árbol canónico openspec/specs/.

El perfil predeterminado core instala exactamente esos cuatro comandos más update y sync. Un perfil ampliado 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: cambia a él 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 releer 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:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Ese formato delta de ADDED/MODIFIED/REMOVED es el mecanismo que permite a OpenSpec evitar reescribir un archivo de especificación completo por un cambio de un solo campo. También es la razón por la que OpenSpec es explícitamente brownfield-first en lugar de 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 la 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

Comite toda la carpeta openspec/ en 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 es un borrador que se elimina 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 aplicación tiene 80,000 líneas de antigüedad, ¿tengo que especificar todo esto primero?”. No. Las propias directrices de OpenSpec son francas al respecto: 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 primero cómo funcionan realmente las cosas, y luego /opsx:propose un cambio acotado solo a esa porción.

Si ya tienes PRDs, documentos SRS o documentos de diseño guardados en Notion o Confluence, trátalos como material de fuente para la exploración en lugar de algo que convertir por lotes en especificaciones. Pega la sección relevante en una sesión de /opsx:explore y deja que el agente dé forma a una delta enfocada a partir de ella; una conversión mecánica única de un PRD de cuarenta páginas tiende a producir una especificación en 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 ampliado /opsx:onboard escanea tu base de código en busca de una mejora pequeña y segura y recorre el bucle completo sobre ella.

Preguntas y problemas comunes

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

“Escribí el comando de barra y no pasó nada.” Casi siempre es uno de estos casos: 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 vieja que openspec update informa que todo está al día sin haber escrito nunca 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 compatibles).

“La IA genera mucha más especificación de la que necesito.” Esta es la queja más citada en los análisis extensos: 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 propias especificaciones delta no tienen un límite duro, por lo que recortar las especificaciones generadas a lo que realmente sostiene la estructura es un hábito que tienes que mantener tú mismo, no algo que la herramienta te imponga.

“Dos cambios tocaron el mismo requisito y uno silenciosamente descartó el escenario del otro.” Este es un caso límite real y documentado: archivar aplica una delta MODIFIED como un reemplazo de bloque completo clave por nombre de requisito, por lo que si dos cambios en curso modifican ambos el mismo requisito, archivar el segundo solía sobrescribir los escenarios del primero sin advertencia. Las versiones actuales añaden una comprobación de deriva que aborta el archivado y te dice que refresques la especificación del cambio primero; pero aún 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?" Las propias documentaciones de OpenSpec recomiendan modelos de razonamiento alto tanto para la planificación como para la implementación – se señalan específicamente modelos de clase Opus y 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.

"¿En qué es diferente esto 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 encadena al IDE de AWS y a los modelos de Claude; OpenSpec cambia parte de esa estructura inicial por la capacidad de iterar libremente y trabajar con el 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.

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

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

"¿Cómo evito que un agente re-proponga algo que ya rechazamos?" /opsx:archive no tiene un estado dedicado para un cambio rechazado, por lo que nada le dice a una propuesta futura que una idea ya fue investigada y descartada. Ve [Propuestas rechazadas en OpenSpec: Una convención de memoria de decisión](https://www.glukhov.org/es/ai-devtools/openspec/handling-rejected-proposals/ “Propuestas rechazadas en OpenSpec: Una convención de memoria de decisión”}) para el patrón decision.md y la regla de configuración que hace que un agente busque en el archivo antes de proponer de nuevo.

Cuándo OpenSpec encaja y cuándo no

Buena compatibilidad:

  • Bases de código brownfield donde quieres especificaciones revisables sin documentar todo el sistema de antemano.
  • Desarrolladores solitarios y equipos pequeños que quieren una ceremonia más ligera que Spec Kit pero que aún obtengan un plan escrito antes del código.
  • Trabajo que abarca varios archivos, un cambio de esquema o cualquier cosa para la que un ingeniero junior querría razonablemente un documento de diseño corto.
  • Equipos comprometidos con revisar planes en solicitudes de extracción (pull requests): las especificaciones delta se fusionan limpiamente desde un diff ya que solo describen lo que cambió.

Compatibilidad más débil:

  • Correcciones de errores de una línea y prototipos descartables, donde el paso de revisión de propuesta 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 en el IDE como Kiro: ver el marco de decisión en la comparación de herramientas para dónde gana cada herramienta.
  • Características que cruzan repositorios hoy, a menos que estés dispuesto a probar la función beta de 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 Basado en Especificaciones vs Vibe Coding primero, ya que OpenSpec solo ayuda una vez que ya has decidido que la estructura vale la sobrecarga.

Conclusión

La apuesta de OpenSpec es que el mayor dolor del Desarrollo Basado en Especificaciones proviene de la ceremonia, no de la idea subyacente de acordar un plan antes de que exista el código. Deltas en lugar de reescrituras completas, sin fases bloqueadas y un flujo de trabajo brownfield-first lo hacen notablemente más ligero que Spec Kit o Kiro para adoptarse en una base de código que no construiste desde cero. Las desventajas también son reales: la 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 las propias herramientas 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 se gana su valor frente a tu carga de trabajo real.

Enlaces útiles

Suscribirse

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