Uso en el Mundo Real: Nuevas Funcionalidades, Corrección de Bugs, Agregar OpenSpec a Proyectos Existentes

Los primeros cuatro artículos cubrieron los conceptos y el flujo de trabajo de OpenSpec con suficiente claridad, pero "saber cómo ejecutarlo" y "saber por dónde empezar cuando comienza el trabajo real" son dos cosas diferentes. Este artículo usa los tres escenarios más comunes como plantillas, cada uno con su propio playbook correspondiente.

Escenario 1: Desarrollar una Nueva Funcionalidad

Este es el caso de uso más estándar de OpenSpec. Tres comandos lo resuelven:

Playbook: explore (opcional) → propose → apply → archive

Si los requisitos todavía no están claros, empieza con explore:

/opsx:explore Users are reporting that search results are sorted incorrectly — what could be causing this?

La IA revisará la base de código, explicará la lógica existente y te ayudará a decidir qué cambiar. Una vez que tengas clara la dirección, propone:

/opsx:propose fix-search-ranking

La IA genera cuatro artifacts. Revisa cuidadosamente proposal.md y el delta en specs/, confirmando "sí, estos son exactamente los comportamientos que estamos cambiando" — no te saltes este paso. El costo de descubrir una dirección incorrecta después de la implementación es mucho mayor que cinco minutos de revisión aquí.

Confirma que todo se ve bien, luego /opsx:apply para implementar y /opsx:archive para cerrar.

Error común para principiantes: Ejecutar apply inmediatamente después de propose sin revisar los artifacts. La propuesta y las tareas generadas a veces pueden desviarse de lo que tenías en mente, especialmente cuando tu descripción del requisito era vaga. Cinco minutos de revisión ahorran mucho más que rehacer una implementación incorrecta.

Escenario 2: Corregir un Bug

Las correcciones de bugs siguen casi el mismo flujo de trabajo que las nuevas funcionalidades, con una diferencia clave — entiende la causa raíz antes de proponer. No te apresures a proponer.

Playbook: explore (definir el problema) → propose → apply → archive

Empieza usando explore para articular el problema:

/opsx:explore Users occasionally lose their session after logging in, especially on Safari. How does the current session management logic work?

Una vez que la IA haya revisado la base de código y tengas un entendimiento compartido de la causa raíz, entonces propone:

/opsx:propose fix-safari-session-expiry

El proposal.md aquí debería indicar claramente: cuál es la causa raíz, qué comportamiento se está corrigiendo y cómo se ve cuando está "terminado." En el delta spec, si la spec existente ya describe el comportamiento de sesión, este cambio probablemente será MODIFIED.

¿Por qué ejecutar las correcciones de bugs a través de OpenSpec? Porque una vez corregido, el comportamiento reparado se convierte en el nuevo estado actual del sistema y debería reflejarse en la spec. La próxima vez que alguien trabaje en la misma funcionalidad, verá en la spec que esta área tiene historial de correcciones y antecedentes de decisiones — mucho más fácil que buscar en git blame para encontrar mensajes de commit.

Escenario 3: Agregar OpenSpec a un Proyecto Existente

Tienes un proyecto existente sin ninguna spec y quieres incorporar OpenSpec — no necesitas documentar todo antes de empezar a usarlo. Agregar cobertura de forma incremental a medida que trabajas es el enfoque correcto.

Playbook: init → crear un change para la primera modificación → ejecutar OpenSpec para cada cambio posterior → las specs crecen naturalmente

Después de instalar e inicializar, no intentes escribir specs para todo el sistema a la vez — eso se convierte en otro bloqueo del tipo "déjame terminar la documentación antes de poder hacer cualquier trabajo."

El enfoque correcto: la próxima vez que agregues una funcionalidad o corrijas un bug, ejecútalo a través de OpenSpec. Cuando se ejecute /opsx:propose, el delta spec generado por la IA describirá los comportamientos involucrados en el cambio, y después de archivarlos aterrizarán en openspec/specs/. Eso es todo — un poco de cobertura agregada con cada cambio, y las specs se van llenando gradualmente.

Si quieres documentar proactivamente algunos dominios principales, puedes decirle a la IA:

/opsx:explore Analyze the src/auth/ directory and summarize the existing authentication behaviors in preparation for writing openspec/specs/auth/spec.md

Después de que la IA revise la base de código, puedes pedirle que genere el archivo de spec inicial y lo coloque en openspec/specs/. No necesita ser perfecto — con capturar los comportamientos principales es suficiente.

El bloqueo mental común con proyectos legacy: "¿Es demasiado tarde para empezar ahora?" No lo es. Empieza hoy y la próxima funcionalidad ya tiene una pista de despegue. No empezar, y un año después seguirás adivinando hacia dónde se fue la IA. Desde el primer propose, estás en el camino correcto.

Avanzado: Múltiples Cambios en Paralelo

Si tienes dos funcionalidades en desarrollo al mismo tiempo — sin problema, OpenSpec lo soporta:

openspec/changes/
├── add-dark-mode/        ← tú estás trabajando en esto
└── fix-search-ranking/   ← un compañero de equipo está trabajando en esto

Los artifacts de cada change se mantienen en su propia carpeta y no entran en conflicto. Al archivar, cada delta spec se fusiona en su spec de dominio correspondiente de forma independiente.

Para colaboración en equipo, usa comandos CLI para verificar el estado:

openspec list                    # Listar todos los cambios en progreso
openspec show add-dark-mode      # Ver detalles de un cambio específico

Guarda Esta Tabla a Mano

Después de cinco artículos, ahora tienes un flujo de trabajo reutilizable de OpenSpec. La próxima vez que estés a punto de decirle a la IA que se ponga a trabajar, dedica diez minutos a /opsx:propose primero, confirma que los artifacts se ven bien, luego aplica — solo esa disciplina casi con certeza costará menos que corregir una dirección incorrecta después.

Volver al índice de la serie: Guía para Principiantes de OpenSpec: 5 Artículos para Dominar la Gestión de Especificaciones en el Desarrollo con IA