Desmitificando OpenSpec

Entré en OpenSpec esperando unos cuantos comandos y algo de Markdown. Al menos así era cuando lo probé por primera vez en sus inicios.

Luego abrí la documentación y encontré perfiles, esquemas, artefactos, archivos de configuración, flujos de archivo, OPSX y delta specs. Pasé más tiempo del que quiero admitir yendo de una pestaña a otra, intentando mantenerlo todo en la cabeza. ¿Qué es exactamente un artefacto? ¿Por qué hay perfiles y esquemas? Si ambos afectan al flujo de trabajo, ¿por qué necesitan existir ambos?

Esta es la explicación que hubiera deseado tener en lugar de esas pestañas.

¿Qué es OpenSpec?

OpenSpec es un framework de desarrollo spec-driven. Vive en tu repositorio junto con tu código y funciona con la mayoría de agentes de programación: Claude Code, Cursor, Codex, GitHub Copilot, OpenCode y otros. Se instala con npm install -g @fission-ai/openspec@latest, y añade comandos de planificación a tu agente.

La idea es simple. Antes de escribir código, describes el cambio que quieres hacer. OpenSpec genera una propuesta, un documento de diseño, un desglose de tareas y un spec delta que muestra cómo cambiarán los requisitos. Revisas ese plan, lo refinas y luego implementas. Cuando el cambio está listo, el spec delta se aplica a tus specs canónicos, de modo que los requisitos en tu repositorio se mantienen actuales.

Esa última parte es lo que lo diferencia del modo plan integrado de tu agente. El modo plan desaparece cuando termina la sesión de chat. Los specs de OpenSpec se quedan en tu repositorio como documentación viva, confirmados en git, revisables en PRs.

El proyecto es open source en openspec.dev.

La versión corta

OpenSpec se volvió mucho más fácil para mí cuando lo reduje a cuatro preguntas:

Concepto	La pregunta que responde
Profile	¿Qué acciones de flujo de trabajo están disponibles para mi agente?
Schema	¿Qué artefactos de planificación existen, y qué depende de qué?
Config	¿Qué contexto de proyecto y reglas extra deben dar forma a esos artefactos?
Skills	¿Cómo ejecuta mi herramienta de IA cada acción del flujo de trabajo?

Los artefactos son las salidas que produce ese sistema: propuestas, specs, diseños, tareas o cualquier otra cosa que tu esquema defina.

Por qué la terminología se siente por capas

Parte de la confusión tiene más sentido cuando ves cómo evolucionó OpenSpec.

El flujo de trabajo inicial era intencionalmente pequeño:

propose -> apply -> archive

El paso de propuesta creaba los documentos de planificación, el agente implementaba el cambio y archive plegaba el resultado de vuelta en los specs del proyecto.

Luego OPSX hizo el sistema más flexible. La planificación se convirtió en un conjunto de artefactos discretos conectados por dependencias. Podías crearlos de forma incremental, revisarlos según aprendías y personalizar el grafo en lugar de aceptar un proceso fijo.

Esa flexibilidad introdujo más acciones:

new -> continue or ff -> apply -> verify -> archive

OpenSpec 1.2 introdujo entonces los perfiles. El punto no era añadir otra abstracción de planificación. Los perfiles controlan qué skills y comandos de flujo de trabajo se instalan, para que la gente que quiere el camino corto no necesite cada comando expandido en el contexto de su agente.

El perfil core actual te da el camino rápido:

explore -> propose -> apply -> sync -> archive

El flujo de trabajo expandido expone acciones como new, continue, ff y verify cuando quieres un control más fino.

Esta historia importa. Los perfiles y los esquemas pueden parecer dos generaciones de la misma idea. No lo son, y esa confusión es donde perdí más tiempo.

Perfiles vs. Esquemas

Aquí fue donde me quedé atascado más tiempo. Asumí que los perfiles y los esquemas eran formas competidoras de definir un flujo de trabajo.

Son ortogonales.

Un perfil controla las acciones disponibles para ti. Un esquema controla la estructura de planificación sobre la que operan esas acciones.

