データは残しても、App 全体は残さない：リファクタリング前に棚卸しすること

「元のサイトの内容を残して、アーキテクチャを変える」という依頼で最初に必要なのは、新しいフレームワークのコンポーネントではありません。双方が残す範囲を確認できる一覧です。

このサイトは Vue からネイティブの Astro へ移行しました。作品データ、画像、3言語の文案は引き継ぐ必要がありましたが、古い App 全体を残す要件はありませんでした。ファイル名を頼りに1つずつ書き直すと、使われていなかった操作まで新しいサイトへ持ち込むおそれがあります。コンポーネントの形を守る一方で、読者が開けていた URL を取りこぼすこともあります。

棚卸しは、読者に見えるコンテンツと動作から始め、その実装へたどるべきです。以下の一覧は、コンテンツサイトのリファクタリングを準備するためのものです。あらゆるアプリケーションに対応する完全な移行仕様ではありません。

以下で「現在」の状態として説明する内容は、2026年10月5日付の原稿に記録された実装と要件を指します。

まずコンテンツを列挙し、その出所を調べます

最初の一覧で答えるのは、「何を失ってはいけないか」だけです。新しいアーキテクチャでどの種類のコンポーネントにするかを、先に指定しないようにします。

このサイトの素材には、作品名、紹介文、外部リンク、画像、職務経歴、多言語の文案がありました。棚卸しでは、ファイルが残っているかだけでなく、実際のページがデータをどう使っているかも確認します。除外される項目、並び順の条件、言語別の内容、空の値の扱いも対象です。

原稿に記録された作品ページでは、並べ替えたプロジェクトデータを読み込んだあと、一部の項目を除外していました。そのため、「すべてのデータを表示する」ことは、元の展示範囲を残すことと同じではありません。データが存在することと、公開展示に適していることは別です。

項目ごとに、次を確認できます。

• データソースは揃っていますか。各フィールドの意味は、今も読み取れますか。
• 実際に表示される項目はどれで、データの中に残っているだけの項目はどれですか。
• 並べ替えや除外の条件には、既定の用途がありますか。
• 画像に対応するコンテンツはありますか。外部リンクは引き続き残すべき入口ですか。
• 多言語の内容は実際の言語別バージョンですか。それともフィールドだけがあり、本文はありませんか。

この段階では、現状を記録します。不足があれば明示し、一覧を整えるためだけに作品紹介や翻訳を作り足してはいけません。

機能一覧には入口の証拠が必要です

操作を列挙するときは、読者がそれをどう見つけるかも併記します。

たとえば作品カテゴリの切り替えなら、ページ上の入口と、切り替え後に表示される内容を示せます。アバター画像の拡大表示では、開く方法、閉じる動作、フォーカスの移動先を確認します。背景アニメーションにはボタンがありませんが、これも見える動作です。動く状態と静止した状態を別々に記録する必要があります。

このサイトのリファクタリングでは、古いツール用コンポーネントにあった技術別フィルターを新しいページに追加したことがありました。その後、古いページがそのコンポーネントを参照していないと確認し、余分な操作を削除しました。この事例から、棚卸しのルールを決められます。コンポーネントのファイルは手がかりにはなりますが、そのまま機能を残す要件にはできません。

入口が見つからなければ、まず参照とマウントの関係を調べ、その項目を「利用未確認」とします。知らないうちに新しい要件へ格上げしてはいけません。過去に別のデプロイ版があったかどうかも、資料がなければ、なかったとは結論づけられません。

URL も残す範囲に含まれます

画面が似ていても、以前の深い階層の URL を直接開けなくなれば、読者にとっては変更です。

URL を棚卸しするときは、正式な入口、言語別の入口、互換用の入口を少なくとも分けて記録します。原稿に記録された時点では、繁体字中国語のルート例である /about/work が作品ページの canonical URL で、旧 /work も読める互換用の入口として残っていました。英語と日本語にも対応するルートがありました。互換用の入口は独立した別コンテンツではありません。両者の公開上の位置づけを混同しないようにします。

次の項目で URL 一覧を作成できます。

