Iteracion: Agregando Drag and Drop

Donde OpenSpec realmente brilla

En los capitulos anteriores completamos el primer ciclo: propusimos el modelo de datos, generamos specs, implementamos, verificamos y archivamos. Ese flujo esta bien para entender la mecanica, pero no es donde OpenSpec se diferencia de otras herramientas.

La verdadera ventaja aparece cuando agregas funcionalidad a codigo que ya existe. Esto es lo que en la industria se llama brownfield development: no partes de cero, partes de algo que ya funciona.

La mayoria de frameworks de SDD asumen que empiezas un proyecto nuevo. OpenSpec fue disenado desde el inicio para el escenario real: tienes codigo, tienes specs, y necesitas agregar algo sin romper lo que ya funciona.

El estado actual del proyecto

Despues del primer ciclo, nuestro proyecto Kanban tiene:

• Specs archivadas en openspec/specs/ que describen el modelo de datos
• Contexto del proyecto en CLAUDE.md con las decisiones de arquitectura
• Codigo funcional con el backend y frontend del tablero basico
• Historial en openspec/changes/archive/ del cambio completado

Estos artefactos son la memoria institucional del proyecto. No importa si paso una hora o un mes desde el ultimo cambio: OpenSpec sabe exactamente en que estado esta todo.

Creando el segundo cambio

Ahora queremos que las tarjetas del Kanban se puedan arrastrar entre columnas. Creamos el cambio:

/opsx:propose add-drag-drop

Aqui ocurre algo que no pasaba en el primer ciclo: la IA no parte de una pizarra en blanco. Antes de generar la propuesta, OpenSpec le proporciona:

1. Contexto del proyecto via openspec instructions con informacion del stack y convenciones
2. Los specs existentes en openspec/specs/ del modelo de datos
3. El historial de cambios para entender la evolucion del proyecto

Esto significa que la propuesta ya conoce la estructura de las tarjetas, las columnas, las APIs existentes y las convenciones del proyecto.

La propuesta referencia lo existente

El proposal.md generado para add-drag-drop se ve diferente al del primer cambio. En lugar de describir todo desde cero, referencia los specs existentes:

Este cambio extiende el modelo de tarjetas definido en specs/kanban-board.spec.md para agregar capacidad de reordenamiento. Se reutiliza la API REST existente (PATCH /api/cards/:id) y se agrega un nuevo endpoint para actualizar posiciones en lote.

La propuesta no repite lo que ya esta especificado. Solo describe lo nuevo y lo que cambia. Esto es fundamentalmente diferente a pedirle a la IA “agrega drag and drop” en un chat sin contexto.

Delta specs: MODIFIED y ADDED

La fase de especificacion genera delta specs, que son los cambios incrementales a las especificaciones existentes. En este segundo ciclo aparecen dos tipos:

Tipo MODIFIED

Cuando un spec existente necesita actualizarse. Por ejemplo, el spec del tablero Kanban ya existe pero necesita nuevos escenarios:

# MODIFIED: kanban-board.spec.md

Feature: Tablero Kanban - Reordenamiento de tarjetas

  # Escenarios existentes se mantienen sin cambios

  # Nuevo escenario agregado
  Scenario: Reordenar tarjeta dentro de la misma columna
    Given una columna "En Progreso" con tarjetas ["A", "B", "C"]
    When el usuario mueve la tarjeta "C" a la posicion 1
    Then el orden de las tarjetas es ["C", "A", "B"]
    And se persiste el nuevo orden via API

Tipo ADDED

Cuando se necesita un spec completamente nuevo que no existia antes:

# ADDED: drag-drop-interaction.spec.md

Feature: Interaccion Drag and Drop

  Scenario: Mover tarjeta entre columnas
    Given una tarjeta en la columna "Pendiente"
    When el usuario arrastra la tarjeta a la columna "En Progreso"
    Then la tarjeta aparece en "En Progreso"
    And desaparece de "Pendiente"
    And se actualiza el estado en el backend

  Scenario: Indicador visual durante arrastre
    Given el usuario esta arrastrando una tarjeta
    When pasa sobre una columna valida
    Then la columna muestra un indicador de destino

