⬡
SDD Lifecycle con OpenSpec
Ciclo de vida completo de software gobernado por especificación · Spec-Driven Development
Antonio Herrera
13
Fases del ciclo
11
Quality gates
22
Pasos prácticos
Guía completa · Paso a paso
- 1Crear historia de usuarioDefinir necesidad de negocio y criterios de aceptación
- 2Crear propuesta OpenSpec/opsx:propose "descripción del cambio"
- 3Revisar proposal.mdValidar problema, objetivo, alcance, fuera de alcance y riesgos
- 4Revisar design.mdValidar enfoque técnico, arquitectura, impacto API, datos y seguridad
- 5Revisar spec.mdValidar requisitos y escenarios verificables
- 6Revisar tasks.mdAsegurar trabajo dividido en tareas pequeñas y comprobables
- 7Validar OpenSpecopenspec validate --strict
- 8Definir o actualizar OpenAPICrear el contrato técnico de la API — contract-first
- 9Validar contrato APIspectral lint openapi.yaml
- 10Publicar en API ManagerConfigurar catálogo, seguridad, versionado, políticas y documentación
- 11Implementar con agente IA/opsx:apply [change-id]
- 12Ejecutar tests localesmvn test · npm test · npx playwright test
- 13Validar calidadLint, SonarQube, security scan, contract tests
- 14Crear Pull RequestVincular historia, spec, contrato, tests y evidencias
- 15Revisión humanaValidar intención, alcance, calidad y seguridad
- 16Pipeline CI/CDEjecutar validaciones automáticas
- 17Despliegue a QA / UATProbar funcionalidad en entorno controlado
- 18Validación funcionalQA / PO validan criterios de aceptación
- 19Despliegue a producciónPromover versión con control de rollback
- 20MonitorizaciónLogs, métricas, trazas, errores y consumo API
- 21Archivo del cambio/opsx:archive · openspec archive <id> --yes
- 22Cierre de historiaSpec viva actualizada e historia cerrada en el tracker
Mapa mental por bloques
Bloque 1
Negocio
- Historia de usuario
- Criterios de aceptación
- Alcance funcional
→ Necesidad clara
Bloque 2
Especificación
- /opsx:propose
- proposal.md · design.md
- spec.md · tasks.md
→ Cambio documentado
Bloque 3
Gobierno técnico
- OpenAPI · API Manager
- Seguridad · Versionado
- Políticas
→ API gobernada
Bloque 4
Implementación
- /opsx:apply
- Código · Tests
- Tasks actualizadas
→ Código contra spec
Bloque 5
Validación
- Unit · Integration · E2E
- Contract · Security
- openspec validate
→ Evidencia automática
Bloque 6
Revisión humana
- Pull Request
- Aprobación técnica
- Aprobación funcional
→ Control de intención
Bloque 7
Despliegue
- CI/CD · QA · UAT
- Producción · Rollback
→ Entrega controlada
Bloque 8
Operación & Archivo
- Observabilidad · Analytics
- /opsx:archive
→ Conocimiento vivo
Tabla rápida de comandos
0
Preparación inicial del proyecto
Inicializar OpenSpec y crear la estructura base de gobierno técnico
Qué se hace aquí
Antes de empezar con cualquier historia de usuario, hay que preparar el repositorio para trabajar con OpenSpec. Esto crea una estructura base donde se guardarán las specs permanentes del sistema, los cambios en curso y la documentación viva.
Dependiendo del asistente utilizado, también puede generar comandos o skills para Claude Code, Cursor, Copilot, OpenCode, etc.
Comandos de inicialización
npm install -g @fission-ai/openspec@latest
cd mi-proyecto
openspec init
# Ver ayuda
openspec --help
# Validar que todo está bien
openspec validate
Estructura generada
openspec/
project.md # Contexto y convenciones del proyecto
specs/ # Specs permanentes del sistema
changes/ # Cambios en curso y archivados
Para qué sirve esta fase
Sirve para que el proyecto tenga una memoria técnica gobernada. No es solo documentación: es el sitio donde se define qué hace el sistema, cómo está diseñado, qué cambios están en curso, cuáles se han completado y qué convenciones debe respetar el agente IA.
✓ Gate 0 — Project Ready
✓
OpenSpec instalado✓
Proyecto inicializado✓
Estructura openspec/ creada✓
project.md configurado✓
openspec validate OK1
Historia de usuario
Punto de partida del ciclo real · Definición de necesidad y criterios verificables
Qué se hace aquí
Se parte de una historia de usuario en Jira, Azure DevOps, GitHub Issues, Linear o similar. La historia debe ser clara, con criterios de aceptación específicos y sin ambigüedad antes de pasar a la siguiente fase.
Ejemplo de historia de usuario
Como cliente autenticado,
quiero consultar mis movimientos bancarios
filtrando por fecha, importe y categoría,
para encontrar operaciones concretas sin revisar
todo el histórico.
── Criterios de aceptación ──────────────────────
CA1. El usuario puede filtrar por rango de fechas.
CA2. El usuario puede filtrar por importe mínimo y máximo.
CA3. El usuario puede filtrar por categoría.
CA4. Si no hay resultados, se muestra un mensaje informativo.
CA5. El endpoint debe paginar resultados.
CA6. Solo se devuelven movimientos del usuario autenticado.
Flujo clásico vs. flujo con OpenSpec
❌ Flujo clásico
Historia → código directamente. El agente IA empieza a implementar sin spec completa, generando ambigüedad y retrabajo.
✓ Flujo con OpenSpec
Historia → spec exhaustiva → criterios verificables → tareas atómicas → tests → código. Orden y trazabilidad total.
✓ Gate 1 — Historia Clara
✓
Historia en formato estándar✓
Criterios de aceptación definidos✓
Sin ambigüedad de alcance✓
Impacto técnico identificado2
Definición de la especificación
Primera capa formal del ciclo · De la intención a la spec verificable
Crear la propuesta con OpenSpec
# Nombre corto de cambio
/opsx:propose add-transaction-filtering
# Con descripción natural
/opsx:propose "Añadir filtrado de movimientos por fecha, importe y categoría"
Artefactos generados
openspec/
changes/
add-transaction-filtering/
proposal.md # Qué y por qué (negocio)
design.md # Cómo (técnico)
tasks.md # Trabajo dividido
specs/
transactions/
spec.md # Comportamiento verificable
Contenido de proposal.md
## Problem
Los usuarios no pueden localizar movimientos concretos fácilmente.
## Goal
Filtrado por fecha, importe y categoría con paginación.
## In Scope
- Filtro por fecha inicio / fecha fin
- Filtro por importe mínimo / máximo
- Filtro por categoría · Paginación
## Out of Scope
- Exportación a Excel · Búsqueda semántica
- Categorización automática · Consulta multiusuario
## Risks
- Rendimiento en tablas grandes
- Posible fuga de datos entre usuarios
Escenarios verificables en spec.md
### Scenario: Valid date range
- GIVEN an authenticated user
- AND the user has transactions in January
- WHEN the user searches with startDate and endDate
- THEN the system SHALL return only transactions within that range
### Scenario: No matching transactions
- GIVEN an authenticated user
- WHEN the filters return no results
- THEN the system SHALL return an empty list
- AND the UI SHALL show a friendly empty state message
Validación antes de avanzar
openspec validate
openspec validate --strict
✓ Gate 2 — Spec Ready
✓
Historia vinculada✓
Criterios de aceptación completos✓
Alcance definido✓
Fuera de alcance definido✓
Riesgos documentados✓
Spec validada (openspec validate)✓
Tareas atómicas creadas✓
API impact identificado✓
QA involucrado desde el inicio3
Contexto, skills, MCPs y convenciones
La diferencia entre "prompting" y "engineering" · Contexto real del proyecto al agente
Qué se hace aquí
Se le da al agente IA contexto real del proyecto. Una spec buena no basta si el agente no conoce el stack, la arquitectura, las convenciones, los patrones de testing, la estructura del repositorio, los MCPs corporativos y las políticas de seguridad.
Dónde se documenta el contexto
openspec/project.md
Stack, arquitectura, patrones, reglas API, políticas de seguridad
AGENTS.md / CLAUDE.md
Instrucciones específicas para el agente IA del proyecto
.cursor/rules
Reglas y convenciones para Cursor
.github/copilot-instructions.md
Instrucciones para GitHub Copilot
Ejemplo de openspec/project.md
## Stack
- Backend: Java 21 + Spring Boot
- Frontend: React + TypeScript
- Database: PostgreSQL
- CI/CD: GitHub Actions
- Gateway: Azure API Management
- Testing: JUnit, Playwright, Pact
## API Standards
- RESTful APIs · OpenAPI 3.1
- Pagination: page + size
- Error format: RFC 7807
- CorrelationId required
- OAuth2/OIDC security
## Development Rules
- Do not bypass service layer
- Do not expose internal IDs
- All endpoints validate authenticated user
- All new APIs require OpenAPI update
MCPs corporativos relevantes
Jira MCP
Gestión de historias y tareas
GitHub MCP
PRs, commits, issues
Playwright MCP
Tests E2E automáticos
Postman MCP
Contratos API y colecciones
SonarQube MCP
Análisis de calidad de código
Confluence MCP
Documentación de equipo
API Manager MCP
Gobierno de APIs corporativas
ServiceNow MCP
Gestión de servicios TI
Comandos útiles
openspec list # Ver estado del proyecto
openspec list --specs # Ver specs existentes
openspec validate # Validar
openspec update # Actualizar skills si cambia el perfil
openspec config profile # Configurar perfil
✓ Gate 3 — Context Ready
✓
Stack documentado✓
Convenciones documentadas✓
Reglas API definidas✓
Reglas de seguridad definidas✓
MCPs disponibles identificados✓
Estructura del repo entendida✓
Dependencias conocidas4
Tareas atómicas
Descomposición del trabajo en unidades pequeñas, ejecutables y verificables individualmente
Buena vs. mala descomposición
❌ Tarea genérica
"Implementar búsqueda de movimientos" — ambigua, no verificable, no ejecutable de forma independiente.
✓ Tareas atómicas
1. Actualizar contrato OpenAPI · 2. Añadir DTO de filtros · 3. Añadir validaciones · … cada una verificable.
Ejemplo de tasks.md
## 1. API Contract
- [ ] 1.1 Add query parameters to OpenAPI
- [ ] 1.2 Add response examples
- [ ] 1.3 Add error responses 400, 401, 403, 500
- [ ] 1.4 Validate OpenAPI contract
## 2. Backend
- [ ] 2.1 Create TransactionFilterRequest DTO
- [ ] 2.2 Validate date range
- [ ] 2.3 Validate min/max amount
- [ ] 2.4 Extend TransactionController
- [ ] 2.5 Extend TransactionService
- [ ] 2.6 Add paginated repository query
- [ ] 2.7 Enforce authenticated user filter
## 3. Frontend
- [ ] 3.1 Add filter form UI
- [ ] 3.2 Connect filters to API
- [ ] 3.3 Add empty / loading / error states
## 4. Testing
- [ ] 4.1 Unit tests · 4.2 Integration tests
- [ ] 4.3 Contract tests · 4.4 E2E (Playwright)
Comando de implementación
/opsx:apply add-transaction-filtering
# El agente ejecuta tarea por tarea siguiendo tasks.md
# y marca completado en el checklist sin improvisar
✓ Gate 4 — Implementation Controlled
✓
Tareas atómicas y verificables✓
Sin tareas genéricas✓
Sin mezcla de responsabilidades✓
Agente sigue orden de tasks.md✓
Checklist actualizado tras cada tarea5
Contrato API y API Manager
Contract-first · OpenAPI antes que código · Gobierno de la exposición
Flujo contract-first
OpenSpec → OpenAPI → API Manager → Backend implementation
Ejemplo de contrato OpenAPI
paths:
/api/v1/transactions:
get:
summary: Search user transactions
operationId: searchTransactions
security:
- oauth2: []
parameters:
- {name: startDate, in: query, schema: {type: string, format: date}}
- {name: endDate, in: query, schema: {type: string, format: date}}
- {name: minAmount, in: query, schema: {type: number}}
- {name: maxAmount, in: query, schema: {type: number}}
- {name: page, in: query, schema: {type: integer}}
- {name: size, in: query, schema: {type: integer}}
responses:
"200": {description: Paginated list of transactions}
"400": {description: Invalid filters}
"401": {description: Unauthorized}
"403": {description: Forbidden}
Validación del contrato
npm run openapi:validate
spectral lint openapi.yaml
openapi-generator validate -i openapi.yaml
Qué gobierna el API Manager
Seguridad
OAuth2, políticas de acceso, rate limiting, cuotas por cliente
Versionado
Gestión de versiones y deprecación controlada de contratos
Observabilidad
Analytics, trazabilidad, consumo desagregado por cliente
Catálogo
Documentación pública, suscripción y portal de desarrolladores
✓ Gate 5 — API Governance Ready
✓
OpenAPI válido y con ejemplos✓
Naming y versionado correctos✓
Security scheme definido (OAuth2)✓
Errores estándar 400/401/403/500✓
Paginación estándar (page/size)✓
CorrelationId definido✓
API publicada en API Manager✓
Políticas de seguridad aplicadas6
Validación integrada · Tests
Los tests nacen de la spec, no al final · QA entra desde el diseño
La spec alimenta los tests
Spec → criterios → tests → código → validación automática
Capas de testing generadas desde spec
Tests unitarios
Generados desde los requisitos de spec.md por dominio
Tests de integración
Cubren los escenarios de los criterios de aceptación
Contract testing
Validan el contrato OpenAPI con Pact u otras herramientas
Tests E2E
Playwright cubre los flujos completos de usuario
BDD
Feature files generados desde los escenarios de spec.md
Evidencias QA
Casos Xray / Zephyr trazables a criterios de aceptación
Ejemplo BDD generado desde spec
Feature: Transaction filtering
Scenario: Filter transactions by date range
Given I am an authenticated user
And I have transactions in January
When I filter from "2026-01-01" to "2026-01-31"
Then I should only see transactions within that range
Scenario: No transactions found
Given I am an authenticated user
When I apply filters with no matching transactions
Then I should see "No se encontraron movimientos"
Comandos de ejecución
# Backend
mvn test
mvn verify
# Frontend
npm test
# E2E
npx playwright test
# Contrato API
spectral lint openapi.yaml
# Calidad
mvn sonar:sonar
# Spec
openspec validate --strict
✓ Gate 6 — Quality Ready
✓
Spec validada✓
OpenAPI validado✓
Unit tests OK✓
Integration tests OK✓
Contract tests OK✓
E2E tests OK✓
Static analysis OK✓
Security scan OK✓
Todos los CA cubiertos7
Pull Request y revisión humana
La IA acelera, pero no sustituye el criterio · Tú validas la intención, no solo el output
Qué se hace aquí
El agente genera código, tests y documentación, pero la decisión final es humana. El PR debe estar trazado contra la historia y contra la spec. La revisión no es línea a línea: es una validación de intención, alcance, calidad y seguridad.
Ejemplo de PR bien estructurado
## Change
Implements OpenSpec change: add-transaction-filtering
## Related Story
JIRA-1234
## OpenSpec
openspec/changes/add-transaction-filtering
## Summary
- Added transaction filters (date, amount, category)
- Updated OpenAPI contract
- Added unit, integration and E2E tests
## Validation Evidence
- openspec validate OK · openapi validate OK
- unit tests OK · integration tests OK
- playwright OK · security scan OK
## Risks
- Query performance on large datasets (monitor post-release)
Comandos Git
git checkout -b feature/add-transaction-filtering
git add .
git commit -m "feat: add transaction filtering"
git push origin feature/add-transaction-filtering
Qué valida el revisor humano
Intención vs. código
¿La implementación cumple la spec? ¿Se salió el agente del alcance definido?
Seguridad
¿La seguridad está bien aplicada? ¿Hay riesgos de fuga de datos entre usuarios?
Patrones del proyecto
¿Se respetan las convenciones, el contrato API y la arquitectura?
Cobertura de tests
¿Los tests cubren todos los criterios de aceptación definidos en la spec?
✓ Gate 7 — Human Review
✓
PR vinculado a historia✓
PR vinculado a OpenSpec change✓
Código alineado con spec✓
Sin cambios fuera de alcance✓
Evidencias de tests visibles✓
Aprobación técnica obtenida8
CI/CD y quality gates
El pipeline valida automáticamente spec, contrato, código, tests, seguridad y build
Ejemplo de pipeline (GitHub Actions)
name: ci
on:
pull_request:
branches: [main, develop]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate OpenSpec
run: openspec validate --strict
- name: Test backend
run: mvn verify
- name: Test frontend
run: npm test
- name: Validate OpenAPI
run: spectral lint openapi.yaml
- name: Security scan
run: mvn dependency-check:check
- name: Build
run: npm run build
Con contenedores y orquestación
docker build -t transactions-service:${GIT_SHA} .
docker push registry/transactions-service:${GIT_SHA}
helm upgrade --install transactions-service ./helm/transactions-service
✓ Gate 8 — CI/CD Ready
✓
OpenSpec validado en pipeline✓
OpenAPI validado en pipeline✓
Build correcto✓
Tests OK✓
Análisis estático OK✓
Security scan OK✓
Imagen versionada y publicada9
Despliegue a integración / QA / UAT
Del PR aprobado al entorno controlado · Validación funcional antes de producción
Flujo de entornos
develop → Build → Deploy INT → Smoke → Deploy QA → Regresión → UAT
Comandos de despliegue
oc project banking-qa
oc apply -f k8s/
oc rollout status deployment/transactions-service
# O con Helm
helm upgrade --install transactions-service ./chart \
--namespace banking-qa \
--set image.tag=1.2.0
Validaciones en QA
curl -H "Authorization: Bearer $TOKEN" \
"https://api-qa.empresa.com/api/v1/transactions?startDate=2026-01-01"
npx playwright test --project=qa
✓ Gate 9 — QA / UAT Ready
✓
Despliegue correcto✓
Smoke test OK✓
Regresión OK✓
UAT validado✓
API Manager configurado✓
Logs y trazas disponibles✓
PO acepta la historia10
Despliegue a producción
Promoción controlada con rollback definido desde el primer momento
Estrategias de despliegue
Manual approval
Gate humano obligatorio antes de ejecutar en producción
Blue / Green
Dos entornos paralelos con swap de tráfico al nuevo
Canary release
Porcentaje gradual de tráfico a la nueva versión
Feature flag
Activación de funcionalidad desacoplada del despliegue
Despliegue y rollback
helm upgrade --install transactions-service ./chart \
--namespace banking-prod \
--set image.tag=1.2.0
kubectl rollout status deployment/transactions-service -n banking-prod
# Rollback si algo falla
kubectl rollout undo deployment/transactions-service -n banking-prod
# OpenShift
oc rollout undo deployment/transactions-service
Validación postdespliegue
Health check · Smoke test productivo · Validación API Manager · Métricas de latencia (p50/p95) · Tasa de errores 4xx/5xx · Logs de aplicación · Trazas distribuidas · Alarmas activas
✓ Gate 10 — Production Ready
✓
Aprobación de release✓
Rollback definido y probado✓
Observabilidad activa✓
API publicada con políticas✓
Smoke productivo OK✓
Sin errores anómalos✓
Métricas dentro de umbral11
Observabilidad y operación
La fase que se olvida · Monitorizar si la funcionalidad realmente funciona bien
Qué observar en producción
Latencia
Percentiles p50 / p95 / p99 por endpoint y por operación
Errores
Tasa de errores 4xx y 5xx en tiempo real con alertas
Volumen
Llamadas por cliente, por operación y por período
Saturación
CPU, memoria, conexiones de base de datos, hilos activos
Trazas distribuidas
Trazas end-to-end vinculadas por CorrelationId
Logs de negocio
Eventos estructurados con contexto funcional relevante
Ejemplo de log estructurado
{
"event": "transaction.search.completed",
"correlationId": "abc-123-xyz",
"userId": "masked",
"filters": ["dateRange", "category"],
"resultCount": 25,
"durationMs": 120
}
Herramientas habituales
Dynatrace · Datadog · Elastic Stack · Grafana + Prometheus · Azure Monitor · CloudWatch · Splunk · API Manager Analytics
✓ Gate 11 — Operated
✓
Métricas visibles en dashboard✓
Logs estructurados y útiles✓
Trazas distribuidas conectadas✓
Alertas configuradas y probadas✓
API Manager recoge consumo✓
Sin degradación de servicio12
Archivo y sincronización de OpenSpec
Cierre del ciclo · La spec temporal pasa a ser documentación viva del sistema
Qué ocurre al archivar
Las delta specs se fusionan en openspec/specs/ y el cambio se mueve a una carpeta de archivo con fecha. La funcionalidad deja de ser un "cambio pendiente" y pasa a formar parte del conocimiento oficial del sistema.
Comandos de archivo
# Con asistente
/opsx:archive add-transaction-filtering
# Con CLI
openspec archive add-transaction-filtering --yes
Transformación del repositorio
Antes del archivo
openspec/
changes/
add-transaction-filtering/
proposal.md
design.md
tasks.md
specs/
Después del archivo
openspec/
specs/
transactions/
spec.md
changes/
archive/
2026-05-07-add-transaction/
proposal.md ···
El significado del cambio
Antes
"Estamos añadiendo filtrado de movimientos"
Después
"El sistema permite filtrar movimientos bajo estas reglas verificables"
✓ Gate 12 — Spec Archived · Ciclo completado
✓
Cambio desplegado en producción✓
Evidencias completas y almacenadas✓
Spec sincronizada en openspec/specs/✓
Cambio archivado con fecha✓
Documentación viva actualizada✓
Historia cerrada en el tracker
Antonio Herrera
Fractional CTO & Strategic Tech Advisor
Ayudo a compañías a ganar contratos, escalar su tecnología y tomar
decisiones técnicas críticas con criterio y seguridad.
decisiones técnicas críticas con criterio y seguridad.