luismori.

OpenSpec Workflows · Parte 1

OpenSpec Spec-Driven Development AI Coding

Cómo empezar con OpenSpec: proyectos existentes, aplicaciones nuevas y primeros cambios comunes

Una guía práctica, respaldada por fuentes, para ingenieros y PMs que adoptan OpenSpec: cuándo empezar con un proyecto existente, cuándo usarlo para crear uno nuevo y cómo ejecutar el primer workflow de forma segura.

17 min de lectura Actualizado el 1 jul 2026

Resumen

  • OpenSpec es una capa ligera de desarrollo guiado por especificaciones para asistentes de programación con IA. Le da a tu equipo un lugar dentro del repositorio para registrar propuestas, especificaciones de comportamiento, diseño técnico, tareas y decisiones archivadas.
  • En proyectos existentes, no documentes toda la aplicación primero. La propia guía de OpenSpec para proyectos brownfield recomienda escribir especificaciones solo para la parte que estás por cambiar.
  • En proyectos nuevos, usa OpenSpec antes de que la primera rama de implementación se complique. La mayor ventaja es acordar el comportamiento, el alcance y las concesiones antes de que el asistente de IA convierta una idea vaga en código.
  • Hay dos lugares donde escribir comandos: openspec ... se ejecuta en la terminal; /opsx:... se ejecuta en el chat de tu asistente de IA.
  • El ciclo inicial predeterminado es:
TERMINAL   npm install -g @fission-ai/openspec@latest
TERMINAL   cd your-project && openspec init
AI CHAT    /opsx:explore       # optional, when unclear
AI CHAT    /opsx:propose ...
AI CHAT    /opsx:apply
AI CHAT    /opsx:archive
  • Mi recomendación general:
    • producto existente: empieza con un cambio real y pequeño
    • producto nuevo: empieza con una funcionalidad acotada de extremo a extremo
    • idea poco clara: empieza con /opsx:explore
    • idea clara: empieza con /opsx:propose

Qué aprenderás aquí

Al terminar este artículo, deberías poder:

  • explicar qué aporta OpenSpec al chat habitual con un asistente de programación con IA
  • instalar e inicializar OpenSpec sin confundir los comandos de la terminal con los del chat
  • elegir el primer workflow adecuado para una aplicación existente o una nueva
  • ejecutar un primer cambio realista, como limitar la tasa de solicitudes o permitir compras como invitado
  • entender qué archivos crea OpenSpec y por qué deben estar en git
  • evitar los errores de adopción más comunes para ingenieros y PMs

El July 1, 2026, revisé el README y la documentación vigentes de OpenSpec sobre instalación, primeros pasos, proyectos existentes, workflows, herramientas compatibles y personalización. Los nombres de comandos, la estructura de directorios, el modelo de especificaciones delta, el comportamiento de las herramientas compatibles y las recomendaciones para proyectos brownfield que aparecen a continuación están respaldados por esas fuentes. La secuencia de adopción y las recomendaciones para el trabajo en equipo son mi síntesis para equipos de ingeniería y producto.

Para una comparación más amplia con GitHub Spec Kit, empieza por OpenSpec vs GitHub Spec Kit. Este artículo es más práctico: explica cómo empezar a usar OpenSpec sin convertirlo en una ceremonia de planificación.

El problema que resuelve OpenSpec

Los asistentes de programación con IA son buenos para convertir un prompt en código. Eso es útil, pero crea un problema nuevo:

chat idea
  -> generated code
  -> reviewer asks "is this actually what we agreed to build?"
  -> more chat
  -> more code
  -> intent disappears

OpenSpec agrega una pequeña capa entre la idea y el código:

idea
  -> proposal
  -> behavior specs
  -> design
  -> tasks
  -> implementation
  -> archived spec history

Esa capa les da a los ingenieros una base concreta sobre la cual construir y a los PMs algo concreto que revisar antes de que la implementación se vuelva costosa.

El propio README de OpenSpec describe el proyecto como fluido, iterativo, fácil de usar y creado tanto para proyectos brownfield como greenfield. En este artículo, cuando digo que el workflow es «ligero», lo comparo con procesos de especificación más pesados y con etapas sujetas a aprobación: lo respaldado por las fuentes es que el perfil core predeterminado de OpenSpec limita el ciclo a explore, propose, apply, sync y archive; mi valoración es que eso lo hace adecuado para ciertos equipos.

