October CMS v4 移行記
先日、October CMS を使用したシステムのバージョンアップを担当することになりました。土台となる CMS が古いバージョンのままでサポートが終了しており、放っておける状態ではなかったためです。
今回はこの作業を、最初から最後まで Claude Code を使って進めてみました。実際に手を動かしてみると、原因調査や設定の突き合わせでは想像以上に助かった一方で、「指示の出し方を変えていれば防げた」不具合もいくつか出ました。
この記事では、進め方・使ってよかった点・うまくいかなかった点・実際に起きたトラブルを順にまとめます。
1. やったこと
October CMS は、管理画面などを作るための土台（CMS）です。使っていたのは古いバージョン（v1）で、不具合が見つかっても修正は提供されない状態でした。
そこで最新のバージョン（v4）へ入れ替えました。土台の下で動いている PHP も、7 系から 8.2 へ上げています。
この作業が少し特殊なのは、土台のプログラムそのものが自分たちのリポジトリの中に入っていることです。ライブラリのように「新しいものを取り寄せる」のではなく、土台のソースコードをまるごと差し替える作業になります。
- 差し替えたファイル：数千ファイル
- うち自分たちが書いたコード：数百ファイル
- 用意したテスト：約80
今回は、調査から修正、テスト、手順書づくりまで、ほぼ全工程で Claude Code を使っています。
2. 進め方
1. 新しい土台で動く環境を、先に手元に作る
「これは新バージョンの仕様なのか、うちの環境のせいなのか」を切り分けられる場所を最初に用意しました。これがあるかどうかで、後の効率が大きく変わります。
2. 入れ替える前に、今の動きを記録しておく
バージョンアップで求められるのは、新しい機能ではなく「前と同じように動くこと」です。そこで、入れ替える前の動きを記録しておくテストを先に用意し、前後で挙動が変わっていないかを確認できるようにしました。
3. 土台を入れ替えて、変わった設定を戻す
新しい土台には新しい初期設定が付いてきます。前の設定を上書きしてしまうので、1件ずつ元に戻す必要があります。
4. サーバーに載せて、実際の画面で確認する
ここで、手元では気づけなかった問題がいくつも出てきました。
3. Claude Code を使ってよかったこと
原因を「たぶん」で終わらせない
新旧の違いは、公式ドキュメントを読んでも分からないものが多くあります。いちばん助かったのは、土台のプログラムそのものを読んで、原因を根拠つきで示してくれたことです。「このファイルのこの部分がこう変わっています」まで出てくるので、直し方の妥当性を判断できます。
地道な総点検ができる
「前の設定と新しい設定を全項目突き合わせる」「表示文言の参照350件超をすべて確認する」といった作業は、人がやると必ず取りこぼします。ここは強く、実際にやりきれました。
退屈なテストを大量に用意できる
前述のテストは、価値は高いのに書くのが退屈なコードです。人力だと後回しになりがちなところを、まとめて用意できました。
昔からあったバグが見つかった
新旧の違いを調べる過程で、前のバージョンの時点で壊れていた箇所も出てきました（権限チェックの不備など）。結果としてコードの棚卸しになりました。
4. うまくいかなかったこと ── 指示の出し方の問題
先に書いておくと、ここに挙げるのは Claude Code にできなかったことではなく、こちらの指示の出し方が足りなかったことです。
「消えたもの」は、言わないと出てこない
今回いちばん大きな失敗です。新旧を見比べれば、無くなったものも自動で検出してくれると思っていましたが、そうはなりませんでした。前のバージョンで追加していたライブラリのうち、コードに名前が出てくるものは引き継がれ、間接的に使っていたものは落ちていました。設定も同じです。追加や変更は差分に出るので話題になりますが、無くなったものは、探すよう頼まないかぎり出てきません。
自動テストが「形だけ」になる
入れ替え前に用意した権限チェックのテストは、ソースに特定の書き方が残っているかを見るだけで、動きを確認していませんでした。動きが壊れても通るテストです。実際の動きを確かめるにはログイン状態や権限の違うユーザーを用意する必要があり、書ける形に置き換えられていました。件数は揃うので、一覧では気づけません。
指示をこう変えるべきだった
- 設定やライブラリの欠落：「前と後の全項目を、あるかないかで突き合わせて。値の違いではなく、有無を見て」
- 自動テストが形だけだった：「ソースの文字列ではなく呼び出した結果で判定して。確認できないものは代わりのテストで埋めず、未確認として一覧に出して」
- テストが効いているか不明：「わざと動きを壊して、テストが落ちるのを確認してから出して」
- 環境ごとの設定の見落とし：「環境によって値が違う設定を洗い出して。動かしても症状が出ないものを先に挙げて」
共通しているのは、「変わったもの」を見る指示になっていて、「無くなったもの」を見る指示になっていなかったという点です。
5. 実際に起きたトラブル
画像がすべて表示されなくなった
管理画面にアップロードした画像は、クラウド上の保管場所に置いています。その保管場所を指す設定が、入れ替えのときに消えていました。関連するライブラリも一緒に落ちていて、画面ごとエラーになるところもありました。
厄介なのは、画面には「画像が選択されていません」としか出ないことです。「ファイルが無い」「権限が無い」「設定が違う」がすべて同じ表示になるため、原因が読み取れません。
メールが送れなくなった
原因が3つ重なっていました。①設定項目の名前が変わり、古い名前は黙って無視されていた。②上記のライブラリ欠落。③配信サービスの接続先の指定方法が変わっていた。どれも自動テストでは見つからず、設定値を読み比べて気づいたものです（②は画像の調査中に判明、③は環境によって症状が出ません）。
最初の入れ替えで直らなかったのは、前の設定を1項目ずつ引き継げているか確認する手順が無かったからです。送信方法・接続先・ライブラリを役割で洗い出し、新バージョンでの行き先を確認するべきでした。
その他
このほかに出たものは、画面を開いて触ってみないと分からないものが中心でした。
画像のプレビューが極端に小さくなる、一覧のチェックボックスが選べない、画面のデザインが崩れる── いずれもエラーにはならないため、画面を1つずつ開いて確かめる中で見つかりました。
6. 次に活かすこと
「変わったもの」だけでなく「無くなったもの」も探す
比べるときは、値の違いだけではなく、項目そのものがあるかないかの確認が必要。
自動テストは「効くか」を確かめる
用意した時点で、わざと動きを壊して落ちるかを1回試す。確認できないものは弱いテストで埋めず、未確認の項目として残す。
指示の出し方を先に決める
「直して」ではなく「前と後を突き合わせて、違いを列挙して、戻すべきか判断材料を出して」と頼む。原因は根拠を示してもらう。完了条件は機能で書き出す。この3つで、拾える範囲がかなり変わりました。
7. まとめ
土台をまとめて入れ替える作業でしたが、難しかったのはプログラムの書き換えではなく、「何が静かに消えたか」を見つけることでした。
エラーで止まってくれる問題は、いずれ必ず見つかります。怖いのは、初期設定に静かに戻って「動いているように見える」ものです。
Claude Code は、この「静かな違い」を地道に洗い出す作業でよく働きました。一方で、何と何を突き合わせるべきかを決めるのは人間の仕事です。今回出た問題の多くは、ツールの限界ではなく指示の設計不足でした。
これから同じような入れ替え作業を予定されている方は、着手前に「前にあったものが全部あるか」を確認する指示を1つ加えるだけでも、後の手戻りが減ると思います。
