Ejemplos y Recetas

Cambios reales, de principio a fin. Cada receta muestra los comandos que escribirías y lo que verías de vuelta, para que puedas igualar tu situación a un patrón y copiarlo. Estas usan los comandos centrales predeterminados (propose, explore, apply, update, sync, archive); donde el conjunto ampliado ayuda, se nota.

Un recordatorio antes de empezar: los comandos de barra como /opsx:propose van en el chat de tu asistente de IA, y los comandos openspec van en tu terminal. Si eso es nuevo, lee Cómo funcionan los comandos primero. En las transcripciones de abajo, Tú: y IA: son el chat, y las líneas que comienzan con $ son la terminal.

¿No estás seguro de lo que estás construyendo todavía? La mayoría de estas recetas son más nítidas si empiezas con /opsx:explore para pensarlo primero. Receta 3 lo muestra en acción, y la guía Explora primero expone el caso completo.

Receta 1: Una pequeña característica, el camino rápido

Cuándo usarlo: sabes lo que quieres, y es una pieza de trabajo contenida. Esta es la receta más común.

Todo son tres comandos. Propón, construye, archiva.

You: /opsx:propose add-logout-button

AI:  Created openspec/changes/add-logout-button/
     ✓ proposal.md — why and what
     ✓ specs/      — the new requirement and its scenarios
     ✓ design.md   — technical approach
     ✓ tasks.md    — implementation checklist
     Ready for implementation. Run /opsx:apply.

Ahora lee el plan. Abre la propuesta y el spec delta. Este es el momento para el que OpenSpec está construido: detectar una suposición incorrecta cuando aún es un párrafo, no 400 líneas de código. Edita cualquier artefacto directamente si algo no está bien, luego continúa.

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Add logout button to header
     ✓ 1.2 Clear session on click
     ✓ 1.3 Add confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  Archiving add-logout-button...
     ✓ Merged specs into openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
     Done. Ready for the next change.

Eso es todo. El comportamiento de cierre de sesión ahora es parte de tus specs, y el cambio se archiva con su contexto completo.

Receta 2: Una corrección de errores

Cuándo usarlo: algo está roto y quieres que la corrección quede registrada como un cambio deliberado en el comportamiento, no como un commit misterioso.

Las correcciones de errores funcionan exactamente igual que las características. La diferencia está en cómo enmarcas la propuesta: describe el comportamiento correcto, no solo "arregla el error".

You: /opsx:propose fix-login-redirect-loop

AI:  Created openspec/changes/fix-login-redirect-loop/
     The proposal captures the current broken behavior and the
     intended behavior. The delta spec MODIFIES the redirect
     requirement so it's now precise and testable.
     Ready for implementation.

Debido a que la corrección aterriza como un requisito MODIFIED con un escenario nuevo, la próxima persona (o la próxima sesión de IA) ve no solo que lo arreglaste, sino qué significa "correcto". Luego, /opsx:apply y /opsx:archive como de costumbre.

Consejo: para una corrección, un buen escenario es la prueba de regresión en prosa. "DADO un usuario no autenticado, CUANDO envía credenciales válidas, ENTONCES llega al panel y no es redirigido de nuevo." Escríbelo, y la implementación tiene un objetivo claro.

Receta 3: Explorando antes de comprometerse

Cuándo usarlo: tienes un problema pero aún no un plan. No estás seguro de qué construir o cuál es el enfoque correcto.

Empieza con /opsx:explore. Es un compañero de pensamiento sin estructura y sin artefactos creados. Lee tu base de código y te ayuda a decidir.

You: /opsx:explore

AI:  What would you like to explore?

You: Page loads feel slow but I don't know where the time goes.

AI:  Let me look... I found three likely culprits:
     1. Large unoptimized images on the product list
     2. Synchronous data fetching that blocks render
     3. Re-renders triggered by context changes
     Which should we tackle first?

You: The data fetching one.

You: /opsx:propose optimize-product-list-fetching

AI:  Created the change, with a proposal informed by what we just
     found. Ready for implementation.

La exploración aclara tu pensamiento antes de que gastes un cambio en ello. Cuando la idea cristaliza, propón, y la IA lleva el contexto hacia adelante.

Receta 4: Manejando dos cambios a la vez

Cuándo usarlo: estás a mitad de una característica y una corrección urgente se adelanta en la fila.

Los cambios son carpetas independientes, por lo que el trabajo en paralelo no entra en conflicto. Empieza la corrección, envíala, luego vuelve a la característica justo donde la dejaste.

You: I'm partway through add-dark-mode, but I need to fix a login bug now.

You: /opsx:propose fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.

You: /opsx:apply

AI:  Implemented the fix. All tasks complete.

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect.

You: Back to dark mode.

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...