項目	記録すること
読者の入口	既存の URL と、そこに表示すべき内容
新版での位置づけ	正式なページを継続するか、互換用の入口にするか
言語	その URL に対応する文案と HTML の lang
ページ情報	タイトル、説明、canonical URL の根拠
失効時の処理	未知の URL や、すでに存在しない内容をどう扱うか

これは棚卸しの書式であり、すべてのサイトで言語や互換ページを増やす必要があるという意味ではありません。引き継ぐべきなのは確認済みの入口です。表を埋めるために URL を増やすのではありません。

実装の責任は別の列に書きます

コンテンツと動作を確認してから、それを何に担当させるかを決めます。

同じ要件にも、複数の実装方法があります。ページの言語はアプリケーションの状態で管理することも、URL で決めることもできます。共通の外枠はフレームワークのコンポーネントで組み合わせることも、ビルド時に各ページの HTML へ組み込むこともできます。まず要件を残し、そのあとで実装を評価すれば、古い技術に新しいアーキテクチャの判断を任せずに済みます。

このサイトで採用した分担を例にします。

残す要件	記録された実装での責任分担
各 URL に、それぞれ読める内容があること	ネイティブの Astro ページと静的出力
ナビゲーションと言語切り替え	実際のリンクと URL が決める言語
各ページのタイトル、説明、言語情報	共通 layout とページの metadata
作品データと画像	既存のデータソースをページが読み取る構成
背景アニメーションと局所的な操作	スコープを明確にしたブラウザーのスクリプトとネイティブ HTML

この表は、このサイトでの選択を説明するものです。移行成功を示す証拠のすべてではありません。古い責任のうち、もう残す必要がないものと、新しい実装に引き継ぐ必要がある要件を見つけるために使います。

インタラクションでは失敗と復帰の状態も棚卸しします

再生中のアニメーションが同じように見えても、インタラクション全体を残せたとは限りません。

このサイトの開発規約では、背景の流線を通常の動作モードでアニメーション更新ごとに描画し、タブが非表示のときは停止することを求めていました。reduced-motion では静止表示にし、ウィンドウサイズの変更時は再描画し、ページを離れるときはクリーンアップします。さらに、ブラウザーのキャッシュから復帰した場合の初期化も扱います。これらの状態は動作一覧に記録する必要があります。「Canvas を残す」の一言では足りません。

ほかの操作にも固有の状態があります。ダイアログでは Escape、背景のクリック、フォーカスの復元を列挙します。画像ではサイズ、代替テキスト、失敗時の状態を記録します。ナビゲーションと本文は、JavaScript が動作しなくても読めるかを確認します。

一覧では、まず期待する動作を記述し、検証結果は別に記録します。ある状態を満たすよう要求したことは、その状態をテスト済みであることを意味しません。

各項目には完了チェックだけでなく、残すかどうかの判断が必要です

棚卸しの最後では、項目を「コンテンツを残す」「実装を作り直す」「別途確認が必要」「今回は追加しない」に整理できます。「確認が必要」を「完了」の列に入れてはいけません。また、未使用のコンポーネントを、そのまま削除可能なコンテンツに分類してはいけません。

技術別フィルターであれば、できる判断は「元のサイトが提供していた操作とは確認できないため、今回は追加しない」です。「過去のすべてのバージョンにこの機能がなかった」ではありません。作品データであれば、データを残し、確認済みの展示範囲を引き継ぎます。全件を自動的に公開することではありません。

書き直す前に、代表となるページを1つ選び、コンテンツ、URL、1つのインタラクションを新しい実装方法で一通り通しておくとよいです。その増分が残す項目の一覧を満たすことを確認してから、ほかのページへ広げます。棚卸し後に新しい要件が出た場合は、追加範囲として別に記録します。リファクタリングとリニューアルが混ざり、受け入れ確認ができなくなるのを防ぐためです。

記録の範囲

この記事は、このサイトのリファクタリングと、当時の作品展示、ルーティング、インタラクションの規約に基づく棚卸し方法を整理したものです。一覧と表は調整可能な作業用の書式であり、完全な移行ツールではありません。ログイン、データベース移行、取引システムも対象外です。残す項目の一覧を実測の代わりにするものではなく、変更前後の速度、検索の成果、過去のすべてのバージョンの機能が確認済みだと主張するものでもありません。