migration-architect

migration-architect skill 概览

migration-architect 适合解决什么问题

migration-architect skill 用于规划高风险的软件、数据库、服务和基础设施迁移；在这些场景中，停机、数据丢失、API 破坏性变更或回滚路径不明确都可能带来业务风险。当你需要的不只是通用迁移清单，而是分阶段执行、兼容性验证、切换计划、数据对账，以及运维团队真正能照着执行的回滚 runbook 时，它尤其有价值。

最适合的用户与迁移场景

如果你是软件架构师、staff engineer、平台工程师、SRE、数据库负责人，或正在准备生产环境切换的技术项目负责人，可以使用 migration-architect skill。它适用于 PostgreSQL 或其他数据库升级、单体到服务化迁移、strangler-fig 服务替换、云上切换、schema 演进、API 版本化，以及带有 GDPR、SOX、PCI DSS 等合规约束的迁移。

这个 skill 的不同之处

这个仓库不只是 prompt 文本，还提供了实用支持：scripts/migration_planner.py、scripts/compatibility_checker.py 和 scripts/rollback_generator.py，以及数据库和服务迁移的示例规格。参考文件覆盖迁移模式、零停机技术和数据对账策略，因此在 Software Architecture 决策场景下，它比一次性的“帮我做个计划”prompt 更有支撑力。

采用前需要考虑的事项

当你能提供真实约束时，这个 skill 的效果最好：停机预算、依赖关系、schema 变更、流量画像、数据量、合规要求、验证关卡和回滚触发条件。它不能替代特定环境下的测试、负载测试、数据库引擎专家经验或正式变更审批。应把它的输出视为架构规划加速器，而不是自动获得生产发布授权。

如何使用 migration-architect skill

migration-architect 安装与首先要读的文件

在兼容 Claude Skills 的环境中安装该 skill：

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

然后在以下位置查看该 skill：

engineering/skills/migration-architect

先阅读 README.md，了解组件地图和快速开始命令；再阅读 SKILL.md，理解预期工作流。在编写自己的输入之前，先查看 assets/sample_database_migration.json 和 assets/sample_service_migration.json，因为它们展示了脚本和 prompt 期望的细节粒度。使用 expected_outputs/ 来理解有用交付物应具备的结构，再请求定制化输出。

让 migration-architect 更有效的输入

弱 prompt 可能只是：“Plan our database migration.” 更强的 prompt 会给这个 skill 提供足以支持决策的上下文：

• migration type: database, service, infrastructure, or hybrid
• source and target platforms, versions, and hosting model
• downtime limit and data-loss tolerance
• data volume, row counts, table criticality, or request load
• dependent services, clients, jobs, queues, analytics, and backups
• schema or API changes, including breaking-change concerns
• compliance, audit, retention, and encryption requirements
• success metrics, validation queries, rollback triggers, and owner roles

示例 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.”

使用内置脚本

README 展示了生成计划和报告的命令行用法。一个典型工作流是：

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

使用 scripts/compatibility_checker.py，并传入类似 assets/database_schema_before.json 和 assets/database_schema_after.json 的迁移前/后 schema 文件，以暴露兼容性风险。在迁移计划完成之后再使用 scripts/rollback_generator.py，这样回滚步骤会与已规划的阶段对齐，而不是停留在泛泛的故障处理层面。

制定更高质量计划的实用工作流

先复制一个 sample asset 作为自己的迁移规格，然后把每一个占位信息替换成生产事实。先让这个 skill 生成初始计划，再分别请求兼容性报告、回滚 runbook 和切换检查清单。将结果与 expected_outputs/sample_database_migration_plan.txt、schema_compatibility_report.txt 和 rollback_runbook.txt 对比，判断输出是否具体到足以让工程、SRE、安全和业务负责人评审。

migration-architect skill 常见问题

migration-architect 只适合数据库迁移吗？

不是。仓库中包含数据库和服务迁移示例。数据库路径尤其具体，因为它包含迁移前/后的 schema assets 和兼容性检查；但服务示例也支持 strangler-fig migration、endpoint 兼容性、负载画像变化、客户端依赖和 session 连续性。

它比普通迁移 prompt 好在哪里？

普通 prompt 往往会生成一份看起来合理的清单。migration-architect skill 则围绕迁移模式、零停机技术、兼容性分析、数据对账和回滚生成来组织。内置脚本和 expected outputs 让你更容易产出接近工程 runbook 的交付物，而不是只停留在策略备忘录。

新手可以使用 migration-architect skill 吗？

可以，但新手应从 sample JSON 文件开始，不要跳过约束信息。这个 skill 可以帮助你理解规划形态，但它默认你能够识别系统、依赖、数据存储、运营限制和验证需求。如果这些事实还不清楚，第一次可以先用它生成调研问题，再请求最终计划。

什么时候不应该使用这个 skill？

不要只依赖 migration-architect 来处理紧急线上恢复、供应商特定的数据库调优、法律合规签署，或需要深度访问专有基础设施的变更。对于没有生产用户、没有兼容性风险、也没有回滚要求的简单迁移，它也并不适合。

如何改进 migration-architect skill

用更清晰的约束提升 migration-architect 结果

最常见的失败模式是计划看起来完整，但无法真正执行。避免这种情况的方法是提供硬指标：最大停机时间、RPO/RTO、数据规模、峰值流量、批处理窗口、可接受的复制延迟、回滚时间上限，以及每个 gate 由谁批准。不要使用“minimal downtime”这类模糊说法，而应替换为可衡量阈值，例如“no more than 5 minutes of write unavailability”。

补充验证与对账细节

对于数据库工作，请提供 primary keys、row counts、critical tables、schema changes、indexes、constraints，以及有代表性的 validation queries。对于服务工作，请提供 endpoint lists、expected status codes、compatibility promises、traffic split strategy、latency targets 和 client versions。当这个 skill 能把这些事实转化为 gates、smoke tests 和 reconciliation checks 时，效果会更好。

从计划迭代到 runbook

不要停在第一版迁移计划。先请求风险评审，再请求回滚 runbook，最后请求 operator checklist。一个有用的后续 prompt 是：“Review this plan for hidden coupling, missing validation gates, rollback ambiguity, and data reconciliation gaps. Return only changes that would reduce production risk.” 这会把 migration-architect 从规划工具进一步变成评审助手。

为你的环境扩展仓库

如果希望让 migration-architect skill 更适合内部反复使用，可以添加组织专属模板：approval gates、incident contacts、cloud provider commands、database backup procedures、observability dashboards、feature flag standards 和 post-cutover monitoring checks。把这些内容保留为可复用的 reference files，而不是埋在某一次 prompt 里，这样未来的迁移计划才能继承同一套运营标准。