← Volver al listado de tecnologías ← Índice de OpenSpec

Primer Cambio con Propose

Por: Artiko
openspeccambiomodelo-datospropose

Primer Cambio con Propose

Que es un “cambio” en OpenSpec

Un cambio (change) es la unidad atomica de trabajo en OpenSpec. Cada cambio representa una funcionalidad, mejora o correccion que quieres implementar. Lo importante: cada cambio vive en su propia carpeta aislada dentro de changes/, con todos sus artefactos de planificacion.

Un cambio sigue un ciclo de vida claro:

  1. Propose - Definir que quieres hacer y generar artefactos
  2. Apply - Implementar las tareas
  3. Archive - Fusionar specs y cerrar

Creando el primer cambio

Con el perfil Core, usas /opsx:propose seguido de un nombre o descripcion:

/opsx:propose setup-data-model

Referencia: /opsx:propose

Sintaxis: /opsx:propose [nombre-o-descripcion]

ArgumentoRequeridoDescripcion
nombre-o-descripcionNoNombre en kebab-case o descripcion libre del cambio

Si proporcionas un nombre, lo usa directamente. Si proporcionas una descripcion (ej: “agregar autenticacion con OAuth2”), la IA deriva un nombre en kebab-case automaticamente. Si no proporcionas nada, la IA te pregunta que quieres construir.

El identificador debe ser corto, en kebab-case y describir la intencion del cambio. Buenos ejemplos:

Que hace /opsx:propose

A diferencia del flujo anterior donde tenias que ejecutar multiples comandos, /opsx:propose hace todo en un paso:

  1. Crea el directorio del cambio con openspec new change "<nombre>"
  2. Consulta openspec status para entender el schema y las dependencias
  3. Genera cada artefacto en orden usando openspec instructions
  4. Verifica que todos los artefactos necesarios estan completos

Al terminar, tienes un cambio listo para implementar.

Estructura generada

Despues de /opsx:propose setup-data-model, la carpeta del cambio queda completa:

changes/
  setup-data-model/
    .openspec.yaml   # Metadata (schema, estado)
    proposal.md      # El "que" y "por que"
    design.md        # El "como"
    tasks.md         # Lista de tareas
    specs/           # Delta specs
      data-model/
        spec.md

Los 4 artefactos del cambio

1. proposal.md (Que y por que)

El proposal justifica el cambio y delimita su alcance:

# Proposal: Setup Data Model

## Motivacion
El proyecto Kanban necesita un modelo de datos que soporte
tableros, columnas y tarjetas.

## Alcance
- Definir tablas para Board, Column y Card
- Establecer relaciones entre entidades
- Migraciones de base de datos

## Fuera de alcance
- Autenticacion y modelo de usuarios
- Drag and drop en frontend
- API REST para CRUD

## Riesgos
- La eleccion del esquema impacta todos los cambios futuros
- El campo de posicion necesita estrategia de reordenamiento

2. Delta Specs (Que exactamente)

Las delta specs definen los requisitos formales con marcadores de cambio:

Cada requisito incluye escenarios Gherkin:

## Board Entity [ADDED]

### REQ-001: Board creation

GIVEN a valid board name and owner_id
WHEN creating a new board
THEN the board is persisted with name, description,
     owner_id and timestamps

3. design.md (Como)

Documenta las decisiones tecnicas no obvias:

# Design: Setup Data Model

## Decision: ORM y Migraciones
Usamos Drizzle ORM por alineacion con el stack
definido en el proyecto.

## Estructura de archivos
- src/db/schema/board.ts
- src/db/schema/column.ts
- src/db/schema/card.ts

## Decisiones clave
- Posiciones con enteros (migracion a fractional indexing si es necesario)
- UUIDs como PK (optimistic updates futuros)

4. tasks.md (Pasos)

Lista de tareas atomicas con checkboxes:

# Tasks: Setup Data Model

- [ ] Crear esquema de Board en src/db/schema/board.ts
- [ ] Crear esquema de Column en src/db/schema/column.ts
- [ ] Crear esquema de Card en src/db/schema/card.ts
- [ ] Crear barrel export en src/db/schema/index.ts
- [ ] Configurar conexion a BD en src/db/index.ts
- [ ] Generar y ejecutar migracion inicial

Como OpenSpec genera los artefactos

Cuando ejecutas /opsx:propose, la IA no inventa de la nada. Para cada artefacto:

  1. Ejecuta openspec instructions <artefacto> --change "<nombre>" --json
  2. Recibe contexto (informacion del proyecto), reglas (restricciones) y un template (estructura)
  3. Lee los artefactos completados como dependencias
  4. Genera el artefacto alineado con tu proyecto

Los artefactos forman una cadena de dependencias:

flowchart LR
    A["proposal.md\n(que/por que)"] --> B["delta specs\n(que exacto)"]
    B --> C["design.md\n(como)"]
    C --> D["tasks.md\n(pasos)"]

Revisar los artefactos

Los artefactos generados son borradores. Siempre debes revisarlos. Preguntas utiles:

Puedes editar cualquier archivo .md directamente con tu editor o pedirle a la IA que ajuste.

/opsx:explore vs /opsx:propose

OpenSpec ofrece dos formas de iniciar:

/opsx:explore

Modo exploratorio. Investiga ideas, analiza impacto y discute alternativas sin crear artefactos ni carpetas.

Sintaxis: /opsx:explore [pregunta-o-tema]

ArgumentoRequeridoDescripcion
pregunta-o-temaNoTema libre a explorar (conversacion abierta si se omite)

Explore es una postura, no un workflow. No tiene pasos fijos, secuencia obligatoria ni outputs requeridos. La IA puede leer archivos y analizar el codebase, pero nunca escribe codigo. Puede crear artefactos OpenSpec si lo pides (eso es capturar pensamiento, no implementar).

/opsx:explore Quiero agregar autenticacion con OAuth2.
Que implicaciones tiene para el modelo de datos actual?

Util cuando:

/opsx:propose

Modo formal. Crea todo en un paso. Util cuando:

Regla practica: si tienes dudas, usa /opsx:explore primero. Cuando tengas claridad, usa /opsx:propose.

Verificar el estado

En cualquier momento puedes consultar el estado del cambio:

openspec status --change "setup-data-model"

Esto muestra que artefactos estan completos, cuales faltan y si el cambio esta listo para implementar.

Resumen

← Capitulo 3: Configurando el Contexto | Capitulo 5: Perfil Expandido →

← Volver al listado de tecnologías ← Índice de OpenSpec