migration-refactor

維持する対象は、利用者の目的・動作・データ契約であり、旧実装の構造そのものではない。移植元を調べて移植先を先に設計し、一連の利用動作を実装・検収する。移植途中からの立て直しでも、現在の実装だけを正本にしない。

工程は、既知の見逃しの分類（該当時）、範囲の確定、動作と構造の調査、設計とアドバイザーレビュー、実装、新旧比較と構造検収、再監査と最終レビューの順に進める。

適用と守る境界

• 範囲を限定しても、その範囲内の機能・操作・UI・データ・保存・復旧を省略・簡略化してよいわけではない。概念や代表操作が似ているだけでは移植済みにしない。
• 合意した変更と維持する動作を分ける。既知の不具合修正には再現条件と期待結果を示し、未合意の仕様変更を内部整理や不具合修正として通さない。旧仕様の改善案も、合意の要否を区別して扱う。
• 移植元は比較基準として保護し、明示された変更範囲以外は書き換えない。開始時の既存差分と他担当の変更も保護する。
• 調査・計画だけの依頼は設計レビューまでで終了する。実装依頼では、許可済みの修正・検証を続け、設計記録を毎回の承認依頼にしない。
• 主担当は設計・実装・採否・検証を担う。別のアドバイザーによるread-onlyレビューを設計時と完了判定前に行う。これは実装委譲や外部送信の許可ではない。

確認項目はcoverage-guide.md、独立レビューの実施方法と利用不能時の扱いはadvisor-review.mdを正本とする。確認ガイドは工程0〜2の該当箇所から読み、レビュー手順は最初の依頼前に読む。複数単位・再開時の記録は末尾に従い、短い作業にも別の記録一式を作らない。

0. 既知の見逃しがある場合は先に分類する

移植漏れの是正、途中からの立て直し、過去の失敗を踏まえた改善では、今回の移植に関する会話の訂正・監査記録・不具合・完了撤回を確認する。最新の症状だけでなく、初期の欠落、修正後の回帰、設計・検証・完了判断の誤りまで拾う。

既知事例の分類で、事例、種類、原因、検証の穴、予防する工程、検出条件・証拠を対応付ける。発生した問題、原因分析、未確認の懸念、合意した変更を分ける。

既知の全事例へ戻り、具体的な予防・検出が対応していることを確かめる。「GUI確認」「コード確認」という見出しだけでは対応済みにしない。結果は既存の作業記録にまとめ、調査・設計・検収へ渡す。

過去事例がない新規移植では架空の失敗一覧を作らず、次節へ進む。事例がある場合も、それだけでは未知の漏れを調べられないため、移植元からの調査を別に行う。

1. 範囲と比較基準を確定する

原依頼、訂正・合意、仕様・計画、移植元と移植先、作業中の差分を読む。過去の完了報告は検証対象であり、完了の根拠にはしない。

利用目的、入口、関係する共通処理、範囲外、意図した削除・変更と根拠を定める。後続機能に依存する入口や保存項目は、今回維持する接続契約まで追い、隣接機能を丸ごと移植しない。

移植元の版・コード・テスト・確認用データを比較基準にする。実行環境、認証、ライブラリ、保存基盤の差は記録し、機能差や意図した変更と混同しない。実装・資料・実動作が食い違えば、合意した目的と再現結果から扱いを決める。

2. 利用動作と構造を一緒に調べる

確認ガイドのうち、対象に存在する観点を一巡する。代表画面・主要関数だけでなく、入口から呼出先、利用側、状態遷移、データ形式、永続化、通知、外部作用まで辿り、旧テストと実動作も照合する。

検索結果やファイル一覧で調査を終えない。各動作を成立させる定義・適用条件・利用側を読み、分岐、既定値、共有設定まで新旧の対応を付ける。GUIではcomponentに加え、DOM、CSSの読込・継承・上書き、media query、ライブラリ既定style、状態による属性を追う。各要件の実経路と未追跡部分を示し、コードで分かる欠落を後の実操作で見つける前提にしない。

移植元から、次の対応を要件ごとに作る。

条件・操作・期待結果 → 移植元 → 移植先 → 差分の扱い → 検証方法・結果

メニュー、キー操作、暗黙の既定値、共有処理、エラー時の動作にも対応先を持たせる。欠落とともに、移植先が追加した操作負担・禁止状態・制約を調べる。存在しない観点は理由付きで非適用にできるが、未調査を非適用にしない。

複数段階の操作は、途中状態の確認に従って工程間のつながりも要件に対応付ける。確認画面、入力確定、queue、await、通知、再試行の前後では、開始時の対象・条件が変わり得る。段階ごとの成功だけで一連の動作を確認済みにしない。

