migration-architect

Visão geral do skill migration-architect

Para que serve o migration-architect

O skill migration-architect ajuda a planejar migrações de alto risco em software, bancos de dados, serviços e infraestrutura quando indisponibilidade, perda de dados, quebra de APIs ou incerteza no rollback podem gerar risco para o negócio. Ele é mais útil quando você precisa de mais do que um checklist genérico de migração: execução em fases, validação de compatibilidade, planejamento de cutover, reconciliação de dados e um runbook de rollback que equipes de operações consigam seguir de verdade.

Usuários e cenários de migração mais indicados

Use o skill migration-architect se você é arquiteto de software, staff engineer, platform engineer, SRE, líder de banco de dados ou responsável técnico por um programa preparando uma transição em produção. Ele se encaixa em upgrades de PostgreSQL ou outros bancos de dados, migrações de monólito para serviços, substituição de serviços com padrão strangler fig, cutovers para cloud, evolução de schema, versionamento de APIs e migrações com restrições de conformidade, como GDPR, SOX ou PCI DSS.

O que diferencia este skill

O repositório inclui suporte prático além do texto de prompt: scripts/migration_planner.py, scripts/compatibility_checker.py e scripts/rollback_generator.py, além de exemplos de especificações de migração de banco de dados e de serviços. Os arquivos de referência cobrem padrões de migração, técnicas de zero downtime e estratégias de reconciliação de dados, o que torna o skill mais forte para decisões de Software Architecture do que um prompt isolado do tipo “faça um plano para mim”.

Pontos de atenção antes de adotar

Este skill funciona melhor quando você consegue fornecer restrições reais: orçamento de downtime, dependências, mudanças de schema, perfil de tráfego, volume de dados, requisitos de conformidade, gates de validação e gatilhos de rollback. Ele não substitui testes específicos do ambiente, testes de carga, conhecimento especializado do mecanismo de banco de dados nem aprovação formal de mudança. Trate a saída como um acelerador de planejamento de arquitetura, não como autorização automática para produção.

Como usar o skill migration-architect

Instalação do migration-architect e primeiros arquivos para ler

Instale o skill em um ambiente compatível com Claude Skills usando:

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

Depois, inspecione o skill em:

engineering/skills/migration-architect

Leia primeiro README.md para ver o mapa de componentes e os comandos de quick-start; depois leia SKILL.md para entender o fluxo de trabalho previsto. Revise assets/sample_database_migration.json e assets/sample_service_migration.json antes de criar sua própria entrada, porque eles mostram o nível de detalhe esperado pelos scripts e prompts. Use expected_outputs/ para entender o formato de entregáveis úteis antes de pedir uma saída customizada.

Entradas que tornam o uso do migration-architect mais efetivo

Um prompt fraco diz: “Planeje nossa migração de banco de dados.” Um prompt mais forte dá ao skill contexto suficiente para apoiar decisões:

• tipo de migração: banco de dados, serviço, infraestrutura ou híbrida
• plataformas de origem e destino, versões e modelo de hospedagem
• limite de downtime e tolerância à perda de dados
• volume de dados, contagem de linhas, criticidade das tabelas ou carga de requisições
• serviços dependentes, clientes, jobs, filas, analytics e backups
• mudanças de schema ou API, incluindo riscos de breaking changes
• requisitos de conformidade, auditoria, retenção e criptografia
• métricas de sucesso, consultas de validação, gatilhos de rollback e papéis dos responsáveis

Exemplo 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 dos scripts incluídos

O README mostra o uso por linha de comando para gerar planos e relatórios. Um fluxo típico é:

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

Use scripts/compatibility_checker.py com arquivos de schema antes/depois, como assets/database_schema_before.json e assets/database_schema_after.json, para revelar riscos de compatibilidade. Use scripts/rollback_generator.py depois que o plano de migração já existir, para que as etapas de rollback fiquem alinhadas às fases planejadas em vez de virarem um tratamento genérico de falhas.

Fluxo prático para obter planos melhores

