legacy-modernizer

レガシーシステムのモダナイズ

コアワークフロー

1. システムを評価する — コードベース、依存関係、リスク、ビジネス上の制約を分析します。作業を進める前に、依存関係マップとリスク一覧を作成します。

   • 検証チェックポイント： ステップ 2 に進む前に、すべての外部連携とデータ契約が文書化されていることを確認します。

2. 移行を計画する — 各フェーズに明確なロールバック戦略を設けた、段階的なロードマップを設計します。コード分析テンプレートについては references/system-assessment.md を参照してください。

   • 検証チェックポイント： 各フェーズに、定義済みのロールバックのトリガーと担当者がいることを確認します。

3. 安全網を構築する — 本番コードに手を加える前に、特性テストとモニタリングを作成します。既存の動作を 80% 以上カバーすることを目指します。

   • 検証チェックポイント： 特性テストスイートを実行し、変更前のレガシーシステムでテストがすべて成功することを確認してから、先に進みます。

4. 段階的に移行する — フィーチャーフラグを使ってストラングラーフィグパターンを適用します。ファサード経由でトラフィックをルーティングし、負荷を徐々に移行します。

   • 検証チェックポイント： トラフィックを増やすたびに、エラー率とレイテンシの指標がベースラインのしきい値内に収まっていることを確認します（例：5% → 25% → 50% → 100%）。

5. 検証して反復する — レガシーコードを廃止する前に、テストスイート全体を実行し、モニタリングダッシュボードを確認して、ビジネス上の動作が維持されていることを確認します。

   • 検証チェックポイント： レガシー経路を削除する前に、新しいコードが少なくとも 1 回のリリースサイクルにわたり、トラフィック 100% で安定稼働することを実証する必要があります。

リファレンスガイド

状況に応じて、詳細なガイダンスを読み込んでください。

トピック	リファレンス	読み込むタイミング
ストラングラーフィグ	references/strangler-fig-pattern.md	段階的な置き換え、ファサード層、ルーティング
リファクタリング	references/refactoring-patterns.md	サービスの抽出、抽象化による分岐、アダプター
移行	references/migration-strategies.md	データベース、UI、API、フレームワークの移行
テスト	references/legacy-testing.md	特性テスト、ゴールデンマスター、承認
評価	references/system-assessment.md	コード分析、依存関係のマッピング、リスク評価

コード例

ストラングラーフィグファサード（Python）

# facade.py — routes requests to legacy or new service based on a feature flag
import os
from legacy_service import LegacyOrderService
from new_service import NewOrderService

class OrderServiceFacade:
    def __init__(self):
        self._legacy = LegacyOrderService()
        self._new = NewOrderService()

    def get_order(self, order_id: str):
        if os.getenv("USE_NEW_ORDER_SERVICE", "false").lower() == "true":
            return self._new.fetch(order_id)
        return self._legacy.get(order_id)

フィーチャーフラグラッパー

# feature_flags.py — thin wrapper around an environment or config-based flag store
import os

def flag_enabled(flag_name: str, default: bool = False) -> bool:
    """Check whether a migration feature flag is active."""
    return os.getenv(flag_name, str(default)).lower() == "true"

# Usage
if flag_enabled("USE_NEW_PAYMENT_GATEWAY"):
    result = new_gateway.charge(order)
else:
    result = legacy_gateway.charge(order)

特性テストテンプレート（pytest）

# test_characterization_orders.py
# Captures existing legacy behavior as a golden-master safety net.
import pytest
from legacy_service import LegacyOrderService

service = LegacyOrderService()

@pytest.mark.parametrize("order_id,expected_status", [
    ("ORD-001", "SHIPPED"),
    ("ORD-002", "PENDING"),
    ("ORD-003", "CANCELLED"),
])
def test_order_status_golden_master(order_id, expected_status):
    """Fail loudly if legacy behavior changes unexpectedly."""
    result = service.get(order_id)
    assert result["status"] == expected_status, (
        f"Characterization broken for {order_id}: "
        f"expected {expected_status}, got {result['status']}"
    )

制約事項

必ず行うこと

• すべての移行において、本番環境への影響をゼロに保つ
• リファクタリング前に包括的なテストカバレッジを確保する（目標：80% 以上）
• 段階的なロールアウトにはすべてフィーチャーフラグを使用する
• モニタリングとロールバックの手順を実装する
• すべての移行に関する決定とその理由を文書化する
• 既存のビジネスロジックと動作を維持する
• 進捗とリスクを透明性をもって共有する

絶対に行わないこと

• 一括での書き換えや置き換え
• 変更前にレガシーの動作をテストする手順を省略する
• ロールバック手段なしでデプロイする
• 既存の連携や API を壊す
• 新しいコードの技術的負債を無視する
• 適切な検証をせずに移行を急ぐ
• 新しいコードの実証が済む前にレガシーコードを削除する

出力テンプレート

モダナイズを実施する際は、以下を提示してください。

1. 評価の概要（リスク、依存関係、アプローチ）
2. 移行計画（フェーズ、ロールバック戦略、指標）
3. 実装コード（ファサード、アダプター、新しいサービス）
4. テストカバレッジ（特性テスト、統合テスト、E2E）
5. モニタリングの設定（指標、アラート、ダッシュボード）

ナレッジリファレンス

ストラングラーフィグパターン、抽象化による分岐、特性テスト、段階的な移行、フィーチャーフラグ、カナリアデプロイ、API バージョニング、データベースのリファクタリング、マイクロサービスの抽出、技術的負債の削減、ダウンタイムゼロのデプロイ

ドキュメント