migration-architect

Descripción general de migration-architect skill

Para qué sirve migration-architect

La migration-architect skill ayuda a planificar migraciones de alto riesgo de software, bases de datos, servicios e infraestructura cuando el tiempo de inactividad, la pérdida de datos, la ruptura de API o la falta de claridad para revertir cambios pueden generar riesgo para el negocio. Es especialmente útil cuando necesitas algo más que una lista genérica de tareas de migración: ejecución por fases, validación de compatibilidad, planificación del cutover, reconciliación de datos y un runbook de rollback que los equipos de operaciones puedan seguir de verdad.

Usuarios y escenarios de migración más adecuados

Usa la migration-architect skill si eres software architect, staff engineer, platform engineer, SRE, responsable de bases de datos o technical program owner y estás preparando una transición a producción. Encaja con actualizaciones de PostgreSQL u otras bases de datos, migraciones de monolito a servicios, reemplazos de servicios con patrón strangler-fig, cutovers a la nube, evolución de esquemas, versionado de API y migraciones con requisitos de cumplimiento como GDPR, SOX o PCI DSS.

Qué hace diferente a esta skill

El repositorio incluye soporte práctico más allá del texto de prompts: scripts/migration_planner.py, scripts/compatibility_checker.py y scripts/rollback_generator.py, además de especificaciones de ejemplo para migraciones de bases de datos y servicios. Los archivos de referencia cubren patrones de migración, técnicas de cero downtime y estrategias de reconciliación de datos, lo que hace que la skill sea más sólida para decisiones de Software Architecture que un prompt puntual del tipo “hazme un plan”.

Consideraciones antes de adoptarla

Esta skill funciona mejor cuando puedes aportar restricciones reales: presupuesto de downtime, dependencias, cambios de esquema, perfil de tráfico, volumen de datos, requisitos de cumplimiento, puertas de validación y disparadores de rollback. No sustituye las pruebas específicas del entorno, las pruebas de carga, la experiencia con el motor de base de datos ni la aprobación formal de cambios. Trata sus resultados como un acelerador de planificación arquitectónica, no como una autorización automática para producción.

Cómo usar migration-architect skill

Instalación de migration-architect y primeros archivos que conviene leer

Instala la skill en un entorno compatible con Claude Skills con:

npx skills add alirezarezvani/claude-skills --skill migration-architect

Luego revisa la skill en:

engineering/skills/migration-architect

Lee primero README.md para ver el mapa de componentes y los comandos de inicio rápido; después, revisa SKILL.md para entender el flujo de trabajo previsto. Consulta assets/sample_database_migration.json y assets/sample_service_migration.json antes de escribir tu propio input, porque muestran el nivel de detalle que esperan los scripts y prompts. Usa expected_outputs/ para entender la forma de los entregables útiles antes de pedir una salida personalizada.

Inputs que hacen más efectivo el uso de migration-architect

Un prompt débil diría: “Plan our database migration.” Un prompt más sólido le da a la skill contexto suficiente para tomar decisiones:

• tipo de migración: base de datos, servicio, infraestructura o híbrida
• plataformas de origen y destino, versiones y modelo de hosting
• límite de downtime y tolerancia a pérdida de datos
• volumen de datos, conteo de filas, criticidad de tablas o carga de solicitudes
• servicios dependientes, clientes, jobs, colas, analítica y backups
• cambios de esquema o de API, incluidas preocupaciones por breaking changes
• requisitos de cumplimiento, auditoría, retención y cifrado
• métricas de éxito, consultas de validación, disparadores de rollback y roles responsables

Ejemplo de prompt:

“Use the migration-architect skill to create a phased zero-downtime migration plan for PostgreSQL 13 on-prem to PostgreSQL 15 managed cloud. Data volume is 2.5 TB. Max downtime is 30 minutes. Critical dependencies are authentication, notification, analytics, and backups. Include compatibility risks, validation gates, reconciliation checks, rollback criteria, and a stakeholder communication timeline.”

Uso de los scripts incluidos

El README muestra cómo usar la línea de comandos para generar planes e informes. Un flujo de trabajo típico es:

python3 scripts/migration_planner.py \
  --input assets/sample_database_migration.json \
  --output migration_plan.json \
  --format both