Comece copiando um asset de exemplo para sua própria especificação de migração e substitua cada placeholder por fatos de produção. Peça ao skill um plano inicial e, em seguida, solicite separadamente um relatório de compatibilidade, um runbook de rollback e um checklist de cutover. Compare o resultado com expected_outputs/sample_database_migration_plan.txt, schema_compatibility_report.txt e rollback_runbook.txt para verificar se a saída está específica o suficiente para revisão por engenharia, SRE, segurança e responsáveis de negócio.

FAQ do skill migration-architect

O migration-architect serve apenas para migrações de banco de dados?

Não. O repositório inclui exemplos de migração de banco de dados e de serviços. O caminho de banco de dados é especialmente concreto porque inclui assets de schema antes/depois e verificação de compatibilidade, mas o exemplo de serviço dá suporte a migração com padrão strangler fig, compatibilidade de endpoints, mudanças de perfil de carga, dependências de clientes e continuidade de sessão.

Por que isso é melhor do que um prompt comum de migração?

Um prompt comum costuma gerar um checklist plausível. O skill migration-architect é estruturado em torno de padrões de migração, técnicas de zero downtime, análise de compatibilidade, reconciliação de dados e geração de rollback. Os scripts incluídos e as saídas esperadas facilitam a criação de artefatos parecidos com runbooks de engenharia, em vez de simples notas estratégicas.

Iniciantes podem usar o skill migration-architect?

Sim, mas iniciantes devem começar pelos arquivos JSON de exemplo e evitar pular restrições. O skill pode ensinar o formato do planejamento, mas pressupõe que você consiga identificar sistemas, dependências, data stores, limites operacionais e necessidades de validação. Se esses fatos ainda forem desconhecidos, use a primeira rodada para gerar perguntas de descoberta antes de pedir um plano final.

Quando eu não devo usar este skill?

Não dependa apenas do migration-architect para recuperação emergencial em produção, tuning de banco de dados específico de fornecedor, aprovação jurídica de conformidade ou mudanças que exigem acesso profundo a infraestrutura proprietária. Ele também é pouco adequado para migrações triviais sem usuários em produção, sem risco de compatibilidade e sem necessidade de rollback.

Como melhorar o skill migration-architect

Melhore os resultados do migration-architect com restrições mais precisas

O modo de falha mais comum é um plano que parece completo, mas não pode ser executado. Evite isso informando números concretos: downtime máximo, RPO/RTO, tamanho dos dados, pico de tráfego, janelas de batch, tolerância a replication lag, limite de tempo para rollback e quem pode aprovar cada gate. Substitua frases vagas como “downtime mínimo” por limites mensuráveis, como “no máximo 5 minutos de indisponibilidade para escrita”.

Adicione detalhes de validação e reconciliação

Para trabalho com banco de dados, inclua chaves primárias, contagens de linhas, tabelas críticas, mudanças de schema, índices, constraints e consultas de validação representativas. Para trabalho com serviços, inclua listas de endpoints, status codes esperados, garantias de compatibilidade, estratégia de divisão de tráfego, metas de latência e versões de clientes. O skill tem melhor desempenho quando consegue transformar esses fatos em gates, smoke tests e verificações de reconciliação.

Evolua do plano para o runbook

Não pare no primeiro plano de migração. Peça uma revisão de riscos, depois um runbook de rollback e, em seguida, um checklist para operadores. Um bom prompt de acompanhamento é: “Review this plan for hidden coupling, missing validation gates, rollback ambiguity, and data reconciliation gaps. Return only changes that would reduce production risk.” Isso transforma o migration-architect de planejador em assistente de revisão.

Estenda o repositório para o seu ambiente

Para melhorar o skill migration-architect em usos internos recorrentes, adicione templates específicos da organização: gates de aprovação, contatos de incidente, comandos do provedor de cloud, procedimentos de backup de banco de dados, dashboards de observabilidade, padrões de feature flags e verificações de monitoramento pós-cutover. Mantenha esses itens como arquivos de referência reutilizáveis, em vez de enterrá-los em um único prompt, para que futuros planos de migração herdem os mesmos padrões operacionais.