Releí esa frase en la documentación tres veces antes de que cuajara, así que voy a dedicarle un rato.

Los perfiles eligen los controles

Un perfil no define proposal.md, design.md o tasks.md. Decide qué acciones de flujo de trabajo OpenSpec instala para tu herramienta de IA.

Con el perfil core, /opsx:propose te da la experiencia simple: describes el cambio y generas los artefactos de planificación en una sola pasada.

Con una selección expandida, puedes ser más deliberado:

/opsx:new crea el andamiaje del cambio.
/opsx:continue crea el siguiente artefacto disponible.
/opsx:ff crea todos los artefactos de planificación que se pueden generar.
/opsx:verify compara la implementación con los artefactos antes de archivar.

Mi abreviación original estaba cerca pero no del todo correcta. El perfil no dice "genera todo" ni "genera una cosa". El perfil hace disponibles esas acciones; el comando que eliges decide qué pasa después.

Los esquemas definen el grafo de planificación

Los esquemas responden a una pregunta distinta: ¿qué debería contener este cambio?

El esquema por defecto spec-driven contiene artefactos como propuesta, specs, diseño y tareas. También describe sus dependencias. Una vista simplificada se ve así:

              proposal
              /      \
           specs    design
              \      /
                tasks

Ese grafo es la razón por la que /opsx:continue puede decir qué artefacto está listo y cuál sigue bloqueado. OpenSpec comprueba qué existe en el disco y sigue las reglas de dependencia del esquema.

Un esquema personalizado podría añadir un artefacto de investigación o de revisión de seguridad:

research -> proposal -> specs -> security-review -> tasks

El perfil no necesita cambiar. La misma acción continue o ff puede recorrer un esquema distinto.

Ahí fue donde perfiles y esquemas por fin se separaron en mi cabeza: el perfil te da los controles; el esquema les da algo sobre lo que operar.

Lo que OpenSpec quiere decir con "Artefacto"

La palabra artefacto hizo que el sistema sonara más abstracto de lo que es.

Un artefacto es una salida definida por el esquema. La mayoría son archivos Markdown o un grupo de archivos Markdown:

proposal.md
design.md
tasks.md
specs/<capability>/spec.md

No hay ningún objeto artefacto especial ejecutándose en segundo plano. OpenSpec determina el estado en gran medida desde el sistema de ficheros: si la salida requerida existe, ese artefacto está listo y sus dependientes pueden quedar disponibles.

El término sigue importando porque un esquema puede definir más de una forma de archivo. El artefacto specs, por ejemplo, puede generar un directorio de delta specs en lugar de un archivo fijo. Pero como usuario, la traducción útil es:

Artefacto = una salida de planificación producida durante un cambio.

Propuesta, Specs, Diseño y Tareas en términos familiares

Me resultaron mucho más fáciles de entender a través del lenguaje ordinario de proyecto:

Artefacto OpenSpec	Equivalente familiar	Pregunta principal
Proposal	Caso de negocio	¿Por qué hacemos esto y qué entra en el alcance?
Specs	Requisitos	¿Qué debe hacer el sistema?
Design	Solución técnica	¿Cómo lo vamos a construir?
Tasks	Lista de implementación	¿Qué trabajo hay que completar?

Una vez que dejé de tratarlos como invenciones específicas de OpenSpec, el flujo de trabajo se sintió familiar. Son simplemente los documentos que un equipo decente produciría de todos modos, excepto que aquí el tooling sabe de ellos.

Main Specs vs. Delta Specs

Hay una distinción que pasé por alto un tiempo: OpenSpec maneja dos tipos de especificación.

Los specs bajo openspec/specs/ describen el sistema tal como se comporta ahora. Son la fuente canónica de verdad, organizados por capacidad.

Los specs dentro de un cambio describen solo lo que ese cambio añade, modifica o elimina. Esos son delta specs.

openspec/specs/                 current system
openspec/changes/add-2fa/specs/ proposed difference

Por eso el cambio se puede revisar sin reescribir toda la especificación. Los revisores ven la diferencia, no una segunda copia de todo.