構造では、責務の混在、ルールの重複、状態の二重所有、暫定分岐、依存方向、実行環境との結合、検証しにくい箇所を、実経路・問題・影響と結び付ける。サイズや命名だけで分割を決めない。

複数の旧アプリ・入口に似た機能があれば、移す前に利用目的、入出力、データの意味、状態と更新規則、保存・失敗・復旧を比較する。同じ意味のデータと処理は共通の保存形式・実装へそろえ、必要な業務差だけをcodecや操作判定に残す。共通化しない箇所には利用動作上の理由を示す。旧ディレクトリ単位の新パッケージ化や、重複実装を共通interfaceで包むだけでは共通化済みにしない。

3. 対象全体を再設計し、レビューを受ける

最初の製品コードを変える前に、対象範囲と依存する境界を一つのシステムとして見直す。既に移植済みの部分も含める。調査用の再現と旧動作を固定するテストは先行できるが、関数抽出・ファイル分割だけで設計工程を済ませない。

入口から出力・保存・復旧までの現状を、責務・依存・データ・状態遷移・副作用で示す。構造の問いを一巡し、個別不具合だけでなく、迂回、過剰な層、密結合、不要な状態、重複変換、複雑な順序制御を評価する。

利用目的と維持契約から、責務・経路を残す、統合する、分解する、削除する、置き換える判断を行う。旧ファイル・クラス・パッケージを前提にせず、局所修正で足りる案と、処理経路・データモデル・状態管理を組み替える案を必要に応じて比べる。変更量だけを理由に問題を残さず、件数のために健全な実装を書き直さない。

設計に含めるもの	確定する内容
改善目標	どの構造が利用動作・変更・失敗処理を難しくしているか。不要になる仕組み、責任、検証方法
移植先の構成	データモデル、業務ルール、UI、状態遷移、永続化・通知、外部実行の責務と依存方向。失敗・競合・中断も説明できる構成
状態と副作用	正本・派生値、編集中・送信待ち・確定済み状態の所有者、識別、寿命、受渡し・退役条件。同期・再試行・復旧に必要な順序と除ける調停
複数段階の操作	開始時に固定する対象・意図、実行直前に再評価する可否、前提が失効した後続処理の中止・保持・再開条件
変更の採否	各責務・経路の変更理由、再利用する実装、互換処理と撤去条件。問題なしの判断にも実経路の根拠
移行と実装順	維持契約、意図した変更、データ移行・復旧、依存順、段階切替、最終構成の検収条件

過剰な旧仕様・保存方式・処理経路の簡素化も候補にする。仕様が変わる案は、変更前後、効果、失う動作、既存データへの影響、検証方法を示し、既存の合意で採用できるか判断する。未決の製品判断だけを利用者へ返し、依存しない調査・作業は続ける。

全体構成、各要件の実装先、構造問題の採否、最終構成への到達条件、未決事項の影響範囲がそろったら、別のアドバイザーへ移植元・要件対応・設計を渡す。根拠のある漏れ・矛盾を直し、影響箇所の再レビューを受けてから実装へ進む。局所改善案の一覧だけでは通過しない。

調査・設計だけの依頼はここで終え、実装・最終実装レビューへ進まない。対象外の全面改修や用途のない汎用基盤は加えない一方、対象内で必要な組み替えを「移植だから」「大きな変更だから」と先送りしない。

4. 一連の利用動作を検収できる単位で実装する

全体設計から依存順に単位を切り出し、入口・UIからルール、保存、再表示・復旧まで進める。コピー順や画面だけ・保存だけの完成を、機能全体の完成にしない。段階実装の途中は未完了とする。

健全な旧処理を設計した責務へ再利用する。同じ操作の検証・更新規則をGUI・CLI・MCPごとに増やさず、業務ルール、表示・操作状態、永続化・通知、外部実行を分ける。共通の業務ルールをブラウザー・Worker・Node等へ依存させず、アプリ間の内部実装への直接依存や、異なる責務を一つの共通utilityへ集める構造を避ける。

対象単位の重複と役目を終えた暫定処理を除く。互換adapter・暫定分岐、保存経路・状態所有者の二重化が必要なら、理由、範囲、切替条件、互換性、撤去条件を決めて導入する。無関係な一括依存更新や、旧二系統を残すためだけの汎用基盤は追加しない。

不具合は再現条件・期待結果を定め、所有者・順序・契約の原因から直す。非同期処理の開始だけで一時状態を捨てず、古い応答で後続操作を上書きしない。遅延・フラグ・表示固定で症状だけを隠さず、同じ状態を使うコピー・履歴・別画面への影響も追う。

新しい根拠で範囲・契約・所有者の前提が変わったら、要件対応と設計を更新してから依存する実装を進める。設計を変えずに例外分岐だけを増やさない。

