※本記事は英語から日本語へ Claude を使って翻訳しています。
クライアント向けに、Vue と Vuetify を使ったアプリの移行を担当しました。
- Vue 2 → Vue 3
- Vuetify 2 → Vuetify 4
このプロジェクトで難しかったのは、クライアントのコードベースに手を入れる際に「意図を持って」変更することです。
Claude Code を使うと、なぜそのパッケージが上がったのか分からないまま、複数のパッケージを一気に上げてしまいがちです。たとえ一つひとつ説明を求めても、結局は「まとめて上がった変更の束」が出来上がるだけで、その背景にあるストーリーがはっきり残りません。
最終的に目指したのは、移行全体を通してコードベースのエントロピー（複雑さ・乱雑さ）の増加をできるだけ抑えることでした。
これに取り組むため、私は一つの基本ルールに従いました。それは エビデンスに基づいた、オーガニックな移行 を行うことです。
移行のワークフロー
一例を挙げます。
たとえば Vue のバージョンを 2 から 3 に上げたいとします。
これを Claude Code にそのまま任せると、周辺の peer dependency もまとめて推測で上げてしまい、多くのノイズ、ひいてはエントロピーを生み出しかねません。
そこで、物事を整理された理解しやすい状態に保つために、まずは対象のパッケージだけを上げます。
Vue 2 → 3
次に、例えば、vue-papa-parse 2 が Vue 3 と互換性がなくビルドが落ちたら、それを上げます。
vue-papa-parse 2 → 3
これをエラーがなくなるまで繰り返します。
もちろん、必須ではないパッケージの更新についても、鮮度の維持やツール周り（Node、vue-tsc など）の観点から検討します。
こうしたオーガニックなバージョン更新は、大きな変更の束の背景にあるストーリーを浮かび上がらせ、レビューを楽にしてくれます。
逆に、大きな束のまま push してしまうと、せっかく積み上げたストーリーがすべてぼやけてしまいます。
コミットのワークフロー
積み上げた労力を無駄にしないために、私は個人的なルールを決めました。それは コミットメッセージを一つずつ手で書く ことです。
そうすることで、クライアントのリポジトリに何を送ろうとしているのかをきちんと理解する時間を投資できます（コミット前の最後のレビューにもなります）。
これはプロジェクトにとってのメリットだけでなく、自分自身の知識や成長にとってもプラスになります。
もちろん、このワークフロー全体は時間がかかります。しかしその代わりに、ある程度のスピードを保ちつつ、コントロールと理解を手に入れられます。
特にクライアントのコードベースを扱うときは、自分の作業を説明し報告できることが重要だと考えています。
とはいえ失われるスピードを埋め合わせるため、ツールと自動化で武装しました。
イメージとして（実測値ではありません）：
QA の自動化
私のケースでは、自動テストがありませんでした。
つまり QA に時間がかかるということです。
そこで、2 つのことをしました。
- 移行を分割し、可能な限り特定のチェックポイントで QA を行うことで、QA パスの回数を抑える
- 各ルートが表示され、ブラウザのコンソールにエラーが出ないことを一括で確認するルート監査スクリプトに頼り、途中の QA を軽くする
これにより、次の計画を立てられました。
- ビルド基盤: Vue 2.6 → 2.7 + Vue CLI 4 → 5（これで Vue 2 → 3 が可能に）
- （軽い）QA パス（自動化に頼る）
- フレームワーク: webpack + CLI 5 の上で Vue 2.7 → 3.5 + Vuetify 2 → 4 など
- （重い）QA パス + UI のズレを修正
この計画は、もちろん実際にバージョンを上げる前に立てておきました。
まとめ
最終的に、私は次の原則に従っていました。
- バージョン更新はバージョンの「目標」から駆動する
- 必須となる peer dependency の更新は、表面化したエラーから対応する（エラー → 修正）
- 必須ではない更新（鮮度、ツール周りなど）も検討する
予防的な更新はエビデンスではありません。
一方で、2 つのボトルネックもありました。
- コミットのワークフロー
- QA パス
コミットのワークフローは、自分自身の成長のためにも受け入れている個人的なルールです。
時間のかかる QA パスについては、しっかり練った計画で回数を抑えるようにしました。
- まずビルド基盤を上げる
- 次にフレームワークを上げる
- 自動化に頼る