Conceptos
Esta guía explica las ideas centrales detrás de OpenSpec y cómo se relacionan entre sí. Para uso práctico, consulta Primeros pasos y Flujos de trabajo.
Filosofía
OpenSpec se construye sobre cuatro principios:
fluido no rígido — sin fases obligatorias, trabaja en lo que tenga sentido
iterativo no en cascada — aprende mientras construyes, refina sobre la marcha
simple no complejo — configuración ligera, ceremonia mínima
brownfield primero — funciona con bases de código existentes, no solo con proyectos nuevosPor Qué Estos Principios Importan
Fluido, no rígido. Los sistemas de especificación tradicionales te encierran en fases: primero planificas, luego implementas y luego terminas. OpenSpec es más flexible — puedes crear artefactos en cualquier orden que tenga sentido para tu trabajo.
Iterativo, no en cascada. Los requisitos cambian. La comprensión se profundiza. Lo que parecía un buen enfoque al principio podría no sostenerse después de ver la base de código. OpenSpec acepta esta realidad.
Simple, no complejo. Algunos marcos de especificación requieren configuración extensa, formatos rígidos o procesos pesados. OpenSpec no se interpone en tu camino. Inicializa en segundos, comienza a trabajar de inmediato y personaliza solo si lo necesitas.
Brownfield primero. La mayoría del trabajo de software no consiste en construir desde cero — es modificar sistemas existentes. El enfoque basado en deltas de OpenSpec facilita especificar cambios al comportamiento existente, no solo describir nuevos sistemas.
El Panorama General
OpenSpec organiza tu trabajo en dos áreas principales:
┌────────────────────────────────────────────────────────────────────┐
│ openspec/ │
│ │
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ specs/ │ │ changes/ │ │
│ │ │ │ │ │
│ │ Fuente de verdad │◄─────│ Modificaciones propuestas │ │
│ │ Cómo funciona │ merge│ Cada cambio = una carpeta │ │
│ │ tu sistema │ │ Contiene artefactos + deltas │ │
│ │ actualmente │ │ │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────┘Las especificaciones (specs) son la fuente de verdad: describen cómo se comporta tu sistema actualmente.
Los cambios (changes) son modificaciones propuestas: viven en carpetas separadas hasta que estés listo para fusionarlos.
Esta separación es clave. Puedes trabajar en múltiples cambios en paralelo sin conflictos. Puedes revisar un cambio antes de que afecte las especificaciones principales. Y cuando archivas un cambio, sus deltas se fusionan limpiamente en la fuente de verdad.
Especificaciones (Specs)
Las especificaciones describen el comportamiento de tu sistema utilizando requisitos estructurados y escenarios.
Estructura
openspec/specs/
├── auth/
│ └── spec.md # Comportamiento de autenticación
├── payments/
│ └── spec.md # Procesamiento de pagos
├── notifications/
│ └── spec.md # Sistema de notificaciones
└── ui/
└── spec.md # Comportamiento de la interfaz y temasOrganiza las especificaciones por dominio — agrupaciones lógicas que tengan sentido para tu sistema. Patrones comunes:
- Por área de funcionalidad:
auth/,payments/,search/ - Por componente:
api/,frontend/,workers/ - Por contexto delimitado:
ordering/,fulfillment/,inventory/
Formato de una Especificación
Una especificación contiene requisitos, y cada requisito tiene escenarios:
# Especificación de Autenticación
## Propósito
Autenticación y gestión de sesiones para la aplicación.
## Requisitos
### Requisito: Autenticación de Usuario
El sistema DEBERÁ emitir un token JWT tras un inicio de sesión exitoso.
#### Escenario: Credenciales válidas
- DADO un usuario con credenciales válidas
- CUANDO el usuario envía el formulario de inicio de sesión
- ENTONCES se devuelve un token JWT
- Y el usuario es redirigido al panel principal
#### Escenario: Credenciales inválidas
- DADO credenciales inválidas
- CUANDO el usuario envía el formulario de inicio de sesión
- ENTONCES se muestra un mensaje de error
- Y no se emite ningún token
### Requisito: Expiración de Sesión
El sistema DEBE expirar las sesiones después de 30 minutos de inactividad.
#### Escenario: Tiempo de espera por inactividad
- DADA una sesión autenticada
- CUANDO pasan 30 minutos sin actividad
- ENTONCES la sesión se invalida
- Y el usuario debe re-autenticarseElementos clave:
| Elemento | Propósito |
|---|---|
## Propósito | Descripción de alto nivel del dominio de esta especificación |
### Requisito: | Un comportamiento específico que el sistema debe tener |
#### Escenario: | Un ejemplo concreto del requisito en acción |
| SHALL/MUST/SHOULD | Palabras clave RFC 2119 que indican la fuerza del requisito |
Por Qué Estructurar las Especificaciones Así
Los requisitos son el "qué" — establecen lo que el sistema debe hacer sin especificar la implementación.
Los escenarios son el "cuándo" — proporcionan ejemplos concretos que pueden verificarse. Buenos escenarios:
- Son comprobables (podrías escribir una prueba automatizada para ellos)
- Cubren tanto el camino feliz como los casos límite
- Usan Dado/Cuando/Entonces o un formato estructurado similar
Palabras clave RFC 2119 (SHALL, MUST, SHOULD, MAY) comunican la intención:
- MUST/SHALL — requisito absoluto
- SHOULD — recomendado, pero existen excepciones
- MAY — opcional
Qué es una Especificación (y Qué No Es)
Una especificación es un contrato de comportamiento, no un plan de implementación.
Buen contenido para una especificación:
- Comportamiento observable del que dependen los usuarios o los sistemas posteriores
- Entradas, salidas y condiciones de error
- Restricciones externas (seguridad, privacidad, fiabilidad, compatibilidad)
- Escenarios que puedan probarse o validarse explícitamente
Evita en las especificaciones:
- Nombres internos de clases/funciones
- Elecciones de librerías o frameworks
- Detalles de implementación paso a paso
- Planes de ejecución detallados (esos pertenecen a
design.mdotasks.md)
Prueba rápida:
- Si la implementación puede cambiar sin que cambie el comportamiento externamente visible, probablemente no pertenece a la especificación.
Manténlo Ligero: Rigor Progresivo
OpenSpec busca evitar la burocracia. Usa el nivel más ligero que aún haga verificable el cambio.
Especificación ligera (por defecto):
- Requisitos cortos centrados en el comportamiento
- Alcance claro y no-objetivos
- Algunas comprobaciones de aceptación concretas
Especificación completa (para mayor riesgo):
- Cambios entre equipos o entre repositorios
- Cambios de API/contratos, migraciones, preocupaciones de seguridad/privacidad
- Cambios donde la ambigüedad probablemente cause retrabajo costoso
La mayoría de los cambios deberían permanecer en modo ligero.
Colaboración Humano + Agente
En muchos equipos, los humanos exploran y los agentes redactan los artefactos. El ciclo previsto es:
- El humano proporciona la intención, el contexto y las restricciones.
- El agente convierte esto en requisitos y escenarios centrados en el comportamiento.
- El agente mantiene los detalles de implementación en
design.mdytasks.md, no enspec.md. - La validación confirma la estructura y la claridad antes de la implementación.
Esto mantiene las especificaciones legibles para los humanos y consistentes para los agentes.
Cambios (Changes)
Un cambio es una modificación propuesta a tu sistema, empaquetada como una carpeta con todo lo necesario para entenderla e implementarla.
Estructura de un Cambio
openspec/changes/add-dark-mode/
├── proposal.md # Por qué y qué
├── design.md # Cómo (enfoque técnico)
├── tasks.md # Lista de verificación de implementación
├── .openspec.yaml # Metadatos del cambio (opcional): schema, created, skip_specs, retire_capabilities
└── specs/ # Especificaciones delta
└── ui/
└── spec.md # Qué está cambiando en ui/spec.mdCada cambio es autónomo. Tiene:
- Artefactos — documentos que capturan la intención, el diseño y las tareas
- Especificaciones delta — especificaciones de lo que se añade, modifica o elimina
- Metadatos — configuración opcional para este cambio específico
Por Qué los Cambios Son Carpetas
Empaquetar un cambio como carpeta tiene varios beneficios:
Todo junto. La propuesta, el diseño, las tareas y las especificaciones viven en un solo lugar. Sin buscar en diferentes ubicaciones.
Trabajo en paralelo. Múltiples cambios pueden existir simultáneamente sin conflictos. Trabaja en
add-dark-modemientrasfix-auth-bugtambién está en progreso.Historial limpio. Al archivarse, los cambios se mueven a
changes/archive/con su contexto completo preservado. Puedes mirar hacia atrás y entender no solo qué cambió, sino por qué.Fácil de revisar. Una carpeta de cambio es fácil de revisar: ábrela, lee la propuesta, revisa el diseño, mira los deltas de las especificaciones.
Artefactos
Los artefactos son los documentos dentro de un cambio que guían el trabajo.
El Flujo de Artefactos
proposal ──────► specs ──────► design ──────► tasks ──────► implement
│ │ │ │
por qué qué cómo pasos
+ alcance cambios enfoque a seguirLos artefactos se construyen unos sobre otros. Cada artefacto proporciona contexto para el siguiente.
Tipos de Artefactos
Propuesta (proposal.md)
La propuesta captura la intención, el alcance y el enfoque a alto nivel.
# Propuesta: Añadir Modo Oscuro
## Intención
Los usuarios han solicitado una opción de modo oscuro para reducir
la fatiga visual durante el uso nocturno y coincidir con las
preferencias del sistema.
## Alcance
Dentro del alcance:
- Alternador de tema en la configuración
- Detección de preferencia del sistema
- Persistir la preferencia en localStorage
Fuera del alcance:
- Temas de color personalizados (trabajo futuro)
- Anulaciones de tema por página
## Enfoque
Usar propiedades personalizadas CSS para los temas con un contexto
de React para la gestión de estado. Detectar la preferencia del
sistema en la primera carga, permitir anulación manual.Cuándo actualizar la propuesta:
- El alcance cambia (se estrecha o amplía)
- La intención se aclara (mejor comprensión del problema)
- El enfoque cambia fundamentalmente
Especificaciones (especificaciones delta en specs/)
Las especificaciones delta describen qué está cambiando en relación con las especificaciones actuales. Consulta Especificaciones Delta más abajo.
Diseño (design.md)
El diseño captura el enfoque técnico y las decisiones de arquitectura.
# Diseño: Añadir Modo Oscuro
## Enfoque Técnico
El estado del tema se gestiona mediante Context de React para evitar
el prop drilling. Las propiedades personalizadas CSS permiten el
cambio en tiempo de ejecución sin alternar clases.
## Decisiones de Arquitectura
### Decisión: Context sobre Redux
Usar Context de React para el estado del tema porque:
- Estado binario simple (claro/oscuro)
- Sin transiciones de estado complejas
- Evita añadir dependencia de Redux
### Decisión: Propiedades Personalizadas CSS
Usar variables CSS en lugar de CSS-in-JS porque:
- Funciona con la hoja de estilos existente
- Sin sobrecarga en tiempo de ejecución
- Solución nativa del navegador
## Flujo de Datos
```
ThemeProvider (contexto)
│
▼
ThemeToggle ◄──► localStorage
│
▼
Variables CSS (aplicadas a :root)
```
## Cambios de Archivos
- `src/contexts/ThemeContext.tsx` (nuevo)
- `src/components/ThemeToggle.tsx` (nuevo)
- `src/styles/globals.css` (modificado)Cuándo actualizar el diseño:
- La implementación revela que el enfoque no funcionará
- Se descubre una mejor solución
- Las dependencias o restricciones cambian
Tareas (tasks.md)
Las tareas son la lista de verificación de implementación — pasos concretos con casillas de verificación.
# Tareas
## 1. Infraestructura del Tema
- [ ] 1.1 Crear ThemeContext con estado claro/oscuro
- [ ] 1.2 Añadir propiedades personalizadas CSS para los colores
- [ ] 1.3 Implementar persistencia en localStorage
- [ ] 1.4 Añadir detección de preferencia del sistema
## 2. Componentes de UI
- [ ] 2.1 Crear componente ThemeToggle
- [ ] 2.2 Añadir el alternador a la página de configuración
- [ ] 2.3 Actualizar Header para incluir alternador rápido
## 3. Estilos
- [ ] 3.1 Definir la paleta de colores del tema oscuro
- [ ] 3.2 Actualizar los componentes para usar variables CSS
- [ ] 3.3 Probar las relaciones de contraste para accesibilidadMejores prácticas para las tareas:
- Agrupa tareas relacionadas bajo encabezados
- Usa numeración jerárquica (1.1, 1.2, etc.)
- Mantén las tareas lo suficientemente pequeñas para completarlas en una sesión
- Marca las tareas como completadas conforme las termines
Especificaciones Delta
Las especificaciones delta son el concepto clave que hace que OpenSpec funcione para el desarrollo en sistemas existentes (brownfield). Describen qué está cambiando en lugar de reafirmar toda la especificación.
El Formato
# Delta para Auth
## REQUISITOS AÑADIDOS
### Requisito: Autenticación de Dos Factores
El sistema DEBE soportar autenticación de dos factores basada en TOTP.
#### Escenario: Registro de 2FA
- DADO un usuario sin 2FA habilitado
- CUANDO el usuario habilita 2FA en la configuración
- ENTONCES se muestra un código QR para la configuración de la app autenticadora
- Y el usuario debe verificar con un código antes de la activación
#### Escenario: Inicio de sesión con 2FA
- DADO un usuario con 2FA habilitado
- CUANDO el usuario envía credenciales válidas
- ENTONCES se presenta un desafío OTP
- Y el inicio de sesión se completa solo después de un OTP válido
## REQUISITOS MODIFICADOS
### Requisito: Expiración de Sesión
El sistema DEBE expirar las sesiones después de 15 minutos de inactividad.
(Anteriormente: 30 minutos)
#### Escenario: Tiempo de espera por inactividad
- DADA una sesión autenticada
- CUANDO pasan 15 minutos sin actividad
- ENTONCES la sesión se invalida
## REQUISITOS ELIMINADOS
### Requisito: Recordarme
(Obsoleto en favor de 2FA. Los usuarios deben re-autenticarse en cada sesión.)Secciones Delta
| Sección | Significado | Qué Ocurre al Archivar |
|---|---|---|
## REQUISITOS AÑADIDOS | Comportamiento nuevo | Se añade a la especificación principal |
## REQUISITOS MODIFICADOS | Comportamiento cambiado | Reemplaza el requisito existente |
## REQUISITOS ELIMINADOS | Comportamiento obsoleto | Se elimina de la especificación principal; eliminar el último requisito retira la capacidad y borra su archivo de especificación, cuando el cambio declara retire_capabilities: true |
## Propósito | Para qué sirve una capacidad completamente nueva | Siembra el Propósito de la especificación principal que se está creando; se ignora cuando la especificación ya existe |
Por Qué Deltas en Lugar de Especificaciones Completas
Claridad. Un delta muestra exactamente qué está cambiando. Al leer una especificación completa, tendrías que hacer un diff mental contra la versión actual.
Evitar conflictos. Dos cambios pueden tocar el mismo archivo de especificación sin conflictos, siempre que modifiquen requisitos diferentes.
Eficiencia en la revisión. Los revisores ven el cambio, no el contexto sin cambios. Concéntrate en lo que importa.
Adecuación para sistemas existentes. La mayoría del trabajo modifica el comportamiento existente. Los deltas hacen que las modificaciones sean de primera clase, no una ocurrencia tardía.
Esquemas
Los esquemas definen los tipos de artefactos y sus dependencias para un flujo de trabajo.
Cómo funcionan los esquemas
# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
- id: proposal
generates: proposal.md
requires: [] # Sin dependencias, puede crearse primero
- id: specs
generates: specs/**/*.md
requires: [proposal] # Necesita la propuesta antes de crear
- id: design
generates: design.md
requires: [proposal] # Puede crearse en paralelo con los especificaciones
- id: tasks
generates: tasks.md
requires: [specs, design] # Necesita tanto los especificaciones como el diseño primeroLos artefactos forman un grafo de dependencias:
proposal
(nodo raíz)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requiere: (requiere:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requiere:
specs, design)Las dependencias son habilitadores, no barreras. Indican qué es posible crear, no lo que debes crear a continuación. Puedes omitir el diseño si no lo necesitas. Puedes crear los especificaciones antes o después del diseño; ambos dependen únicamente de la propuesta.
Esquemas integrados
spec-driven (predeterminado)
El flujo de trabajo estándar para el desarrollo basado en especificaciones:
proposal → specs → design → tasks → implementIdeal para: La mayoría del trabajo de características donde deseas acordar las especificaciones antes de la implementación.
Esquemas personalizados
Crea esquemas personalizados para el flujo de trabajo de tu equipo:
# Crear desde cero
openspec schema init research-first
# O bifurcar uno existente
openspec schema fork spec-driven research-firstEjemplo de esquema personalizado:
# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
- id: research
generates: research.md
requires: [] # Realizar investigación primero
- id: proposal
generates: proposal.md
requires: [research] # Propuesta informada por la investigación
- id: tasks
generates: tasks.md
requires: [proposal] # Omitir especificaciones/diseño, ir directamente a tareasConsulta Personalización para obtener detalles completos sobre cómo crear y usar esquemas personalizados.
Archivo
Archivar completa un cambio al fusionar sus especificaciones delta en las especificaciones principales y preservar el cambio para el historial.
Qué sucede al archivar
Antes de archivar:
openspec/
├── specs/
│ └── auth/
│ └── spec.md ◄────────────────┐
└── changes/ │
└── add-2fa/ │
├── proposal.md │
├── design.md │ fusionar
├── tasks.md │
└── specs/ │
└── auth/ │
└── spec.md ─────────┘
Después de archivar:
openspec/
├── specs/
│ └── auth/
│ └── spec.md # Ahora incluye los requisitos de 2FA
└── changes/
└── archive/
└── 2025-01-24-add-2fa/ # Preservado para el historial
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── auth/
└── spec.mdEl proceso de archivado
Fusionar deltas. Cada sección de especificación delta (ADDED/MODIFIED/REMOVED) se aplica a la especificación principal correspondiente.
Mover al archivo. La carpeta del cambio se mueve a
changes/archive/con un prefijo de fecha para orden cronológico.Preservar contexto. Todos los artefactos permanecen intactos en el archivo. Siempre puedes consultar el pasado para entender por qué se realizó un cambio.
Por qué importa el archivado
Estado limpio. Los cambios activos (changes/) muestran solo el trabajo en curso. El trabajo completado se retira.
Trazabilidad. El archivo preserva el contexto completo de cada cambio: no solo qué cambió, sino también la propuesta que explica por qué, el diseño que explica cómo y las tareas que muestran el trabajo realizado.
Evolución de las especificaciones. Las especificaciones crecen orgánicamente a medida que se archivan los cambios. Cada archivado fusiona sus deltas, construyendo una especificación integral con el tiempo.
Cómo encaja todo junto
┌──────────────────────────────────────────────────────────────────────────────┐
│ FLUJO DE OPENSPEC │
│ │
│ ┌────────────────┐ │
│ │ 1. INICIAR │ /opsx:propose (núcleo) o /opsx:new (expandido) │
│ │ CAMBIO │ │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 2. CREAR │ /opsx:ff o /opsx:continue (flujo de trabajo expandido) │
│ │ ARTEFACTOS │ Crea proposal → specs → design → tasks │
│ │ │ (basado en las dependencias del esquema) │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 3. IMPLEMENTAR│ /opsx:apply │
│ │ TAREAS │ Trabaja a través de las tareas, marcándolas │
│ │ │◄──── Actualiza los artefactos a medida que aprendes │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ │
│ │ 4. VERIFICAR │ /opsx:verify (opcional) │
│ │ TRABAJO │ Verifica que la implementación coincida con las │
│ │ │ especificaciones │
│ └───────┬────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────┐ ┌──────────────────────────────────────────────┐ │
│ │ 5. ARCHIVAR │────►│ Las especificaciones delta se fusionan con │ │
│ │ CAMBIO │ │ las especificaciones principales │ │
│ └────────────────┘ │ La carpeta del cambio se mueve a archive/ │ │
│ │ Las especificaciones son ahora la fuente │ │
│ │ de verdad actualizada │ │
│ └──────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘El ciclo virtuoso:
- Las especificaciones describen el comportamiento actual
- Los cambios proponen modificaciones (como deltas)
- La implementación hace que los cambios sean reales
- El archivado fusiona los deltas en las especificaciones
- Las especificaciones ahora describen el nuevo comportamiento
- El siguiente cambio se basa en las especificaciones actualizadas
Glosario
| Término | Definición |
|---|---|
| Artefacto | Un documento dentro de un cambio (propuesta, diseño, tareas o especificaciones delta) |
| Archivo | El proceso de completar un cambio y fusionar sus deltas en las especificaciones principales |
| Cambio | Una modificación propuesta al sistema, empaquetada como una carpeta con artefactos |
| Especificación delta | Una especificación que describe cambios (ADDED/MODIFIED/REMOVED) con respecto a las especificaciones actuales |
| Dominio | Un agrupamiento lógico para especificaciones (por ejemplo, auth/, payments/) |
| Requisito | Un comportamiento específico que el sistema debe tener |
| Escenario | Un ejemplo concreto de un requisito, típicamente en formato Dado/Cuando/Entonces |
| Esquema | Una definición de tipos de artefactos y sus dependencias |
| Especificación | Una descripción del comportamiento del sistema, que contiene requisitos y escenarios |
| Fuente de verdad | El directorio openspec/specs/, que contiene el comportamiento acordado actualmente |
Próximos pasos
- Primeros pasos - Pasos prácticos iniciales
- Flujos de trabajo - Patrones comunes y cuándo usar cada uno
- Comandos - Referencia completa de comandos
- Personalización - Crea esquemas personalizados y configura tu proyecto