El modelo mental

OpenSpec tiene dos directorios principales:

openspec/
|-- specs/
|   `-- <domain>/spec.md        # current system behavior
`-- changes/
    `-- <change-name>/
        |-- proposal.md         # why and what
        |-- design.md           # how
        |-- tasks.md            # implementation checklist
        `-- specs/
            `-- <domain>/spec.md # delta: ADDED/MODIFIED/REMOVED

La idea importante son las especificaciones delta. Un cambio no necesita describir todo el sistema. Describe lo que se agrega, modifica o elimina.

current behavior
      +
change delta
      =
updated behavior after archive

Por eso OpenSpec es especialmente interesante para bases de código existentes. Puedes empezar con un directorio openspec/specs/ casi vacío y hacerlo útil con cada cambio real.

Primera decisión: ¿proyecto existente o nuevo?

Usa este flujo de decisión rápido:

Are you adding OpenSpec to an app that already exists?
      |
      |-- yes
      |   `-- pick one small real change
      |       use /opsx:explore if the code path is unclear
      |       write only the delta for the touched area
      |
      `-- no
          `-- pick one thin end-to-end capability
              use /opsx:propose to shape the first build
              avoid designing every future feature upfront

En un proyecto existente

Usa OpenSpec para hacer un cambio con mayor seguridad:

"Add rate limiting to public API routes"
"Add guest checkout"
"Fix login redirect after SSO"
"Add audit log export"

No empieces con esto:

"Document our entire platform"
"Create specs for every service"
"Reverse-engineer every feature before we ship again"

Esas opciones parecen responsables. En la práctica, suelen generar especificaciones desactualizadas en las que nadie confía.

En un proyecto nuevo

Usa OpenSpec para proteger la primera implementación de un alcance ambiguo:

"Build a team bookmarks app with login, shared collections, and search"

Luego define el alcance de la primera parte funcional:

"Users can create a workspace, add one bookmark, and see it in a list"

Esto le da al asistente de IA un sistema pequeño que puede hacer realidad, sin cerrar la puerta a futuros cambios con OpenSpec.

Instalación e inicialización

Actualmente, OpenSpec requiere Node.js 20.19.0 o superior.

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

Luego inicialízalo dentro de tu proyecto:

cd your-project
openspec init

Si quieres automatizar la configuración para herramientas específicas:

openspec init --tools cursor,claude

La documentación de herramientas compatibles de OpenSpec también describe --tools all, --tools none y la opción --profile. El perfil predeterminado es core, que incluye:

  • /opsx:explore
  • /opsx:propose
  • /opsx:apply
  • /opsx:sync
  • /opsx:archive

Los workflows ampliados agregan:

  • /opsx:new
  • /opsx:continue
  • /opsx:ff
  • /opsx:verify
  • /opsx:bulk-archive
  • /opsx:onboard

Activa los workflows ampliados cuando quieras un control más explícito:

openspec config profile
openspec update

Una salvedad técnica: las skills y los comandos generados dependen del perfil y de la herramienta. Una configuración de Cursor, una de Claude Code y una con --tools none no crearán los mismos archivos. Toma las rutas de este artículo como ejemplos representativos y revisa los directorios generados antes de hacer commit.

No confundas los comandos de terminal con los del chat

Este es el tropiezo más común al principio.

TERMINAL commands
  openspec init
  openspec update
  openspec list
  openspec show <change>
  openspec validate <change>

AI CHAT commands
  /opsx:explore
  /opsx:propose add-rate-limiting
  /opsx:apply
  /opsx:archive

No hay una aplicación de chat independiente para OpenSpec. Escribes /opsx:... en el mismo chat del asistente de programación con IA donde normalmente pedirías código.

Workflow 1: agregar OpenSpec a un proyecto existente

Escenario:

Mantienes una API existente. Quieres agregar un límite de tasa a las rutas públicas, pero no tienes claro cómo pasan las solicitudes por la cadena de middleware.

Paso 1: inicializa OpenSpec

cd api-service
openspec init --tools cursor

