OpenSpec

1. Instalación

OpenSpec es un framework ligero de Spec-Driven Development (SDD), como Spec Kit o Kiro. Es agnóstico al agente y, como todos las herramientas de este tipo, y, su objetivo es que humanos y agentes de IA acuerden primero qué se va a construir antes de escribir código. La idea es sustituir el flujo de prompt al código por un flujo de especificación a revisión a implementación.

Una de sus principales virtudes es que introduce una capa de especificaciones versionada dentro del propio repositorio de código, las instrucciones de determinada feature, por lo que se convierte en una referencia de contexto más viva y cercana al proyecto que otros formatos que terminan por no volver a consultarse nunca, somo el jira o el confluence.

El mecanismo básico se basa en un flujo dividido en tres grandes etapas:

1. Propose: Describe la feature.
2. Apply: El agente de IA implementa la feature según lo indicado en la feature.
3. Archive: Se guarda la spec en el historial.

Dicho de otra forma: la IA propone un plan, unas especificaciones, se corrigen, se les da el visto bueno, se aplican y se archivan.

Para instalarla, se puede usar npx o npm.

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

Si se prefiere no instalar globalmente, luego hay que añadir openspec a los scripts en el package.

{
  "scripts": {
    "openspec": "openspec"
  }
}

Una vez instaladas, en el directorio root del proyecto donde queramos trabajar con este framework, ejecutamos:

openspec -- init

Y nos aparece un texto de bienvenida.

Seleccionamos enter y y escogemos con qué agente queremos trabajar, como Codex, Claude, Gemini, etcétera. Seleccionamos por lo menos uno y en el proyecto nos debería haber aparecido una directorio llamado openspec.

Aquí se deben generar dos subdirectorios:

• specs: Aquí vivirán las especificaciones actuales del sistema, lo que tu proyecto ya hace o debe hacer.
• change: Aquí se crean los cambios nuevos antes de implementarlos. Cada feature o modificación tendrá su propia carpeta.

También se habrá preparado un archivo llamado config.yaml con la configuración de OpenSpec, como las herramientas activadas, comandos, comportamiento del proyecto, etcétera.

Además, según el agente escogido, puede haber generado elementos adecuados para trabajar con él. Por ejemplo, si escogemos Claude, en .claude creará estas skills:

• openspec-propose. Sirve para crear una propuesta de cambio. Genera la carpeta en .openspec/changes/... con la intención, requisitos y tareas iniciales.
• openspec-apply-change. Sirve para implementar un cambio ya definido. Claude lee la spec/tareas y modifica el código siguiendo ese plan.
• openspec-archive-change. Archiva un cambio terminado en la documentación del proyecto.
• openspec-apply-change. Sirve para crear o actualizar las specs actuales a partir del código real, para sincronizar las specs con el estado existente del proyecto.
• openspec-explore. Sirve para entender el proyecto antes de proponer o implementar nada.

Todo esto se entiende mejor en la práctica.

2. Hola mundo

Para comprender cómo funciona, vamos a preparar una página de login en un proyecto de angular.

Lo primero es ejecutar el propose

/openspec-propose "Crear una pantalla de login como página inicial con formulario reactivo"

Internamente, la skill ejecuta una serie de pasos, entre los que destacan:

1. Entender qué se quiere construir. Si no está claro, debe preguntar. No puede crear una propuesta sin entender el cambio.

2. Crea un nombre de cambio. Por ejemplo, añadir un login puede convertirse en add-login.

3. Genera los artefactos, las instrucciones necesarias para preparar la feature. Aunque hay otros esquemas, normalmente serán:

proposal.md: qué y por qué design.md: cómo se va a hacer tasks.md: pasos de implementación

1. Prepara las spec, las especificaciones, en formato Gherkins

#### Scenario: Pantalla de login visible
- **WHEN** el usuario está en `/login`
- **THEN** el sistema muestra un formulario con campo email, campo contraseña y botón "Iniciar sesión"

