ln-76-architecture-migration-planner

アーキテクチャ移行プランナー

目標： 根拠のある現行アーキテクチャから明確な目標アーキテクチャへの安全な移行を、可逆性の限界と復旧アクションを含めて計画します。承認済みの移行ドキュメントのみを変更してください。移行を実行したり、プロダクトコードを編集したり、汎用的なタスク計画を作成したり、デリバリーを承認したり、不可逆な手順を隠したりしないでください。

実行契約： チェックボックスの順序は完了の定義です。すべての項目を内部で PENDING、具体的な根拠を伴う PROVEN、条件が存在しないことを示す根拠を伴う CLEARED、または未解決点がある UNPROVEN として追跡してください。読み取り、委任、ツールの失敗は根拠にはなりません。各セクションの後に項目を照合してください。回答を返す前に、すべての PENDING を解消し、PROVEN と CLEARED のみを数えてください。すべての未解決点に対して、スキルの判定基準と承認ルールを適用してください。 ユーザーの意図、範囲、既存の承認を維持してください。承認済みの作業を続行し、重大な未解決の選択肢や必要な外部承認がある場合にのみ確認してください。重大なリスクに応じて詳細度を調整しつつ、確認を黙って省略しないでください。依存関係と安全性に関する順序を維持し、それ以外は各要件に適した検証方法を選択してください。

ツールの振り分け

必要な情報	優先する機能	フォールバック
現行状態と目標状態	リポジトリの根拠と承認済みアーキテクチャ成果物	制約を明記した、ユーザー提供の明示的な状態
利用者と互換性	言語インテリジェンス、スキーマツール、設定検索、テレメトリ、直接調査	UNVERIFIED と明記した保守的な一覧
データ規模と実行時のリスク	本番メトリクス、チェックイン済みレポート、マイグレーション、ワークロードの根拠	実行前の検証ゲートを伴う範囲
外部の移行制約	ベンダー公式の移行・互換性ガイダンス	該当するフェーズを BLOCKED または UNVERIFIED と明記
ドキュメントの変更	承認済み移行計画の成果物に対する最小限のパッチ	権限またはパスが不明確な場合は BLOCKED を返す

移行フェーズごとに、システムがサポート対象の状態になるようにしてください。追加的で可逆な手順を切り替えより先に行い、破壊的なクリーンアップは利用がゼロであることを検証した後に行ってください。

成果物のルール

• 明確なアーキテクチャ移行ドキュメントがあれば再利用し、なければ docs/architecture/migration-plan.md を使用してください。
• 現行状態、目標設計、ベースライン、決定事項、図、インターフェース、テレメトリは、任意の共有根拠として扱ってください。
• 計画はアーキテクチャレベルに保ってください。フェーズ、互換性、データ、トポロジー、ゲート、ロールバック、責任者、削除を扱います。
• ファイル単位の実装タスクは後続の計画に委ねてください。
• データや外部への影響が可逆でない場合、ロールバックを「元に戻す」と表現しないでください。
• 破壊的な手順にはそれぞれ、明示的な承認、バックアップ、復元、利用者がゼロであることの根拠を要件として明記してください。

チェックリスト

1. 移行契約を確立する

• 移行の範囲、ビジネス上の成果、現行状態、目標状態、対象外事項、期限または期間、責任者、承認済みの移行先を明確にします。
• リポジトリの指示、Git の状態、関連するアーキテクチャ成果物、マイグレーション、デプロイ設定、互換性ポリシーを読みます。
• 現行状態と目標状態から差分を算出できるだけの具体性があることを検証します。どちらかの状態を作り上げるのではなく、BLOCKED を返してください。
• 保護対象のユーザージャーニー、前提条件、SLO、復旧目標、コンプライアンス上の義務、変更可能な時間帯を特定します。
• 実行中は、承認済みの移行ドキュメント以外を読み取り専用にします。

2. ギャップと依存関係のマップを作成する

• 影響を受けるモジュール、デプロイ可能な成果物、データストア、スキーマ、API、イベント、設定、インフラストラクチャ、運用手順を洗い出します。
• 内部および外部のコンシューマー、オーナー、バージョン、トラフィック、データ量、証拠の品質を洗い出します。
• 境界、オーナーシップ、コントラクト、データ、ランタイムトポロジー、可観測性、障害時の動作について、現状から目標への変更をマッピングします。
• 共有の可変リソース、順序に依存する依存関係、長時間実行される処理、バージョン混在期間、取り消せない影響を特定します。
• 未知のコンシューマーや利用状況は移行リスクとして記録します。検索結果がないことは、利用がゼロであることを意味しません。

3. 互換性とデータの安全性を設計する