Nombrar el cambio en /opsx:apply add-dark-mode es cómo apuntas a la IA a un cambio específico cuando hay más de uno activo. Debido a que las tareas rastrean la finalización en tasks.md, la IA sabe exactamente dónde te detuviste.

Cuando se completan varios cambios a la vez, el /opsx:bulk-archive ampliado los archiva juntos y resuelve conflictos de spec verificando lo que realmente se ha implementado. Consulta Flujos de trabajo.

Receta 5: Un refactor sin cambio de comportamiento

Cuándo usarlo: estás reestructurando código, y el comportamiento visible externamente debe permanecer idéntico.

Este es el caso interesante, porque un refactor puro tiene nada que agregar a tus specs. El contrato de comportamiento no cambia; solo la implementación. Así que el trabajo vive en el diseño y las tareas, y el delta de spec está vacío o ausente.

You: /opsx:propose refactor-payment-module

AI:  Created the change. The proposal states the goal (split the
     payment module, no behavior change) and the design captures
     the new structure. No spec changes, since behavior is identical.
     Ready for implementation.

Declara el delta vacío explícitamente estableciendo skip_specs: true en el .openspec.yaml del cambio:

schema: spec-driven
skip_specs: true

Sin el marcador, openspec validate rechaza un cambio con cero deltas (para que una fase de specs olvidada aún se detecte); con él, la validación pasa y openspec status muestra la etapa de specs como omitida explícitamente en lugar de pendiente. Si el refactor resulta cambiar el comportamiento después de todo, elimina skip_specs de .openspec.yaml y escribe los deltas de spec — validate trata el marcador más los archivos de spec como un conflicto, por lo que el marcador obsoleto no puede permanecer en silencio.

Archivar un cambio marcado no necesita banderas adicionales (no hay deltas para fusionar). Independientemente, la bandera --skip-specs le dice al comando de terminal que omita el paso de spec explícitamente:

$ openspec archive refactor-payment-module --skip-specs

La misma bandera es útil para herramientas, CI y cambios solo de documentos. El principio: los specs describen el comportamiento, así que si el comportamiento no cambió, el spec tampoco debería. Consulta Conceptos.

Receta 6: Control paso a paso (comandos ampliados)

Cuándo usarlo: un cambio complejo o arriesgado donde quieras revisar cada artefacto antes de continuar.

El núcleo /opsx:propose redacta todo de una vez. Cuando prefieras ir paso a paso, activa los comandos ampliados:

$ openspec config profile      # select the expanded workflows
$ openspec update              # apply them to this project

Ahora puedes crear el esqueleto y construir incrementalmente:

You: /opsx:new add-2fa

AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.

You: /opsx:continue

AI:  Created proposal.md. Now available: specs, design.

You: /opsx:continue

AI:  Created specs/auth/spec.md. Now available: design.

Revisa cada artefacto a medida que llega, edítalo libremente y continúa cuando estés contento. Cuando quieras que el resto se redacte de una vez, /opsx:ff avanza rápidamente a través de los artefactos de planificación restantes. Antes de archivar, /opsx:verify verifica que la implementación realmente coincida con los specs. Consulta Flujos de trabajo.

Receta 7: Aprendiendo todo el ciclo en la práctica

Cuándo usarlo: has instalado OpenSpec y quieres sentir el flujo de trabajo en tu propio código, no en un ejemplo de juguete.

Activa los comandos ampliados (ver Receta 6), luego:

You: /opsx:onboard

AI:  Welcome to OpenSpec! I'll walk you through a complete change
     using your actual codebase. Let me scan for a small, safe
     improvement we can make together...

/opsx:onboard encuentra una mejora real (pequeña), crea un cambio para ella, lo implementa, lo archiva, narrando cada paso. Toma de 15 a 30 minutos y te deja con un cambio real que puedes conservar o descartar. Es la forma más suave de aprender. Consulta Comandos.

Verificando tu trabajo desde la terminal

En cualquier momento, desde tu terminal, puedes inspeccionar el estado de las cosas:

$ openspec list                      # active changes
$ openspec show add-dark-mode        # one change in detail
$ openspec validate add-dark-mode    # check structure
$ openspec view                      # interactive dashboard

Estas son herramientas de lectura e inspección. La propuesta y la construcción aún ocurren a través de comandos de barra en el chat. Detalles completos en la referencia de la CLI.

Dónde ir a continuación

• Explora Primero: la forma recomendada de empezar cuando no estás seguro
• Flujos de trabajo: los patrones anteriores, con guía de decisión sobre cuándo usar cada uno
• Comandos: cada comando de barra en detalle
• Cómo Empezar: el recorrido canónico del primer cambio
• Conceptos: por qué las piezas encajan de la manera que lo hacen