Cuando el cambio se sincroniza o se archiva, esos deltas se aplican a los specs canónicos. Los requisitos añadidos se anexan, los modificados reemplazan sus versiones anteriores, los eliminados se borran.

Eso es lo que OpenSpec quiere decir cuando habla de preservar las especificaciones como documentación viva.

Lo que config.yaml realmente hace

Esperaba que openspec/config.yaml definiera el flujo de trabajo. No lo hace.

Configura el proyecto alrededor del flujo de trabajo:

schema: spec-driven

context: |
  Stack: TypeScript, React, PostgreSQL
  Public APIs must remain backwards compatible

rules:
  proposal:
    - Include a rollback plan
  tasks:
    - Include tests for every requirement

El archivo tiene tres trabajos principales:

Seleccionar el esquema por defecto.
Inyectar contexto de proyecto en las instrucciones de cada artefacto.
Inyectar reglas extra en artefactos específicos por ID.

No añade artefactos nuevos ni cambia sus dependencias. Eso corresponde a un esquema.

Esta distinción da una regla útil:

Si quieres cambiar qué archivos existen, cambia el esquema.
Si quieres cambiar qué deben considerar los archivos generados, cambia la config.

Esquemas vs. Skills

Aquí fue donde me equivoqué después. Pensé que los esquemas también eran donde debería vivir todo el comportamiento del agente.

Los esquemas pueden contener plantillas e instrucciones para generar sus artefactos, pero no sustituyen a las skills.

Un esquema describe el modelo de planificación: IDs de artefacto, rutas de salida, plantillas y dependencias. Las skills generadas de OpenSpec le enseñan a la herramienta de IA cómo realizar acciones como propose, continue, apply, sync y archive.

Así que si quiero un nuevo security-review.md antes de las tareas, eso es un cambio de esquema.

Si quiero que mi agente de programación siga TDD al implementar, eso pertenece a una skill de implementación o a una instrucción de proyecto. Si meramente quiero que cada lista de tareas generada mencione pruebas, una regla tasks en config.yaml puede ser suficiente.

Son preocupaciones relacionadas, pero viven en capas distintas, y mezclarlas fue la fuente de la mayor parte de mi confusión.

¿Archive evita la documentación obsoleta?

Esta fue la última cosa que no me podía sacudir.

Archive hace dos cosas útiles: mueve el cambio completado al historial y asegura que los delta specs se puedan sincronizar en los specs canónicos. Esto evita dejar varias versiones competidoras de los requisitos dispersas por las carpetas de cambios activos.

Lo que archive no hace es demostrar que el código coincide con la especificación.

La acción expandida /opsx:verify comprueba integridad, corrección y coherencia entre la implementación y los artefactos de planificación. Aun así, el proceso sigue dependiendo de la revisión y la disciplina de ingeniería. Ningún comando archive puede hacer verdadera una spec inexacta.

Así que OpenSpec reduce un tipo de desviación de documentación: documentos de requisito abandonados o competidores. No cierra por sí mismo la brecha entre la intención escrita y el software real. Esa parte sigue siendo tuya.

El modelo mental que por fin cuajó

Aquí está la versión que ahora guardo en mi cabeza:

Profile -> chooses the available workflow actions
Schema  -> defines the artifact dependency graph
Config  -> injects project context and artifact-specific rules
Skills  -> teach the agent how to perform those actions
Files   -> record the state of the change

O, como una frase:

OpenSpec instala un conjunto de acciones de agente, las ejecuta sobre un grafo definido por esquema, da forma a su salida con la config del proyecto y registra el progreso como archivos en tu repositorio.

Una vez que lo vi así, términos como perfil, esquema y artefacto dejaron de competir entre sí. Cada uno tenía una frontera clara.

Lo más difícil de OpenSpec no es el número de comandos. Es que palabras familiares cargan significados muy específicos dentro del sistema, y la documentación no siempre hace obvias esas fronteras. Si estás atascado en la terminología, no estás solo, me tomó un tiempo, y la mayor parte de este post es el camino que tomé para llegar aquí.