En síntesis, normaliza la intención, el diseño y el plan de trabajo.

Cuando termina, muestra un pequeño informe y a partir de ahí los humanos podemos modificar lo que queramos en los archivos .md que se han generado.

Una vez revisados los cambios, hay que aplicarlos con:

/openspec-apply-change

El agente se pone en marcha y desarrolla todo el código necesario para cumplir con la especificación.

Y, una vez que ha terminado, ya podríamos archivar la spec ejecutando

/openspec-archive-change

Pero antes de archivarlo nos pregunta si queremos que ese conocimiento pase a formar parte de las specs oficiales del proyecto. Hay dos opciones principales:

• Con Sync ahora pasa a formar parte de las specs oficiales. En nuestro caso, guardaría la spec en openspec\specs\login-page\spec.md y además en el archivo: openspec\changes\archive
• Con Archivar sin sync queda solo el histórico del cambio en changes/archive/login-page.

En realidad, es prácticamente lo mismo y no descarto que en un futuro terminen agrupando estos dos directorios.

3. Consideraciones

Entre sus virtudes principales, creo que la mayor es embridar un poco a los vibecoders si se hace con cierto orden. Las specs se pueden revisar en PR igual que el código y eso siempre es bueno. Antes de lanzar un proceso con un coste más o menos alto en tokens, una segunda persona puede analizar si las indicaciones parecen correctas.

Además me parece interesante la idea de que las especificaciones acompañen al proyecto. Algo documentado en una plataforma externa, sea cual sea, se termina convirtiendo en la práctica en algo no documentado.

Ahora bien, le encuentro también varias limitaciones. A vuelapluma.

1. Añade fricción. Para cambios pequeños puede ser demasiado ceremonial. Entre decirle al agente que haga una página de login y esto, no hay mucha diferencia.

2. Las specs se limitan a las instrucciones sobre cómo hacer algo para una cosa muy concreta y eso es en la práctica una base documental muy pobre y que tiende a repetirse. Sigamos con el ejemplo del login. En el frontal habrá una especificación sobre cómo es el login, pero también otra en el back que -si hay suerte- será parecida. Es mucho mejor si existen indicaciones DDD que se pueden compartir, como qué define la entidad usuario. Este es un tema complejo sobre el que quizás vuelva otro día.

3. Por su propia naturaleza, estas specs solo sirven para resolver la construcción de código y es difícil reaprovecharlas para otros usos, como un onboarding.

4. Si no se definen protocolos estrictos de revisión de código, pueden degenerar fácilmente en el típio IA Slop del vive coding. Dicho de otra forma, OpenSpec organiza el trabajo, pero no sustituye tests, CI, contract tests ni revisión humana, a pesar de que puede dar falsa sensación de rigor.

5. Las specs no son ni de lejos tan descubribles como las skills. Mientras que las skills incluyen metadatos explícitos (name, description, propósito y reglas de uso) que permiten al agente saber inmediatamente cuándo utilizarlas, las specs son simples archivos Markdown organizados por carpetas. Esto obliga al modelo a inferir qué documentos son relevantes a partir de nombres y búsqueda textual, lo que dificulta el enrutamiento del contexto y aumenta el riesgo de ignorar especificaciones importantes.

Mi impresión, en síntesis, es que OpenSpec es una buena herramienta para ordenar el trabajo de un único agente, pero no una plataforma de ingeniería de software asistida por IA. Para proyectos serios sigue faltando gestión de contexto a gran escala, trazabilidad bidireccional, navegación semántica, integración con la arquitectura del sistema y mecanismos de verificación más allá de la documentación. Es mejor que el vibe coding, cualquier framework es mejor que ese despilfarro de tokens, pero está mucho más cerca de ser un gestor de tíckets jira que un sistema de ingeniería del conocimiento para grandes aplicaciones corporativas.