translate-programming-language

プログラミング言語を移行する

このスキルを使って、外部から観測できる動作を損なわずに、本番環境のサーバー／アプリケーションコードを別の言語／ランタイムへ移行します。まずは同等性を維持し、古いランタイムを取り除いてから、移行先の言語に合わせて簡素化します。

基本ルール

• ソースランタイムを最初の基準として扱いますが、公的な標準がある場合は確認します。
• 期待値のフィクスチャを手作業で作成しないでください。固定したソースランタイム、または標準準拠のハーネスを使って生成します。
• 再利用可能な移行ドキュメントには、ドメイン固有の名前、URL、スキーマ、顧客情報、製品情報を含めないでください。
• 言語／ランタイム固有の癖は、ドメインロジックではなく互換性レイヤーにまとめます。
• すべての互換性レイヤーに削除計画を紐付けます。計画には、ソースの動作、移行先の動作、標準／仕様への参照、呼び出し元、切り替え後の移行先を記載します。
• 単体テストで同等性を確認しただけで十分だと考えないでください。切り替え前に、シャドートラフィック／リプレイと、本番環境を想定したベンチマークで検証します。

ワークフロー

1. 移行範囲を定める

   • 関数、モジュール、エンドポイント、メッセージ型、プロトコルハンドラーなど、範囲を狭く定めた契約を選びます。
   • 入力、出力、副作用、状態、クロック、乱数、ロケール、環境変数、ファイルシステム／ネットワークの利用、エラーの動作を洗い出します。
   • 外部から見える契約が、バイト単位で完全一致する必要があるのか、構造的に同等であればよいのか、意味的に同等であればよいのかを決定します。

2. オラクルを生成する

   • oracle-driven-parity.mdを読みます。
   • ソースランタイムと依存関係のバージョンを固定します。
   • 通常のケース、境界値、不正な入力、エラー、副作用について、ソース実装からフィクスチャ出力を生成します。
   • 標準がある場合は、標準に基づくケースを追加し、ソース／移行先のランタイム間で差異が生じる箇所を記録します。

3. 移行後のテストを生成する

   • test-migration.mdを読みます。
   • ソースのテスト、テスト名、データプロバイダー、使用例、API 契約から、移行先の言語で同等性を検証するテストのスタブを生成します。
   • 未完了のスタブを CI で可視化し、スキップ／保留の件数がゼロになるまで、フィクスチャ駆動のテストに置き換えます。
   • 発見した言語／ランタイムの差異ごとに、分岐を網羅するケースを追加します。

4. 移行に関する知見を蓄積する

   • compatibility-knowledge.mdを読みます。
   • 数値キャスト、真偽値の評価、配列／マップ／順序、JSON、URL エンコーディング、正規表現、時刻、暗号、バイナリプロトコル、HTTP、例外、並行処理など、言語間の差異を継続的に整理します。
   • 差異ごとに、ソースの動作、移行先の動作、利用できる場合は標準の動作、採用する互換性の方針、テスト、削除手順を記録します。

5. ドメインコードを移植する

   • まず末端の純粋モジュールを移植し、次に共有ヘルパー、I/O アダプター、最後にオーケストレーション／エンドポイントのコードを移植します。
   • ドメインコードは移行先の言語で読みやすく保ちつつ、レガシーな癖は互換性ヘルパー経由で処理します。
   • その場しのぎの文字列操作より、構造化パーサー、公式プロトコルライブラリ、生成コードを優先します。
   • 同等性が証明されてからリファクタリングします。そうでない場合は、ソースの動作と変更の対応関係を追える状態に保ちます。

6. 実環境で検証して切り替える

   • rollout-and-cutover.mdを読みます。
   • 同等性検証のすべてのゲート、ソースフィクスチャの再生成チェック、生成テストの差分チェック、競合／静的チェック、ベンチマークを実行します。
   • リプレイまたはシャドートラフィックを使って、実際のリクエスト／レスポンス、ログ、メトリクス、ヘッダー、バイナリペイロード、副作用を比較します。
   • ロールバックのしきい値を明示したうえで段階的にカナリアリリースし、少なくとも一度のロールバック期間が過ぎるまで、古いランタイムを利用可能な状態に保ちます。

リリースゲート

該当するすべてのゲートを通過するまで、移行の準備が整ったと判断しないでください。

• ソースオラクルの再生成で、予期しないフィクスチャの差分が発生しないこと。
• 生成されたパリティテストのスタブが、ソーステスト／コントラクトと同期していること。
• 保留中／スキップされたパリティテストがゼロで、失敗もゼロであること。
• 意図的なランタイムの差異すべてについて、互換性に関するナレッジに項目があること。
• ビルド、リント／静的解析、競合／並行性チェック、セキュリティチェックに合格すること。
• ベンチマークで、許容できないレイテンシー、スループット、アロケーション、リソースのリグレッションがないこと。
• シャドー／リプレイ／カナリア比較が、合意済みの差分しきい値を満たすこと。
• ロールバック手順がテスト済みであり、ロールバック期間中に旧ランタイムをデプロイ可能な状態に保つこと。

レポート用テンプレート

PR 本文、設計メモ、移行状況レポートでは、次の形式を使用してください。

## Scope
- Source boundary:
- Target boundary:
- Contract level: byte-exact / structural / semantic

## Oracle
- Source runtime/dependency versions:
- Fixture generation command:
- Standard/spec references:
- Boundary classes covered:

## Test Migration
- Source tests/contracts discovered:
- Generated stubs:
- Pending parity tests:
- Drift checks:

## Compatibility Knowledge
- New runtime differences:
- Compatibility helpers added:
- Deletion plan:

## Verification
- Unit/parity:
- Race/static/build:
- Benchmarks:
- Shadow/replay:
- Canary:
- Rollback: