Plan de adopción y riesgos

Adoptar desarrollo guiado por specs sin añadir burocracia al flujo Scrum exige hacerlo de forma incremental y medible. Este plan lo divide en fases con un criterio de salida claro.

Plan por fases

Fase	Duración	Alcance	Criterio de salida
0. Preparación	1 semana	Formación, elección del piloto, revisión con protección de datos	El equipo tiene el modelo mental y el piloto está elegido
1. Piloto manual	Sprints 1–2	openspec init, CLAUDE.md, config.yaml, convención de nombres, revisión de specs en la PR y las skills grill-with-docs y tdd. Sin MCP	5 o más changes archivados y feedback del equipo
2. Integración con el backlog	Sprint 3	MCP de solo lectura y comando de ticket a propuesta	Propuestas generadas desde tickets sin retrabajo mayor
3. Automatización	Sprint 4 en adelante	Validación en CI como validación obligatoria (la verja), hook Stop, subagente verificador, CODEOWNERS sobre openspec/specs/ y estados por automatización	Pipeline obligatoria en main
4. Extensión	Posterior	Resto de proyectos y revisión automática en CI	Adopción en todos los repositorios activos

Elegir el proyecto piloto

Busca una aplicación en mantenimiento activo, con cobertura de tests razonable, un equipo motivado y un impacto de negocio medio (no crítico). Empieza con cambios reales y pequeños de la semana: un bug con regla de negocio, un endpoint nuevo con escenarios de error y un refactor.

Definition of Done

Añade a la definición de hecho del equipo:

• Change creado y propuesta revisada antes de implementar (o etiqueta no-spec justificada).
• Tests de los escenarios escritos y vistos en rojo antes de implementar, en cambios con comportamiento nuevo o bugfix.
• Cada escenario cubierto por un test automatizado; la tabla del verificador no tiene filas «sin cubrir».
• Change archivado en la misma PR y openspec/specs/ actualizado.
• openspec validate --strict en verde en la pipeline; el verde local no basta.

Métricas para evaluar el piloto

• Retrabajo: iteraciones de código tras la revisión. Se espera que baje.
• Defectos escapados en historias con spec frente a las que no la tienen.
• Tiempo de ciclo por historia: igual o menor tras la curva de aprendizaje.
• Cobertura de escenarios: porcentaje con test; el objetivo es el 100 %.
• Omisiones detectadas antes del merge, por la revisión de la propuesta o por el verificador.
• Coste en tokens por historia.
• Percepción del equipo, con una encuesta breve en la retrospectiva.

Criterio de corte: si sube la trazabilidad pero también los defectos y el tiempo de ciclo sin reducir riesgos, el enfoque no ha demostrado valor y hay que replantearlo.

Riesgos y mitigaciones

Riesgo	Mitigación
Revisión de specs «de trámite»: se aprueba sin leer	Checklist de revisión, rotación de revisores y repaso en las retros
Rellenar specs de todo el código existente	Política brownfield: solo specs de lo que se toca. Ver proyectos existentes
Datos personales en tickets y código enviados al modelo	Revisión con protección de datos, plantilla de ticket sin datos reales y deny de ficheros sensibles
Specs desalineadas con el código	Archive dentro de la PR, validación en la pipeline y subagente verificador
«Válido» confundido con «correcto»: specs bien formadas pero erróneas pasan la pipeline	El validador solo comprueba la forma; revisión humana del significado y trazabilidad de cada escenario a su test. Ver Gobierno del cambio
openspec/specs/ actualizado fuera de una PR	Archive solo dentro de la PR, CODEOWNERS y rama protegida sobre esa carpeta
El agente ajusta los tests para que pasen	Tests de los escenarios escritos y revisados antes de implementar; cualquier cambio posterior en ellos se revisa en la PR
El agente modifica el backlog	MCP en solo lectura y estados por automatizaciones nativas
Skills de terceros que se actualizan solas	Cambian el comportamiento del agente sin revisión: instálalas como ficheros versionados y actualízalas por PR. Ver Skills complementarias
Solape de comandos de skills con /opsx:*	Selección cerrada de skills; una sola fuente para specs y tareas
Versiones y tutoriales desactualizados	Versión fijada y openspec update controlado
Rotura por actualizar OpenSpec	Versión fijada en CI y actualización en una rama dedicada
Limitación del MCP remoto de Azure DevOps con Claude Code	Servidor local; revisa el estado periódicamente
Cambios sin spec por urgencia	Etiqueta no-spec explícita y visible, con revisión periódica de su uso
Coste de tokens	Modelo por fase y medición por historia

Datos personales y RGPD

Antes de conectar un agente a tickets, código o repositorios con datos personales, informa a tu delegado de protección de datos y deja por escrito qué datos pueden llegar al modelo. Es la condición previa de la fase 2 del plan.

Checklist de arranque del piloto

• Node 20.19 o superior y OpenSpec instalado en los puestos del equipo.
• Telemetría desactivada.
• openspec init ejecutado con las herramientas que usa el equipo.
• CLAUDE.md y openspec/config.yaml redactados con el stack y el dominio reales.
• Skills seleccionadas instaladas como ficheros versionados en .claude/skills/.
• Glosario único (GLOSSARY.md) referenciado desde config.yaml.
• Convención de nombres acordada y documentada.
• Plantilla de PR y Definition of Done actualizadas.
• Delegado de protección de datos informado.
• Primer change real elegido para el sprint.

Las plantillas de PR y de ticket están en Plantillas.

Antes de abrir la PR

Repasa esta lista en cada change, no solo durante el piloto:

• Cada requisito usa SHALL o MUST y describe comportamiento observable.
• Todos los criterios de aceptación de la historia están cubiertos por escenarios, incluidos los errores y los límites.
• Los MODIFIED reescriben el requisito completo y los REMOVED indican motivo y migración.
• Las specs no contienen detalles de implementación: esos van en design.md.
• openspec validate <change> --strict pasa sin errores.
• La rama y el change se llaman igual.
• tasks.md refleja la realidad: nada marcado que no esté hecho.
• El subagente verificador no deja escenarios sin cubrir.
• El change está archivado y openspec/specs/ se actualiza en esta misma PR.
• Las migraciones de datos, si las hay, tienen plan de vuelta atrás.

Siguiente paso

Comandos de chat