5. 動作と構造を別々に検収する

動作の検収

旧コード・データ契約・旧テストの振る舞い・実操作を組み合わせ、維持要件と意図した変更を確認する。新実装から作った期待値やテスト成功だけを同等性の根拠にしない。利用動作・失敗条件を観測できる既存テストを再利用し、不足する保証だけを追加する。

GUIは同じデータ・選択・権限・画面サイズ・操作段階で新旧ブラウザーを比較する。構成・配置・表示・操作に加え、開始、継続、終了、保存待ち、確定・失敗までの表示と操作可能性を連続して確認する。保存後の静止画だけで途中品質を判定せず、実在する遷移に応じて遅延・失敗・競合、後続操作・画面切替を重ねる。

複数段階の操作は、境界前後の対象・可否・所有者を変え、一連の結果と副作用を調べる。正常完走だけでなく、途中条件の失効、中断後の再操作、結果不明からの復旧も、実在する遷移に応じて確認する。

非同期GUIを変えた場合は、応答を保留・失敗させて途中状態を観測する回帰テストと、実ブラウザーの連続操作を両方行う。既存テストが同じ条件・観測を保証するなら再利用し、形式だけの追加はしない。

巻き戻り・ちらつきは、連続操作に加え、中間フレーム・動画・座標・描画状態の計測など、現象を観測できる手段で確認する。最終値の一致では代用しない。既存のブラウザー機能とテスト環境を優先し、能力不足が明確な場合だけ追加ツール・依存を検討する。追加時は既存手段との役割と理由を説明する。

構造の検収

統合後の対象全体を現状図・移植先の設計と比べ、入口から出力・保存・復旧まで追い直す。責務と依存、データモデル、状態遷移、失敗処理が設計どおりに機能し、不要な経路・状態・変換・調停が除かれたことを確認する。

局所修正が通っても、全体に迂回・二重管理が残れば完了しない。「coreへ分離した」「ファイルを分けた」という説明だけでは通さない。性能に影響する変更や改善主張は、同条件の操作・データで必要な指標を比較する。

対象に必要なテスト、型・lint・build、プロジェクト必須の確認を行う。ブラウザーへ届かないテストをGUI検証、イベント模擬を実機確認と呼ばない。取得できない証拠は、代替確認と残る未確認を分ける。

6. 要件から再監査し、完了を判定する

各単位の修正後は影響経路を確認し、統合後は対象範囲の要件と移植元へ戻る。新コードや直した指摘だけでなく、次を照合する。

• 各要件に実装と検証の対応先があり、新旧差分を維持・合意した変更・既知不具合修正として説明できるか。
• 調査で見つけた構造問題を整理し、採用した設計が実経路で機能しているか。
• 修正が新しい動作差、重複状態、迂回、検証漏れを生んでいないか。

見逃しがあれば調査不足の原因を特定し、同じ原因が届く入口・状態・利用側へ検査を広げる。要件と必要な回帰検証を補い、範囲内の未実装を後から対象外や意図した改善へ読み替えない。新しい変更・根拠がない合格項目は引き継ぎ、無関係な全面監査を反復しない。

発見手段と事前に検出できた根拠を分ける。実画面で見つけても、原因となる定義・条件が旧コードにあれば、欠けた追跡・新旧対応を記録する。ブラウザーでの発見を、コードでは分からなかった証拠にしない。

主担当の再監査後、別のアドバイザーへ要件対応、実装・検証根拠、設計との差分、残件を渡す。根拠と影響を確認して指摘を是正し、変更が届く経路を検証・再レビューする。採否と理由を記録し、自己確認で独立レビューを代替しない。

完了には、対象動作の維持または根拠ある変更、必要な構造改善の検収、必要な検証、独立レビューの必須指摘の解消確認がすべて必要である。必須の未解決・未確認があれば移植完了にせず、残件と依存を示す。許可済みで実行可能な是正は続ける。

記録と既存スキルとの関係

複数単位や再開を伴う場合は既存の計画・要件対応表を更新し、必要なら記録の最小構成を使う。公開範囲、保存先、再開・共有方法はプロジェクトに従う。非公開資料を公開予定のGit履歴へ一時的にも持ち込まず、会話全文、日付違いの複製、別台帳を増やさない。

本スキルは新旧対応と移植の統合判断を担う。構造の深い監査が必要な場合だけarchitecture-refactor-loop、フロントエンド構造にはfront-end-refactor-loopを対象範囲で利用できる。挙動維持の監査と製品仕様の採否を混同せず、手順・台帳・レビューを機械的に重ねない。

最終報告は対象範囲、維持した動作と意図した差分、整理した構造、検証と限界、未解決事項を示す。実装済み・検証済み・未確認を分け、テスト件数だけで全完了としない。