Haz commit de los archivos de OpenSpec y los comandos para las herramientas que se generaron en la misma rama donde introduces el workflow. Si tu repositorio tiene reglas estrictas de revisión, primero crea un PR pequeño de configuración.

Paso 2: explora antes de proponer

En el chat de IA:

/opsx:explore

Luego hazle la pregunta concreta:

I need to add rate limiting to public API routes.
Please inspect the routing and middleware flow first.
Do not write code yet.
Tell me where the clean insertion point is and what risks exist.

Resultado esperado:

Request path:
  edge proxy
    -> Express app
    -> request logging
    -> auth middleware
    -> route handlers

Candidate insertion points:
  1. Before auth: protects auth endpoints too, but may rate-limit login incorrectly
  2. After auth: user-aware limits, but public anonymous routes need IP fallback
  3. Per-router middleware: more explicit, more repeated config

/opsx:explore no crea artefactos. Ese es el objetivo. Es un paso para pensar antes de que OpenSpec te comprometa con una carpeta de cambio.

Paso 3: propone un cambio pequeño

/opsx:propose add-public-api-rate-limiting

Pide el alcance que realmente quieres:

Scope this as a small first change:
- Add IP-based rate limiting to unauthenticated public API routes
- Do not change authenticated user quotas yet
- Add a clear 429 response contract
- Include tests for normal, near-limit, and over-limit requests

OpenSpec debería crear algo como esto:

openspec/changes/add-public-api-rate-limiting/
|-- proposal.md
|-- design.md
|-- tasks.md
`-- specs/api/spec.md

Paso 4: revisa los artefactos

Para los PMs, revisen proposal.md y los escenarios de la especificación delta:

## ADDED Requirements

### Requirement: Public API Rate Limiting
The system SHALL limit unauthenticated public API requests by client IP.

#### Scenario: Over-limit request
- GIVEN an unauthenticated client has exceeded the request limit
- WHEN the client calls a public API route
- THEN the system returns HTTP 429
- AND the response includes retry guidance

Para los ingenieros, revisen design.md y tasks.md:

Does this match the actual middleware stack?
Does the 429 response contract match API conventions?
Are tests attached to behavior, not implementation details?
Is the rollout reversible?

Antes de pasar a /opsx:apply, usa una lista breve de revisión:

Scope
  [ ] Is this one logical change?
  [ ] Are non-goals explicit?

Behavior
  [ ] Does the delta spec describe user-visible behavior?
  [ ] Are edge cases written as scenarios?

Implementation
  [ ] Does design.md match the actual code path?
  [ ] Are tasks small enough to review?
  [ ] Is there a validation command or test plan?

Paso 5: aplica, verifica y archiva

/opsx:apply

Si usas los workflows ampliados:

/opsx:verify

Luego termina:

/opsx:archive

Después de archivar, la especificación delta pasa a formar parte de la biblioteca principal de comportamiento en openspec/specs/api/spec.md, y el cambio se mueve a openspec/changes/archive/.

Workflow 2: iniciar un proyecto nuevo con OpenSpec

Escenario:

Quieres crear una pequeña herramienta interna para los marcadores del equipo. Los ingenieros quieren una primera parte funcional bien definida; los PMs quieren evitar desarrollar búsqueda, permisos, importación/exportación y analítica antes de validar el comportamiento principal.

Paso 1: crea el proyecto

mkdir team-bookmarks
cd team-bookmarks
git init
npm init -y
openspec init --tools cursor

Si aún no se ha elegido el framework de la aplicación, usa primero /opsx:explore:

/opsx:explore

Prompt:

We need a small internal team bookmarks app.
Compare a simple Astro + API route approach vs Next.js vs a lightweight Express backend.
Focus on what lets us ship the first authenticated bookmark flow fastest.
Do not create files yet.

Paso 2: propone una primera parte funcional acotada

/opsx:propose team-bookmarks-mvp

Prompt:

Create the MVP spec for:
- A user can create one workspace
- A user can add a bookmark with title and URL
- A user can see bookmarks in a list
- No sharing, tags, import/export, or full-text search yet
- Keep the implementation small enough for one PR

El objetivo no es crear un plan de producto perfecto. Es construir una primera parte funcional que le permita al equipo aprender si la arquitectura y el workflow están funcionando.

Paso 3: usa los artefactos como puntos de revisión

Revisión de producto:

proposal.md
  -> is the MVP scope right?

specs/bookmarks/spec.md
  -> are the user-visible behaviors correct?

tasks.md
  -> is the PR small enough to review?

Revisión de ingeniería:

design.md
  -> is the stack choice explicit?
  -> are persistence and auth boundaries clear?

tasks.md
  -> can backend, UI, and tests run in parallel?
  -> is there a validation path before archive?

Paso 4: aplica y archiva

/opsx:apply
/opsx:archive

Ahora el proyecto nuevo tiene tanto código como su primer historial de especificaciones. Las funcionalidades futuras se convierten en nuevos cambios de OpenSpec:

add-tags
add-shared-workspaces
add-bookmark-search
add-import-from-browser-export

Cada uno puede tener su propio alcance y revisarse por separado.

Guía para escenarios comunes

Escenario A: tienes un bug, pero no una causa clara

Empieza con:

/opsx:explore

Úsalo como apoyo para el diagnóstico:

Users are sometimes redirected to the wrong page after login.
Trace the login callback and redirect logic.
Give me likely causes and the smallest change worth proposing.

Luego:

/opsx:propose fix-login-redirect-after-auth

Esto evita que escribas una especificación para el bug equivocado.

Escenario B: tienes una solicitud de funcionalidad clara

Omite la exploración si el alcance ya está claro:

/opsx:propose add-invoice-csv-export

Luego revisa:

proposal.md -> scope and non-goals
spec.md     -> export behavior and permissions
design.md   -> query, format, and performance choices
tasks.md    -> implementation checklist

Escenario C: ya tienes un PRD

No conviertas todo el PRD de una sola vez.

Úsalo como material de referencia para el cambio actual:

/opsx:explore

Prompt:

Here is the PRD section for guest checkout.
Extract only the requirements needed for the first implementation PR.
Identify open questions before we create an OpenSpec change.

Luego:

/opsx:propose add-guest-checkout

Escenario D: trabajas en un monorepo

Empieza de forma sencilla:

repo-root/
|-- apps/web/
|-- services/api/
|-- packages/ui/
`-- openspec/

