migration-architect

migration-architect skill の概要

migration-architect の用途

migration-architect skill は、停止時間、データ損失、API 破壊、ロールバック手順の曖昧さが事業リスクにつながるような、ソフトウェア、データベース、サービス、インフラの高リスクな移行計画を支援します。単なる汎用的な移行チェックリストでは不十分で、段階的な実行計画、互換性検証、切り替え計画、データ照合、運用チームが実際に従えるロールバック手順書まで必要な場合に特に有効です。

向いているユーザーと移行シナリオ

migration-architect skill は、本番環境の移行を準備するソフトウェアアーキテクト、スタッフエンジニア、プラットフォームエンジニア、SRE、データベースリード、技術プログラム責任者に向いています。PostgreSQL などのデータベースアップグレード、モノリスからサービスへの分割、strangler-fig パターンによるサービス置き換え、クラウド移行、スキーマ進化、API バージョニング、GDPR、SOX、PCI DSS などのコンプライアンス制約を伴う移行に適しています。

この skill の違い

このリポジトリには、プロンプト文だけでなく実務向けの支援が含まれています。具体的には、scripts/migration_planner.py、scripts/compatibility_checker.py、scripts/rollback_generator.py に加え、データベース移行とサービス移行のサンプル仕様があります。参照ファイルでは、移行パターン、ゼロダウンタイム手法、データ照合戦略が扱われており、単発の「計画を作って」というプロンプトよりも、Software Architecture の意思決定に使いやすい構成です。

導入時に考慮すべきこと

この skill は、停止許容時間、依存関係、スキーマ変更、トラフィック特性、データ量、コンプライアンス要件、検証ゲート、ロールバックのトリガーなど、実際の制約を提示できるほど効果を発揮します。一方で、環境固有のテスト、負荷テスト、データベースエンジンに関する専門知識、正式な変更承認の代替にはなりません。出力は本番適用の自動承認ではなく、アーキテクチャ計画を加速するための材料として扱ってください。

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 を確認することをおすすめします。これらは、スクリプトやプロンプトが期待する詳細度を示しています。カスタム出力を依頼する前に expected_outputs/ を見て、有用な成果物がどのような形になるかも把握しておくとよいでしょう。

migration-architect を効果的に使うための入力

弱いプロンプトは「データベース移行を計画して」のようなものです。より良いプロンプトでは、判断に使えるだけの文脈を skill に渡します。

• 移行タイプ: database、service、infrastructure、または hybrid
• 移行元・移行先のプラットフォーム、バージョン、ホスティング形態
• 停止時間の上限とデータ損失の許容度
• データ量、行数、重要テーブル、またはリクエスト負荷
• 依存するサービス、クライアント、ジョブ、キュー、分析基盤、バックアップ
• スキーマまたは API の変更点。破壊的変更の懸念も含める
• コンプライアンス、監査、保持、暗号化の要件
• 成功指標、検証クエリ、ロールバックのトリガー、担当者の役割

プロンプト例:

“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

assets/database_schema_before.json や assets/database_schema_after.json のような移行前後のスキーマファイルとあわせて scripts/compatibility_checker.py を使うと、互換性リスクを洗い出せます。scripts/rollback_generator.py は、移行計画ができた後に使ってください。そうすることで、汎用的な障害対応ではなく、計画されたフェーズに沿ったロールバック手順になります。

より良い計画を作るための実務フロー

まずサンプル asset をコピーして自分の移行仕様のたたき台にし、すべてのプレースホルダーを本番の事実で置き換えます。最初に skill に初期計画を依頼し、その後で互換性レポート、ロールバック手順書、切り替えチェックリストを別々に依頼します。結果を expected_outputs/sample_database_migration_plan.txt、schema_compatibility_report.txt、rollback_runbook.txt と比較し、エンジニアリング、SRE、セキュリティ、事業責任者がレビューできるだけの具体性があるか確認してください。

migration-architect skill FAQ

migration-architect はデータベース移行専用ですか？

いいえ。このリポジトリには、データベース移行とサービス移行の例が含まれています。データベース向けの流れは、移行前後のスキーマ asset と互換性チェックがあるため特に具体的です。一方でサービス移行の例も、strangler-fig migration、エンドポイント互換性、負荷プロファイルの変化、クライアント依存関係、セッション継続性を扱えます。

通常の移行プロンプトより何が優れていますか？

通常のプロンプトでも、それらしいチェックリストは生成できます。migration-architect skill は、移行パターン、ゼロダウンタイム手法、互換性分析、データ照合、ロールバック生成を軸に構成されています。同梱スクリプトと期待出力があるため、戦略メモではなく、エンジニアリングの runbook に近い成果物を作りやすくなっています。

初心者でも migration-architect skill を使えますか？

はい。ただし初心者はサンプル JSON ファイルから始め、制約条件を省略しないようにしてください。この skill は計画の型を学ぶ助けになりますが、システム、依存関係、データストア、運用上の制限、検証の必要性を特定できることを前提にしています。これらの情報が不明な場合は、最終計画を求める前に、初回の出力で調査質問を生成させるとよいでしょう。

この skill を使わないほうがよい場面は？

緊急の本番復旧、ベンダー固有のデータベースチューニング、法務・コンプライアンス上の正式承認、独自インフラへの深いアクセスが必要な変更について、migration-architect だけに依存しないでください。また、本番ユーザーが存在せず、互換性リスクもロールバック要件もない単純な移行にはあまり向いていません。

migration-architect skill を改善する方法

migration-architect の結果は制約を具体化すると改善する

最もよくある失敗は、一見完成しているのに実行できない計画です。これを避けるには、最大停止時間、RPO/RTO、データサイズ、ピークトラフィック、バッチウィンドウ、レプリケーション遅延の許容値、ロールバックに使える時間、各ゲートの承認者などを数値で示します。「最小限の停止時間」のような曖昧な表現は、「書き込み不可は最大 5 分まで」のように測定可能なしきい値へ置き換えてください。

検証とデータ照合の詳細を追加する

データベース作業では、主キー、行数、重要テーブル、スキーマ変更、インデックス、制約、代表的な検証クエリを含めます。サービス作業では、エンドポイント一覧、期待するステータスコード、互換性の約束、トラフィック分割戦略、レイテンシ目標、クライアントバージョンを含めます。これらの事実を渡すほど、skill はゲート、スモークテスト、照合チェックに落とし込みやすくなります。

計画から runbook へ反復する

最初の移行計画で止めないでください。リスクレビューを依頼し、その後にロールバック手順書、さらにオペレーター向けチェックリストを依頼します。有用な追加プロンプトの例は次のとおりです。“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 を社内で繰り返し使いやすくするには、組織固有のテンプレートを追加します。たとえば、承認ゲート、インシデント連絡先、クラウドプロバイダーのコマンド、データベースバックアップ手順、observability ダッシュボード、feature flag の標準、切り替え後の監視チェックなどです。これらは 1 つのプロンプトに埋め込むのではなく、再利用可能な参照ファイルとして保持してください。そうすれば、今後の移行計画にも同じ運用基準を継承できます。