Usa scripts/compatibility_checker.py con archivos de esquema antes/después como assets/database_schema_before.json y assets/database_schema_after.json para sacar a la luz riesgos de compatibilidad. Usa scripts/rollback_generator.py después de que exista el plan de migración, de modo que los pasos de rollback estén alineados con las fases planificadas y no sean una gestión genérica de fallos.

Flujo de trabajo práctico para obtener mejores planes

Empieza copiando un asset de ejemplo en tu propia especificación de migración y reemplaza cada placeholder por datos reales de producción. Pide a la skill un plan inicial y luego solicita por separado un informe de compatibilidad, un runbook de rollback y una checklist de cutover. Compara el resultado con expected_outputs/sample_database_migration_plan.txt, schema_compatibility_report.txt y rollback_runbook.txt para comprobar si tu salida es lo bastante específica como para que la revisen ingeniería, SRE, seguridad y responsables de negocio.

Preguntas frecuentes sobre migration-architect skill

¿migration-architect sirve solo para migraciones de bases de datos?

No. El repositorio incluye ejemplos de migración de bases de datos y de servicios. La ruta de base de datos es especialmente concreta porque incluye assets de esquema antes/después y verificación de compatibilidad, pero el ejemplo de servicio cubre migración con patrón strangler-fig, compatibilidad de endpoints, cambios en el perfil de carga, dependencias de clientes y continuidad de sesión.

¿En qué mejora a un prompt de migración normal?

Un prompt normal suele producir una checklist plausible. La migration-architect skill está estructurada alrededor de patrones de migración, técnicas de cero downtime, análisis de compatibilidad, reconciliación de datos y generación de rollback. Los scripts incluidos y las salidas esperadas facilitan crear artefactos que se parecen más a runbooks de ingeniería que a notas estratégicas.

¿Pueden usar migration-architect las personas principiantes?

Sí, pero quienes estén empezando deberían partir de los archivos JSON de ejemplo y no saltarse las restricciones. La skill puede enseñar la estructura de planificación, pero asume que puedes identificar sistemas, dependencias, almacenes de datos, límites operativos y necesidades de validación. Si esos datos no se conocen, usa la primera pasada para generar preguntas de descubrimiento antes de pedir un plan final.

¿Cuándo no debería usar esta skill?

No dependas solo de migration-architect para recuperación en vivo durante una emergencia, tuning de bases de datos específico de un proveedor, aprobación legal de cumplimiento o cambios que requieran acceso profundo a infraestructura propietaria. También encaja mal en migraciones triviales sin usuarios en producción, sin riesgo de compatibilidad y sin necesidad de rollback.

Cómo mejorar migration-architect skill

Mejora los resultados de migration-architect con restricciones más precisas

El fallo más común es obtener un plan que suena completo pero no se puede ejecutar. Evítalo dando cifras concretas: downtime máximo, RPO/RTO, tamaño de datos, tráfico pico, ventanas batch, tolerancia a retraso de replicación, límite de tiempo para rollback y quién puede aprobar cada gate. Sustituye frases vagas como “minimal downtime” por umbrales medibles, por ejemplo “no more than 5 minutes of write unavailability.”

Añade detalles de validación y reconciliación

Para trabajo con bases de datos, incluye primary keys, conteos de filas, tablas críticas, cambios de esquema, índices, constraints y consultas de validación representativas. Para trabajo con servicios, incluye listas de endpoints, códigos de estado esperados, compromisos de compatibilidad, estrategia de reparto de tráfico, objetivos de latencia y versiones de clientes. La skill rinde mejor cuando puede convertir esos datos en gates, smoke tests y comprobaciones de reconciliación.

Itera desde el plan hasta el runbook

No te quedes en el primer plan de migración. Pide una revisión de riesgos, luego un runbook de rollback y después una checklist para operadores. Un buen prompt de seguimiento es: “Review this plan for hidden coupling, missing validation gates, rollback ambiguity, and data reconciliation gaps. Return only changes that would reduce production risk.” Así migration-architect pasa de ser un planificador a funcionar también como asistente de revisión.

Extiende el repositorio para tu entorno

Para mejorar la migration-architect skill en usos internos repetidos, añade plantillas específicas de tu organización: gates de aprobación, contactos de incidentes, comandos del proveedor cloud, procedimientos de backup de bases de datos, dashboards de observabilidad, estándares de feature flags y comprobaciones de monitoreo posteriores al cutover. Mantenlas como archivos de referencia reutilizables en lugar de enterrarlas en un único prompt, para que los futuros planes de migración hereden los mismos estándares operativos.