migration-architect

migration-architect skill 概覽

migration-architect 的用途

migration-architect skill 可協助規劃高風險的軟體、資料庫、服務與基礎架構遷移；這類遷移一旦發生停機、資料遺失、API 相容性破壞，或回復流程不明確，就可能造成業務風險。當你需要的不只是通用遷移檢查清單，而是分階段執行、相容性驗證、切換規劃、資料對帳，以及營運團隊真正能照著執行的 rollback runbook 時，migration-architect 特別有用。

最適合的使用者與遷移情境

如果你是軟體架構師、staff engineer、平台工程師、SRE、資料庫負責人，或正在準備 production transition 的技術專案負責人，可以使用 migration-architect skill。它適合 PostgreSQL 或其他資料庫升級、monolith-to-service 遷移、strangler-fig 服務替換、雲端切換、schema evolution、API versioning，以及受 GDPR、SOX、PCI DSS 等合規限制影響的遷移。

這個 skill 的不同之處

這個 repository 不只提供 prompt 文字，還包含實務支援：scripts/migration_planner.py、scripts/compatibility_checker.py、scripts/rollback_generator.py，以及資料庫與服務遷移規格範例。參考檔涵蓋 migration patterns、zero-downtime techniques 與 data reconciliation strategies，因此在 Software Architecture 決策上，比一次性的「幫我做一份計畫」prompt 更有用。

採用前需要考量的事

當你能提供真實限制條件時，這個 skill 的效果最好：downtime budget、dependencies、schema changes、traffic profile、data volume、compliance requirements、validation gates 與 rollback triggers。它不能取代針對環境的測試、load testing、資料庫引擎專業知識，或正式的 change approval。請把它的輸出視為加速架構規劃的工具，而不是自動核准上 production 的依據。

如何使用 migration-architect skill

migration-architect 安裝與優先閱讀的檔案

在相容 Claude Skills 的環境中安裝此 skill：

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

接著到以下位置查看 skill：

engineering/skills/migration-architect

先閱讀 README.md，了解 component map 與 quick-start commands；再閱讀 SKILL.md，掌握預期工作流程。撰寫自己的 input 前，請先檢視 assets/sample_database_migration.json 與 assets/sample_service_migration.json，因為它們示範了 scripts 與 prompts 預期的細節程度。使用 expected_outputs/ 了解有用 deliverables 的形式，再要求客製化輸出。

讓 migration-architect 用起來更有效的輸入

較弱的 prompt 會說：「Plan our database migration.」更好的 prompt 會提供足以支援決策的背景：

• migration type: database、service、infrastructure 或 hybrid
• source and target platforms、版本與 hosting model
• downtime limit 與 data-loss tolerance
• data volume、row counts、table criticality 或 request load
• dependent services、clients、jobs、queues、analytics 與 backups
• schema 或 API changes，包含 breaking-change concerns
• compliance、audit、retention 與 encryption requirements
• success metrics、validation queries、rollback triggers 與 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.”

使用內建 scripts

README 會示範用 command line 產生計畫與報告。典型工作流程如下：

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

使用 scripts/compatibility_checker.py 搭配 before/after schema files，例如 assets/database_schema_before.json 與 assets/database_schema_after.json，可以找出相容性風險。請在 migration plan 已經存在後再使用 scripts/rollback_generator.py，讓 rollback steps 能對齊已規劃的階段，而不是變成泛泛的失敗處理。

產出更好計畫的實務流程

先複製一份 sample asset 作為自己的 migration spec，然後把每個 placeholder 都替換成 production 事實。先請 skill 產出初版計畫，再分別要求 compatibility report、rollback runbook 與 cutover checklist。把結果拿來和 expected_outputs/sample_database_migration_plan.txt、schema_compatibility_report.txt、rollback_runbook.txt 比對，確認輸出是否具體到足以讓 engineering、SRE、security 與 business owners 審閱。

migration-architect skill 常見問題

migration-architect 只適用於資料庫遷移嗎？

不是。這個 repository 包含資料庫與服務遷移範例。資料庫路徑特別具體，因為它包含 before/after schema assets 與 compatibility checking；但服務範例也支援 strangler-fig migration、endpoint compatibility、load profile changes、client dependencies 與 session continuity。

這比一般 migration prompt 好在哪裡？

一般 prompt 往往會產生看起來合理的檢查清單。migration-architect skill 則是圍繞 migration patterns、zero-downtime techniques、compatibility analysis、data reconciliation 與 rollback generation 來設計。內建 scripts 與 expected outputs 讓你更容易建立接近 engineering runbooks 的 artifacts，而不只是策略筆記。

初學者可以使用 migration-architect skill 嗎？

可以，但初學者應該從 sample JSON files 開始，並避免跳過限制條件。這個 skill 可以幫你學會規劃的結構，但它假設你能辨識 systems、dependencies、data stores、operational limits 與 validation needs。如果這些事實還不清楚，請先用第一輪輸出產生 discovery questions，再要求最終計畫。

什麼情況不該使用這個 skill？

不要單靠 migration-architect 處理緊急 live recovery、vendor-specific database tuning、legal compliance signoff，或需要深入存取專有基礎架構的變更。若只是沒有 production users、沒有相容性風險、也不需要 rollback 的簡單遷移，它也不太適合。

如何改進 migration-architect skill

用更明確的限制改善 migration-architect 結果

最常見的失敗模式，是計畫看似完整卻無法執行。避免這點的方法是提供硬性數字：maximum downtime、RPO/RTO、data size、peak traffic、batch windows、replication lag tolerance、rollback time limit，以及每個 gate 由誰核准。請把「minimal downtime」這類模糊說法，改成可衡量的門檻，例如「write unavailability 不超過 5 分鐘」。

補上驗證與對帳細節

資料庫工作請包含 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 時，表現會更好。

從 plan 逐步迭代成 runbook

不要停在第一份 migration plan。接著要求 risk review，再要求 rollback runbook，最後要求 operator checklist。一個實用的 follow-up 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 從規劃工具進一步變成審查助手。

依你的環境擴充 repository

若要讓 migration-architect skill 更適合內部反覆使用，請加入組織專屬 templates：approval gates、incident contacts、cloud provider commands、database backup procedures、observability dashboards、feature flag standards 與 post-cutover monitoring checks。請把這些內容保存為可重用的 reference files，而不是埋在單一 prompt 裡，這樣未來的 migration plans 才能沿用相同的營運標準。