Flujos y Patrones de Trabajo

El problema

Ya conoces los comandos de OpenSpec: propose, new, ff, continue, apply, verify, archive. Sabes que hace cada uno individualmente. Pero cuando te sientas a trabajar en un cambio real, la pregunta es otra: que combinacion de comandos uso para esta situacion?

No existe un unico flujo correcto. Depende del tamano del cambio, de cuanto contexto tengas, y de si estas explorando una idea o ejecutando algo definido. Este capitulo presenta los patrones mas comunes y cuando usar cada uno.

Soporte multi-idioma

Por que importa

Por defecto, la IA genera artefactos en ingles. Si tu equipo trabaja en espanol (o cualquier otro idioma), los proposals, specs y tasks en ingles crean una barrera: hay que traducir mentalmente cada vez que se leen, y los terminos pueden no coincidir con los que usa el equipo.

OpenSpec permite configurar el idioma de generacion para que los artefactos se generen en tu idioma.

Configurar idioma en config.yaml

schema: spec-driven

context: |
  ## Idioma
  - Idioma de artefactos: espanol
  - Terminos tecnicos (API, endpoint, middleware, schema) se mantienen en ingles
  - Nombres de variables, funciones y archivos siempre en ingles

  ## Stack
  - Runtime: Node.js 20, TypeScript 5.4
  - Frontend: React 19, Tailwind CSS 4
  - Backend: Express 5, Prisma 6

Con esta configuracion, al ejecutar /opsx:propose add-user-auth, la IA genera el proposal en espanol:

# Propuesta: Agregar autenticacion de usuarios

## Motivacion
El sistema actualmente no tiene control de acceso...

## Alcance
- Crear modelo User con Prisma
- Implementar registro y login con JWT

Idiomas soportados

Idioma	Configuracion en context
Espanol	Idioma de artefactos: espanol
Portugues	Idioma de artefactos: portugues
Chino	Idioma de artefactos: chino simplificado
Japones	Idioma de artefactos: japones
Frances	Idioma de artefactos: frances
Aleman	Idioma de artefactos: aleman

La IA respeta cualquier idioma que especifiques en el context. Los 6 anteriores son los mas probados, pero puedes usar cualquier idioma que la IA soporte.

Mejores practicas con terminos tecnicos

La regla general: traduce la prosa, mantiene en ingles los terminos tecnicos.

Traducir	Mantener en ingles
Descripciones y explicaciones	Nombres de variables y funciones
Titulos de secciones	Tipos y interfaces (User, AuthService)
Instrucciones al equipo	Comandos y paths (npm run test, src/)
Criterios de aceptacion	Terminos sin traduccion clara (middleware, endpoint)

Para forzar esta convencion, agregala en rules:

rules:
  proposal:
    - Escribir en espanol
    - Terminos tecnicos en ingles
    - Nombres de codigo (variables, funciones, tipos) siempre en ingles
  tasks:
    - Escribir en espanol
    - Nombres de archivos y modulos en ingles

Verificar la configuracion

Para confirmar que el idioma funciona correctamente, genera una instruccion de prueba:

openspec instructions proposal --change mi-cambio

Esto muestra el prompt completo que OpenSpec enviara a la IA. Verifica que incluya la instruccion de idioma y que el context tenga tus convenciones.

Patrones de workflow

Quick Feature: cambio rapido y definido

Cuando usarlo: sabes exactamente que quieres construir, el alcance es pequeno (1-3 tareas) y no necesitas explorar alternativas.

openspec new mi-feature          # Crear el change
openspec ff mi-feature            # Generar todos los artefactos de golpe
/opsx:apply                       # Implementar
openspec verify mi-feature        # Validar
openspec archive mi-feature       # Cerrar

Flujo:

1. new crea el change con nombre y descripcion
2. ff (fast-forward) genera proposal, specs, design y tasks en un solo paso
3. apply implementa las tareas
4. verify valida que todo funciona
5. archive cierra el ciclo y mueve a historial

Ventaja: rapido, minimo overhead. En 5 comandos pasas de idea a codigo implementado.

Riesgo: si el cambio es mas complejo de lo que pensabas, los artefactos generados por ff pueden ser superficiales. En ese caso, usa continue para profundizar en artefactos especificos.

Exploratory: descubrir antes de construir

Cuando usarlo: tienes una idea vaga, necesitas investigar el codebase existente, o quieres evaluar alternativas antes de comprometerte con un enfoque.

/opsx:explore                     # Pensar y explorar la idea
openspec new mi-feature            # Crear el change cuando tengas claridad
openspec continue mi-feature       # Generar artefactos uno a uno, revisando cada paso
/opsx:apply                       # Implementar

Flujo:

1. explore abre un modo de conversacion libre para investigar
2. Cuando tienes claridad, new crea el change
3. continue genera artefactos de forma incremental: primero proposal, lo revisas, luego specs, lo revisas, etc.
4. En cada paso puedes ajustar antes de continuar
5. apply implementa cuando estas satisfecho con los artefactos

Ventaja: control total sobre cada artefacto. Puedes iterar en el design antes de generar tasks.

Riesgo: mas lento. Solo justificado para cambios complejos o cuando hay incertidumbre sobre el enfoque.

Parallel Changes: multiples cambios simultaneos

Cuando usarlo: necesitas trabajar en 2+ features al mismo tiempo, especialmente cuando tocan archivos diferentes.

Este patron se cubre en profundidad en el Capitulo 9: Cambios Paralelos. La idea central:

• Cada change tiene su propio directorio de artefactos
• OpenSpec trackea el estado de cada change independientemente
• Usa openspec status para ver todos los changes activos
• Aplica y verifica cada change por separado

Guia de decision: ff vs continue

La decision mas frecuente es: uso ff (todo de golpe) o continue (paso a paso)?

Criterio	ff (fast-forward)	continue (incremental)
Tamano del cambio	Pequeno (1-3 tareas)	Mediano-grande (4+ tareas)
Claridad del alcance	Alta (sabes que construir)	Baja (necesitas explorar)
Necesidad de revision	Minima (confias en el output)	Alta (quieres revisar cada artefacto)
Velocidad	Rapido (1 comando)	Lento (varios comandos)
Control	Bajo (aceptas lo que genera)	Alto (ajustas en cada paso)

Regla practica: si puedes describir el cambio completo en 2 oraciones, usa ff. Si necesitas mas de 2 oraciones o dices “depende de…”, usa continue.

Combinando patrones

Los patrones no son exclusivos. Un flujo comun es:

1. Empezar con Exploratory para entender el problema
2. Crear el change con new
3. Usar ff para generar artefactos iniciales
4. Usar continue para profundizar en un artefacto especifico que necesita mas detalle
5. apply + verify + archive

La flexibilidad de OpenSpec esta en que puedes mezclar comandos segun lo que necesites en cada momento.

Resumen

• Multi-idioma: Configura el idioma en config.yaml context para que los artefactos se generen en tu idioma
• Quick Feature (new → ff → apply → verify → archive): para cambios pequenos y bien definidos
• Exploratory (explore → new → continue → apply): para cambios complejos o con incertidumbre
• Parallel Changes: multiples changes simultaneos con tracking independiente (ver Cap 9)
• ff vs continue: si lo describes en 2 oraciones, usa ff; si dices “depende”, usa continue

---

← Capitulo 13: Integracion con Herramientas de Calidad | Capitulo 15: LLM como Auditor de Mejores Practicas →