• 該当する場合は、旧／新コントラクトの互換性、バージョンネゴシエーション、アダプター、デュアルリードまたはデュアルライトの動作、非推奨化ポリシーを定義します。
• バージョン混在やオンライン移行に共存が必要な場合は、拡張／移行／縮小の手法を採用し、その際は追加的なリリースと破壊的なリリースを分けます。承認済みのオフラインでのアトミックな移行では、同等の互換性、復旧、ダウンタイム対策を文書化します。
• バックフィルの対象選定、バッチ処理、スロットリング、冪等性、チェックポイント、再試行、照合、正しさを検証する基準を定義します。
• 共存期間中の信頼できる唯一の情報源、同時書き込みの競合処理、部分的なデュアルライト失敗の検出・再試行・照合を定義します。2つの書き込みがアトミックだと想定しないでください。
• データ移動に伴うバックアップ、復元、RPO／RTOへの影響、プライバシー、保持期間、監査証拠を定義します。

4. 可逆的なフェーズを構築する

• 準備、シャドーまたは共存、段階的移行、切り替え、安定化、旧経路の削除を、それぞれ独立して検証可能なフェーズとして定義します。
• 各フェーズについて、前提条件、変更後のアーキテクチャ状態、オーナー、開始ゲート、観測可能な成功条件、中止条件、ロールバックまたはロールフォワードのアクション、終了時の証拠を明記します。
• 妥当な場合は、機能フラグ、ルーティング制御、カナリアコホート、レート制限、メンテナンス期間、影響範囲の制御を定義します。
• トラフィックまたはデータの移動前に必要なメトリクス、ログ、トレース、照合レポート、ダッシュボード、アラート、SLOゲートを定義します。
• 現実的なデプロイ順序とロールバック期間を通じて、旧バージョンと新バージョンの相互運用性を維持します。

5. 切り替えと削除を計画する

• go／no-go の決定権者、連絡方法、凍結条件、切り替えを実行する具体的な制御手段、直後の検証を定義します。
• コード、設定、トラフィック、スキーマ、移行済みデータそれぞれのロールバック境界を個別に定義します。受け付け済みの書き込みが失われる場合は、後戻りできない地点と、ロールフォワードによる復旧方法も含めます。
• 破壊的な削除の前に、関連するスケジュールやオフラインのコンシューマーを網羅する期間、移行済みコンシューマー、該当する保持期間の満了、明示的な承認に基づく利用状況の証拠を必須とします。短期間のトラフィックゼロのサンプルでは、利用がゼロだと判断できません。
• 削除対象となる旧コード経路、コントラクト、フラグ、アダプター、ジョブ、データ、インフラストラクチャ、ダッシュボード、ドキュメントを列挙します。
• 切り替え後の観察期間、オーナーシップの引き継ぎ、インシデント対応、完了を示す証拠を定義します。

6. 文書を作成して報告する

• 移行の概要、状態のギャップ、依存関係、互換性、データ計画、段階的な手順、ゲート、可観測性、ロールバック、削除、オーナー、前提条件、未決事項を記載します。
• 特定のワークフローを必須にせず、安定したリポジトリパスまたはタイトルで共有アーティファクトへのリンクを記載します。
• 各フェーズを読み直し、根拠のないダウンタイムゼロ、データ損失ゼロ、コンシューマー、容量、可逆性に関する主張がないか確認します。
• フェーズが実装計画の入力として安全に実行可能な場合にのみ READY を使用します。互換性、データ、ゲート、ロールバックに重大な不足がある場合は REVISE を使用します。現状、目標状態、決定権限、安全性を示す証拠のいずれかが得られない場合は BLOCKED を使用します。

セルフチェック

• 返却前に整合性を確認します。 項目ごとの根拠、要件の網羅性、矛盾、対象範囲、判定、および該当するクリーンアップを確認します。報告または許可された成果物を修正します。有効な根拠は再利用し、リポジトリを自動的に再スキャンしたり、成功したコマンドを再実行したりしないでください。関連する変更、失敗、または未解決の根拠がある場合に限り、確認を繰り返します。残っている不足を明示します。

出力規約

ユーザーの言語で、次の順序で報告します。5つのフィールドをすべて維持し、各事実は一度だけ記載します。結果が少ない場合はフィールドごとに1行で記載してもかまいません。空の表は省略し、リンク先の成果物をコピーしないでください。

1. 結果： スキル固有の判定と、根拠によって裏付けられた結果。
2. 対象範囲： レビュー／変更した対象範囲、除外事項、ベースライン、および重要な前提。
3. 根拠： 以下のスキル固有のフィールド。事実、推論、未検証の主張を区別します。成果物にリンクし、必要に応じて表を使用します。
4. 検証： 確認項目と結果、利用できない根拠、および該当するクリーンアップ／外部状態。
5. 完了状況： Checklist: X/Y complete、Incomplete: None、または各 UNPROVEN 項目の理由、結果への影響、具体的な次のアクションを記載します。残存リスクと必要な判断事項も記載します。

スキル固有の根拠： 成果物のパス、現在と目標の差分、利用者、依存関係、保護すべき不変条件。各フェーズの開始ゲート、変更、成功を示す根拠、中止条件、ロールバック／ロールフォワードを要約します。データ、共存、整合性確認、切り替え、削除の証明、および安全性、順序、可逆性に影響する未決事項を記載します。