migration-engineering

移行エンジニアリング

システム境界をまたぐ安全な移行を計画し、実行します。移行とは、移行期間中の正確性、可用性、復旧可能性を維持しながら、データ、スキーマ、インターフェース、インフラストラクチャ、またはサービスを現状から目標の状態へ移すあらゆる変更を指します。

このスキルが担当するのは、システムをまたぐ移行の手法、すなわち互換性の設計、段階的な移行、照合、切り替え、復旧、非推奨化です。単一の技術やサブシステムの実装詳細は担当しません。それらは専門スキルの範囲です。

使用するタイミング

タスクに以下が含まれる場合は、このスキルを読み込みます。

トリガー	例
既存の読み取り側や書き込み側を壊さずに行う必要があるスキーマ変更	「高トラフィックのテーブルに、ダウンタイムなしで NULL 不可の列を追加する」
ストア間または表現形式間のデータ移行	「ユーザープロファイルを Postgres から専用データベースを持つサービスへ移行する」
非推奨期間を設ける API バージョンの移行	「6 か月かけて、利用者を v1 REST から v2 GraphQL へ移行する」
インフラストラクチャまたはサービスの移行	「セルフホストの VM からマネージドプラットフォームへ、複数リージョンにわたってワークロードを移行する」
デュアルランニングと照合が必要なシステム横断の変更	「両方を同期したまま、レガシーの請求エンジンを新しいエンジンに置き換える」
移行における切り替え、ロールバック、または不可逆な手順の計画	「データウェアハウスのスキーマ移行に向けた復旧戦略を定義する」

使用しないタイミング

• 単一技術に関する簡単な修正 — 互換性を保つ期間も、デュアルランニングも、システム横断の調整も必要なく、変更が単一のシステム内に収まる場合は、該当する専門スキルを直接使用します（例：単純な DDL 変更には data-engineering、単一エンドポイントの非推奨化には api-design-and-evolution）。
• 特定のツールに関するハウツーガイド — このスキルが提供するのは手法であり、ベンダー固有の手順ではありません。特定の移行技術、データベースエンジン、API ゲートウェイ、またはインフラストラクチャプラットフォームを指定するものではありません。
• システム境界をまたがない移行 — インプレースのリファクタリング、データやインターフェースの境界を越えないコードの書き換え、単一サービスの構成変更は、移行エンジニアリングの対象外です。
• ロールバックの保証 — このスキルは、常にロールバックが可能だとは主張しません。一部の移行には不可逆な手順が含まれます。そのような手順を明示的に特定し、誤った安全性を示唆するのではなく、受け入れ、コミュニケーション、緊急時対応を計画することが、この手法で求められます。

サービスの切り出しについては、境界が提案されており、移行パターン、共存の形態、またはモジュラーモノリスという代替案の評価が必要な場合に、references/service-extraction-patterns.md を読み込みます。一般的な移行計画を記入する前に、templates/service-extraction-assessment.md を使って根拠をまとめます。このスキルは承認済みの切り出しを順序立てて実行するものであり、モノリスを分割すべきかどうかの判断や、目標アーキテクチャの特定は行いません。

基本的なワークフロー

1. 移行を分類し、範囲を定める

該当する移行の種類を特定します。実際の移行では複数の種類が組み合わさることがよくあります（サービスの切り出しには、データ移行と API 移行の両方が含まれます）。現状、目標の状態、越える境界、互換性要件を伴う種類、および影響を受けるシステム、チーム、利用者を記録します。スキーマ、データ、API、インフラストラクチャ／サービス、サービス切り出しの各移行の分類については、references/migration-types.md を読み込みます。

2. 拡張／縮小の手順を設計する

拡張／縮小パターンは、安全な移行の基本となるプリミティブです。

1. 拡張 — 古いインターフェイス、スキーマ、またはシステムが引き続きサービスを提供している間に、新しいものを追加します。両方が共存し、既存の利用者に影響はありません。
2. 互換性維持期間 — 古いものと新しいものの両方を利用できる、終了条件（日付、メトリクスのしきい値、または登録済みの利用者全員による確認などのイベント）を明確に定めた期間です。
3. 二重稼働または並行運用 — データとサービスの移行では、両方のシステムを同時に稼働させ（デュアル書き込み、比較を伴うデュアル読み取り）、切り替えの判断に必要な証拠を得ます。
4. 縮小 — 期間の終了後、検証によって正確性と完全性が確認できたら、古いインターフェイスを削除します。

すべての移行で4つのフェーズすべてが必要になるわけではありません。スキーマへの追加変更では拡張フェーズのみで済む場合がありますが、複雑なサービスの切り出しでは4つすべてが必要です。

3. バックフィルと照合を計画する

データ移行では、バックフィルの戦略（全件、増分、またはストリーミング（CDC／イベントログ））を選択します。照合では、完全性、正確性、適時性、一貫性の4つの観点でソースとターゲットが一致することを検証します。互換性維持期間中は継続して実行し、切り替え前に合格しなければなりません。照合の失敗は停止条件です。

4. 切り替えを設計する

正確な手順（可能な限り自動化し、事前条件と事後条件を定める）、期間と許容できるダウンタイム、切り替えを一時停止または取り消せる中断ポイント（中断ポイントがない切り替えは、明示的にフラグを立てるべきリスクです）、および進行状況を確認して中止を開始するためのオブザーバビリティを定義します。

5. 復旧経路を定義する

移行の各ステップには、次の4つの復旧分類のうち、必ず1つだけを割り当てます。混同してはいけません。ロールバック（変更を元に戻す）、ロールフォワード（新しい状態のまま修正する）、復元（バックアップ／スナップショットから復旧する）、不可逆（どのレベルでも取り消せない）。不可逆なステップは、実行前に明示的な承認が必要です。「取り消す経路を構築しない選択をした」ことと「物理的に取り消せない」ことを区別してください。どちらの場合も、承認、周知、緊急時対応が必要です。具体的なステップを分類する際は、references/recovery-classification.md を読み込んでください。

6. 非推奨化とクリーンアップを計画する

検証済みの切り替え後、古いシステムを読み取り専用／機能低下モードで運用する非推奨化期間を定義し、古いインターフェイスにまだ依存している利用者を追跡し、古いスキーマ／コードパス／フラグ／設定／認証情報／インフラストラクチャを削除します。また、各段階（期間開始、切り替え予定、切り替え完了、期間終了間近、削除）で周知します。

7. 検証して完了する

完了を宣言する前に、正確性を示す証拠（照合レポート、利用者による検証、エラー率の比較、SLO の遵守状況）を収集し、オブザーバビリティで期待どおりの定常状態が確認できること、復旧手順がテスト済みで不可逆なステップが承認済みであることを確認し、各フェーズの責任者から承認を得ます。

読み込みガイド

参照資料とテンプレートは必要に応じて読み込んでください。一度にすべてを読み込まないでください。

ファイル	読み込むタイミング
references/discovery-brief.md	移行の概念が関連するスキル間でどのように対応するか、このスキルの範囲がどこまでかを理解する必要があるとき
references/migration-types.md	パターンを選ぶ前に、移行（スキーマ、データ、API、インフラストラクチャ／サービス、サービスの切り出し）を分類するとき
references/compatibility-patterns.md	特定の移行タイプについて、前方互換性／後方互換性を設計するとき
references/recovery-classification.md	具体的な移行手順の復旧パス（ロールバック、ロールフォワード、復元、不可逆）を分類するとき
references/planning-fields.md	計画で扱う必要がある構造化計画フィールド（調整、証跡、可観測性、顧客への影響、担当）を作成またはレビューするとき
references/service-extraction-patterns.md	切り出しの境界を評価し、ストラングラー・ルーティング、抽象化による分岐、腐敗防止層、CDC、並行実行のパターンを選択するとき。モジュラーモノリスを維持する基準も含みます
templates/migration-plan.md	すべての構造化フィールドを含む完全な移行計画を作成するとき
templates/compatibility-matrix.md	複数のコンシューマーが関わる移行の互換性マトリクスを作成するとき
templates/reconciliation-plan.md	データ移行の調整戦略を設計するとき
templates/cutover-and-recovery-record.md	切り替え手順、復旧パス、不可逆な手順への確認を記録するとき
templates/service-extraction-assessment.md	境界の証跡、結合度、担当、共存、順序、運用リスク、可逆性、および切り出すかモジュラーモノリスを維持するかの判断を記録するとき

専門分野への振り分け

移行エンジニアリングは各分野の専門家と連携しますが、その手法を重複して扱うことはありません。実装の詳細は、該当するサブシステムを担当するスキルに振り分けてください。

移行に関する事項	振り分け先
分解の妥当性と目標境界の判断	software-architecture。このスキルでは、承認済みの移行を順序立てます
API コントラクトの設計、バージョニング方針、非推奨化の仕組み	api-design-and-evolution
データベーススキーマの進化、ETL／ELT パイプラインの設計、バックフィル作業	data-engineering
移行中のインフラストラクチャのプロビジョニング、サービスネットワーキング、シークレット管理	platform-engineering
リリースの順序、段階的デリバリー、カナリアリリース、アーティファクトのプロモーション	release-engineering
移行中の SLO 定義、エラーバジェット、運用準備、インシデント対応	site-reliability-engineering
作業の分解、依存関係のマッピング、クリティカルパス、担当の割り当て	implementation-planning
脅威モデリング、移行対象範囲のセキュリティレビュー、認証境界の変更	secure-software-engineering
テスト戦略、回帰テストの網羅性、移行中の検証ゲート	qa-methodology
検証結果の判定、証跡の基準、境界テスト	verification-methodology

同一ウェーブおよび今後のスキルへのルーティング

移行のエビデンス（照合レポート、切り替え記録、復旧経路の分類、非推奨化の追跡）は、本番稼働準備の評価に活用されます。本番稼働準備スキルは、サービスが本番環境での運用に備えられていることを示すエビデンスとして、移行計画を取り込みます。

本番運用エクセレンスバンドルは、移行エンジニアリングを本番稼働準備、レジリエンスと復旧、キャパシティとコストのエンジニアリング、インシデントからの学習、プライバシーエンジニアリングと組み合わせます。移行エンジニアリングは、本番運用エクセレンスのライフサイクルに安全な変更という側面をもたらします。

プロダクトライフサイクルスキルへのルーティング

機能の廃止や製品の提供終了が移行のきっかけとなる場合は、廃止の決定記録、非推奨化のタイムライン、顧客対応計画について、プロダクトライフサイクル学習と連携してください。