Esta distincion MODIFIED/ADDED es clave: permite rastrear exactamente que cambio en las especificaciones con cada iteracion.

Design.md considera la implementacion existente

El archivo design.md de este segundo cambio no redisena la arquitectura desde cero. En su lugar:

• Identifica que componentes existentes se veran afectados
• Propone como integrar la nueva funcionalidad sin reestructurar
• Senala dependencias entre el codigo nuevo y el existente
• Recomienda librerias o patrones compatibles con la stack actual

Por ejemplo, si el frontend usa React sin ninguna libreria de drag and drop, el design sugiere una opcion ligera. Si ya hay un patron de manejo de estado, lo reutiliza.

Tasks.md: modificar, no crear desde cero

Las tareas generadas reflejan que estamos trabajando sobre codigo existente:

## Tareas

- [ ] Actualizar el modelo Card para incluir campo `position` (number)
- [ ] Agregar endpoint PATCH /api/cards/reorder para actualizacion en lote
- [ ] Instalar dependencia de drag and drop (@dnd-kit/core)
- [ ] Modificar componente KanbanColumn para aceptar drop targets
- [ ] Modificar componente KanbanCard para ser draggable
- [ ] Agregar logica de reordenamiento en el store de estado
- [ ] Actualizar tests existentes con los nuevos escenarios

Nota la diferencia: las tareas dicen “actualizar”, “modificar”, “agregar”. No dicen “crear componente KanbanCard” porque ya existe. OpenSpec sabe que archivos ya estan en el proyecto.

Aplicar el segundo cambio

/opsx:apply

La IA recibe las delta specs, el design y las tareas. Implementa los cambios tocando los archivos existentes y creando solo los nuevos que sean necesarios.

La ventaja respecto al primer ciclo es que la IA no tiene que adivinar como esta organizado el proyecto. Los specs le dicen:

• Que estructura tiene el modelo de datos
• Que API existe y como se usa
• Que componentes hay y como interactuan
• Que patrones y convenciones se siguen

Verificar y archivar

/opsx:verify

La verificacion compara la implementacion contra las delta specs. Si todos los escenarios Gherkin estan cubiertos, el cambio esta listo.

/opsx:archive add-drag-drop

Al archivar, OpenSpec:

1. Fusiona las delta specs con los specs principales
2. El spec MODIFIED actualiza el archivo existente en openspec/specs/
3. El spec ADDED crea un nuevo archivo en openspec/specs/
4. Mueve la carpeta del cambio a openspec/changes/archive/

Como evolucionaron los specs

Despues de dos ciclos, el directorio openspec/specs/ contiene:

openspec/specs/
  kanban-board.spec.md     # Original + escenarios de reordenamiento
  drag-drop-interaction.spec.md  # Nuevo spec del segundo ciclo

El archivo kanban-board.spec.md ahora incluye tanto los escenarios originales del modelo de datos como los nuevos escenarios de reordenamiento. Los specs crecen organicamente con el proyecto.

La ventaja brownfield

El patron que acabamos de seguir tiene una propiedad fundamental:

OpenSpec no necesita “re-entender” todo el proyecto en cada cambio.

Con un chat de IA convencional, cada vez que inicias una conversacion nueva, tienes que explicarle el contexto. Con OpenSpec, el contexto esta en los artefactos:

Fuente	Que aporta al contexto
CLAUDE.md / contexto IDE	Vision, stack, convenciones
openspec/specs/	Comportamiento actual especificado
openspec/changes/archive/	Historia de como llego a este estado
Delta specs del cambio	Que se quiere cambiar ahora

Esto significa que puedes retomar un proyecto despues de semanas, ejecutar /opsx:propose y obtener una propuesta que respeta todo lo que ya existe.

Resumen

• OpenSpec brilla en brownfield: agregar features a codigo existente
• La IA lee los specs existentes antes de generar la propuesta
• Las delta specs distinguen entre MODIFIED (actualizar) y ADDED (nuevo)
• El design y las tareas modifican codigo existente, no parten de cero
• Despues de archivar, los specs evolucionan reflejando el estado actual
• No necesitas re-explicar el proyecto: los artefactos son la memoria

---

Capitulo 7: Verificacion y Archivo | Capitulo 9: Cambios Paralelos y Conflictos