Usa dominios que reflejen cómo piensa tu equipo:

openspec/specs/
|-- auth/spec.md
|-- checkout/spec.md
|-- search/spec.md
`-- admin/spec.md

Para la planificación que realmente abarca varios repositorios, OpenSpec tiene una funcionalidad beta llamada Stores. La consideraría prometedora, pero aún en evolución, y empezaría con un solo directorio openspec/ a nivel de repositorio, salvo que exista una necesidad real de coordinar varios repositorios.

Qué incluir en openspec/config.yaml

La configuración de proyecto de OpenSpec es el punto de personalización más sencillo para los equipos. Úsala para enseñarle al agente tu stack y tus reglas de revisión.

schema: spec-driven

context: |
  Tech stack: TypeScript, Astro, React islands, Tailwind CSS.
  Deployment: Cloudflare Pages static output.
  Testing: npm run build is required before article PRs.
  Content convention: user-facing text lives in content/ when possible.

rules:
  proposal:
    - Include explicit non-goals.
    - Identify affected user roles.
  specs:
    - Use Given/When/Then scenarios.
    - Separate current behavior from proposed changes.
  design:
    - Mention rollback or migration risk when state changes.
  tasks:
    - Keep tasks small enough for one reviewer to verify.

Mantén esta configuración útil, no enciclopédica. La documentación menciona un límite de contexto de 50KB, pero el límite práctico es la atención: cuanto más grande sea el contexto, más fácil será que las reglas importantes se pierdan entre el ruido.

Qué deben revisar los ingenieros y los PMs

              PM REVIEW                       ENGINEERING REVIEW
              ---------                       ------------------
proposal.md   problem, scope, non-goals        affected systems, rollout risk
spec.md       behavior, scenarios, edge cases  testability, current-vs-new behavior
design.md     trade-offs in plain language     architecture, dependencies, failure modes
tasks.md      delivery shape and review size   sequencing, parallel work, validation
archive       decision history                 future maintenance context

El objetivo no es que los PMs lean detalles de implementación ni que los ingenieros reescriban el lenguaje de producto. Es darle a cada rol un lugar estable para corregir la parte de la que es responsable.

Plan de adopción para la primera semana

Si incorporara OpenSpec a un equipo real, no empezaría con un taller.

Haría lo siguiente:

Day 1
  initialize OpenSpec in a small branch
  add project config with minimal context

Day 2
  pick one real upcoming change
  run /opsx:explore if unclear
  run /opsx:propose

Day 3
  review proposal/spec/design/tasks with PM + engineer
  remove overreach
  clarify non-goals

Day 4
  run /opsx:apply
  adjust artifacts if implementation reveals reality was different

Day 5
  verify if using expanded profile
  archive
  merge the change
  write down what felt useful and what felt heavy

Después, decide si OpenSpec tiene sentido para:

  • cada funcionalidad de producto
  • solo las funcionalidades de riesgo
  • cambios brownfield con comportamiento poco claro
  • incorporación de nuevos integrantes y trabajo de ingeniería inversa
  • creación de la estructura inicial de proyectos nuevos

No lo impongas en todas partes hasta que los primeros cambios demuestren que el hábito funciona.

Errores comunes

Error 1: documentar toda la aplicación existente

La guía de OpenSpec para proyectos existentes es directa: no tienes que documentar toda la base de código para empezar. Documenta lo que estás por cambiar.

Error 2: tratar /opsx:propose como una aprobación para implementar

Una propuesta significa que el cambio tiene una forma definida. No significa que el alcance sea correcto. Revisa los artefactos antes de /opsx:apply.

Error 3: archivar sin reflejar la realidad

Si durante la implementación descubres que se necesita un diseño diferente, actualiza el artefacto antes de archivar. De lo contrario, openspec/specs/ reflejará aspiraciones en lugar del comportamiento real.

Error 4: ocultar las especificaciones al equipo de producto

Si los PMs solo ven el diff final del código, OpenSpec pierde la mitad de su valor. La especificación existe para que los comentarios de producto lleguen antes de que la revisión de código se convierta en el único punto de revisión.

Error 5: personalizar demasiado desde el primer día

Empieza con la configuración del proyecto. Recurre a esquemas personalizados cuando tengas evidencia repetida de que los artefactos predeterminados no se ajustan al proceso de tu equipo.

Cómo se relaciona esto con el artículo comparativo anterior

El artículo anterior comparó OpenSpec y GitHub Spec Kit lado a lado. En resumen:

  • OpenSpec destaca cuando quieres especificaciones vivas, cambios delta e iteración fluida.
  • Spec Kit destaca cuando quieres puntos de aprobación explícitos, conjuntos de artefactos más completos y catálogos de extensiones.

Para el caso de uso de este artículo - empezar en una base de código existente o en una aplicación nueva - la ventaja de OpenSpec es su curva de adopción. Puedes empezar con algo pequeño:

one repo
  -> one change
  -> one delta spec
  -> one archived decision

Eso basta para descubrir si el workflow ayuda a tu equipo.

Fuentes

Fuentes primarias revisadas el July 1, 2026:

  • Fission AI, README de OpenSpec - filosofía, inicio rápido, requisito de Node, workflows predeterminados y ampliados, notas de uso
  • Fission AI, Instalación - gestores de paquetes, requisito previo de Node.js 20.19+, comportamiento de actualización
  • Fission AI, Primeros pasos - comandos de terminal frente a comandos del chat de IA, primer ciclo, estructura de directorios, descripción de artefactos, comportamiento de archivo de especificaciones delta
  • Fission AI, Uso de OpenSpec en un proyecto existente - enfoque inicial para proyectos brownfield, evitar especificar toda la base de código, modelo del primer cambio real, nota sobre monorepos
  • Fission AI, Workflows - perfil core, workflows ampliados, /opsx:explore, /opsx:verify, comportamiento de archivo, criterio para actualizar o crear
  • Fission AI, Herramientas compatibles - skills y comandos generados, identificadores de herramientas compatibles, comportamiento de instalación según el perfil
  • Fission AI, Personalización - openspec/config.yaml, incorporación de contexto y reglas, esquemas personalizados, esquemas de la comunidad

Lecturas relacionadas en este sitio: