addyosmani/agent-skills

Envío y Lanzamiento

Resumen

Lanza con confianza. El objetivo no es solo desplegar, sino desplegar de forma segura, con monitoreo implementado, un plan de reversión listo y una comprensión clara de cómo se ve el éxito. Cada lanzamiento debe ser reversible, observable e incremental.

Cuándo usar

• Desplegar una funcionalidad a producción por primera vez
• Lanzar un cambio significativo a los usuarios
• Migrar datos o infraestructura
• Abrir un programa beta o de acceso temprano
• Cualquier despliegue que conlleve riesgo (todos)

La lista de verificación previa al lanzamiento

Calidad del código

• Todas las pruebas pasan (unitarias, integración, e2e)
• La compilación se realiza sin advertencias
• Lint y verificación de tipos pasan
• Código revisado y aprobado
• Sin comentarios TODO que deban resolverse antes del lanzamiento
• Sin declaraciones console.log de depuración en código de producción
• El manejo de errores cubre los modos de fallo esperados

Seguridad

• Sin secretos en código o control de versiones
• La auditoría de dependencias del ecosistema (npm audit, pip-audit, cargo audit, ...) no muestra vulnerabilidades críticas o altas
• Validación de entrada en todos los endpoints orientados al usuario
• Verificaciones de autenticación y autorización implementadas
• Cabeceras de seguridad configuradas (CSP, HSTS, etc.)
• Limitación de tasa en endpoints de autenticación
• CORS configurado para orígenes específicos (no comodín)

Rendimiento

• Core Web Vitals dentro de los umbrales "Bueno"
• Sin consultas N+1 en rutas críticas
• Imágenes optimizadas (compresión, tamaños responsivos, carga diferida)
• Tamaño del bundle dentro del presupuesto
• Las consultas a la base de datos tienen índices apropiados
• Caché configurada para activos estáticos y consultas repetidas

Accesibilidad

• La navegación por teclado funciona para todos los elementos interactivos
• El lector de pantalla puede transmitir el contenido y la estructura de la página
• El contraste de color cumple con WCAG 2.1 AA (4.5:1 para texto)
• La gestión del foco es correcta para modales y contenido dinámico
• Los mensajes de error son descriptivos y están asociados a los campos del formulario
• Sin advertencias de accesibilidad en axe-core o Lighthouse

Infraestructura

• Variables de entorno configuradas en producción
• Migraciones de base de datos aplicadas (o listas para aplicar)
• DNS y SSL configurados
• CDN configurado para activos estáticos
• Registro de logs y reportes de errores configurado
• El endpoint de verificación de estado existe y responde

Documentación

• README actualizado con cualquier nuevo requisito de configuración
• Documentación de API actualizada
• ADRs escritos para cualquier decisión arquitectónica
• Changelog actualizado
• Documentación orientada al usuario actualizada (si aplica)

Estrategia de Feature Flags

Despliega detrás de feature flags para desacoplar el despliegue del lanzamiento:

// Verificación de feature flag
const flags = await getFeatureFlags(userId);

if (flags.taskSharing) {
  // Nueva funcionalidad: compartir tareas
  return <TaskSharingPanel task={task} />;
}

// Comportamiento existente por defecto
return null;

Ciclo de vida del feature flag:

1. DESPLEGAR con flag APAGADO     → El código está en producción pero inactivo
2. HABILITAR para equipo/beta     → Pruebas internas en el entorno de producción
3. DESPLIEGUE GRADUAL             → 5% → 25% → 50% → 100% de usuarios
4. MONITOREAR en cada etapa       → Observar tasas de error, rendimiento, comentarios de usuarios
5. LIMPIAR                        → Eliminar el flag y la ruta de código muerta tras el despliegue completo

Reglas:

• Cada feature flag tiene un propietario y una fecha de vencimiento
• Limpiar flags dentro de las 2 semanas posteriores al despliegue completo
• No anidar feature flags (crea combinaciones exponenciales)
• Probar ambos estados del flag (activado y desactivado) en CI

Despliegue por etapas

La secuencia de despliegue

1. DESPLEGAR en staging
   └── Suite de pruebas completa en el entorno de staging
   └── Prueba manual de humo de flujos críticos

2. DESPLEGAR en producción (feature flag APAGADO)
   └── Verificar que el despliegue fue exitoso (verificación de estado)
   └── Comprobar el monitoreo de errores (sin nuevos errores)

3. HABILITAR para el equipo (flag ACTIVADO para usuarios internos)
   └── El equipo usa la funcionalidad en producción
   └── Ventana de monitoreo de 24 horas

4. DESPLIEGUE CANARY (flag ACTIVADO para el 5% de usuarios)
   └── Monitorear tasas de error, latencia, comportamiento del usuario
   └── Comparar métricas: canary vs. línea base
   └── Ventana de monitoreo de 24-48 horas
   └── Avanzar solo si se superan todos los umbrales (ver tabla abajo)

5. AUMENTO GRADUAL (25% -> 50% -> 100%)
   └── Mismo monitoreo en cada paso
   └── Capacidad de revertir al porcentaje anterior en cualquier momento

6. DESPLIEGUE COMPLETO (flag ACTIVADO para todos los usuarios)
   └── Monitorear durante 1 semana
   └── Limpiar el feature flag

Umbrales de decisión de despliegue

Utiliza estos umbrales para decidir si avanzar, mantener o revertir en cada etapa:

Métrica	Avanzar (verde)	Mantener e investigar (amarillo)	Revertir (rojo)
Tasa de error	Dentro del 10% de la línea base	10-100% por encima de la línea base	>2x la línea base
Latencia P95	Dentro del 20% de la línea base	20-50% por encima de la línea base	>50% por encima de la línea base
Errores JS del cliente	Sin nuevos tipos de error	Nuevos errores en <0,1% de sesiones	Nuevos errores en >0,1% de sesiones
Métricas de negocio	Neutral o positivo	Disminución <5% (puede ser ruido)	Disminución >5%

Cuándo revertir

Revertir inmediatamente si:

• La tasa de error aumenta más de 2x la línea base
• La latencia P95 aumenta más del 50%
• Los problemas reportados por usuarios se disparan
• Se detectan problemas de integridad de datos
• Se descubre una vulnerabilidad de seguridad

Monitoreo y observabilidad

Qué monitorear

Métricas de aplicación:
├── Tasa de error (total y por endpoint)
├── Tiempo de respuesta (p50, p95, p99)
├── Volumen de solicitudes
├── Usuarios activos
└── Métricas clave de negocio (conversión, engagement)

Métricas de infraestructura:
├── Uso de CPU y memoria
├── Uso del pool de conexiones de base de datos
├── Espacio en disco
├── Latencia de red
└── Profundidad de cola (si aplica)

Métricas del cliente:
├── Core Web Vitals (LCP, INP, CLS)
├── Errores de JavaScript
├── Tasas de error de API desde la perspectiva del cliente
└── Tiempo de carga de página

Reporte de errores

// Configurar un límite de error con reporte
class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    // Reportar al servicio de seguimiento de errores
    reportError(error, {
      componentStack: info.componentStack,
      userId: getCurrentUser()?.id,
      page: window.location.pathname,
    });
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallback onRetry={() => this.setState({ hasError: false })} />;
    }
    return this.props.children;
  }
}

// Reporte de errores del lado del servidor
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  reportError(err, {
    method: req.method,
    url: req.url,
    userId: req.user?.id,
  });

  // No exponer detalles internos a los usuarios
  res.status(500).json({
    error: { code: 'INTERNAL_ERROR', message: 'Algo salió mal' },
  });
});

Verificación posterior al lanzamiento

En la primera hora después del lanzamiento:

1. Verificar que el endpoint de estado devuelve 200
2. Verificar el panel de monitoreo de errores (sin nuevos tipos de error)
3. Verificar el panel de latencia (sin regresión)
4. Probar el flujo crítico de usuario manualmente
5. Verificar que los logs fluyen y son legibles
6. Confirmar que el mecanismo de reversión funciona (prueba en seco si es posible)

Puerta de liberación de presupuesto de errores

El presupuesto de errores de tu servicio (la fracción de solicitudes o tiempo que tu SLO permite fallar) determina si es seguro lanzar. Úsalo como una puerta objetiva, no como una negociación:

Presupuesto restante > 20%  →  Lanzar normalmente; monitorear de cerca
Presupuesto restante 0–20%  →  Solo despliegues lentos; sin cambios de alto riesgo
Presupuesto agotado         →  Congelar trabajo de funcionalidades; enfocarse completamente en la confiabilidad
El presupuesto se reinicia  →  Reanudar ritmo normal; integrar la corrección que lo recuperó

Una alta tasa de consumo durante un canary (consumiendo presupuesto más rápido que el ritmo de la línea base) es una señal de mantener en la tabla de umbrales de despliegue anterior: trátalo igual que una tasa de error elevada.

Estrategia de reversión

Cada despliegue necesita un plan de reversión antes de que ocurra:

## Plan de reversión para [Funcionalidad/Lanzamiento]

### Condiciones de activación
- Tasa de error > 2x la línea base
- Latencia P95 > [X]ms
- Reportes de usuarios sobre [problema específico]

### Pasos de reversión
1. Deshabilitar feature flag (si aplica)
   O
1. Desplegar versión anterior: `git revert <commit> && git push`
2. Verificar reversión: verificación de estado, monitoreo de errores
3. Comunicar: notificar al equipo sobre la reversión

### Consideraciones de base de datos
- La migración [X] tiene una reversión: `npx prisma migrate rollback`
- Datos insertados por la nueva funcionalidad: [conservados / limpiados]

### Tiempo de reversión
- Feature flag: < 1 minuto
- Redesplegar versión anterior: < 5 minutos
- Reversión de base de datos: < 15 minutos

Ver también

• Para la Definición de Hecho a nivel de proyecto que todo cambio debe superar antes de esta lista de verificación, consulta ../../references/definition-of-done.md
• Para comprobaciones de seguridad previas al lanzamiento, consulta ../../references/security-checklist.md
• Para la lista de verificación de rendimiento previa al lanzamiento, consulta ../../references/performance-checklist.md
• Para la verificación de accesibilidad antes del lanzamiento, consulta ../../references/accessibility-checklist.md
• Para las reglas de alerta y umbrales vinculados a SLO, consulta observability-and-instrumentation

Racionalizaciones comunes

Racionalización	Realidad
"Funciona en staging, funcionará en producción"	La producción tiene datos, patrones de tráfico y casos extremos diferentes. Monitorea después del despliegue.
"No necesitamos feature flags para esto"	Cada funcionalidad se beneficia de un interruptor de apagado. Incluso los cambios "simples" pueden romper cosas.
"El monitoreo es sobrecarga"	No tener monitoreo significa que descubres problemas por quejas de usuarios en lugar de paneles de control.
"Agregaremos monitoreo después"	Agréguelo antes del lanzamiento. No puedes depurar lo que no puedes ver.
"Revertir es admitir fracaso"	Revertir es ingeniería responsable. Lanzar una funcionalidad rota es el fracaso.
"La tasa de error se ve bien, sigamos lanzando"	Revisa la tasa de consumo, no solo la tasa de error actual. Consumir presupuesto más rápido que la línea base es una señal de mantener incluso cuando los umbrales individuales están en verde.

Banderas rojas

• Desplegar sin un plan de reversión
• Sin monitoreo o reporte de errores en producción
• Lanzamientos de gran impacto (todo a la vez, sin staging)
• Feature flags sin fecha de vencimiento o propietario
• Nadie monitoreando el despliegue durante la primera hora
• Configuración del entorno de producción hecha de memoria, no con código
• "Es viernes por la tarde, lancemos"
• Presupuesto de errores agotado pero el trabajo de funcionalidades continúa sin cambios

Verificación

Antes de desplegar:

• Lista de verificación previa al lanzamiento completada (todas las secciones en verde)
• Feature flag configurado (si aplica)
• Plan de reversión documentado
• Paneles de monitoreo configurados
• Equipo notificado del despliegue

Después de desplegar:

• La verificación de estado devuelve 200
• La tasa de error es normal
• La latencia es normal
• El flujo crítico de usuario funciona
• Los logs fluyen
• Reversión probada o verificada lista

Para cada servicio lanzado:

• Política de presupuesto de errores implementada: saber qué acción tomar cuando el presupuesto baja del 20% y cuando se agota