はじめに
こんにちは、WEARバックエンドブロックでバックエンドエンジニアをしている
@sakam0cchan です。
突然ですが皆さん、バージョンアップってとても大変ではないですか？
- 互換性チェック
- 破壊的変更の洗い出し
でも一方で、
- LTS が切れる
- セキュリティアップデートも来ない
- ライブラリの依存関係もどんどん古くなる
という現実もあって、定期的なバージョンアップは避けて通れないですよね。
私の部署では Bootstrap を「運用ツール（社内向けツール）」で使っているのですが、
ユーザへの直接的な影響が少ない、かつ、膨大な修正作業が必要なこともあって、つい後回しになりがちでした。
そして気づけば、大きな不具合もなく動いていたことから、 Bootstrap 4 をそのまま使い続けている状態でした。
定期的な Dependabot の通知で、「そろそろやらないとな...」となったので、
「このめんどくさい作業、AI に投げてしまおう」
という発想で、Claude Code（コード特化AI）にほぼ丸投げで Bootstrap 4 → 5 の移行をやってみました。
この記事では、そのとき実際にやった流れ・工夫・ハマりどころを書いていきます。
全体の進め方
- バージョンアップの元になる情報を決める
- 情報を元に必要な情報を読ませて、タスクをドキュメント化させる
- タスクごとにコード修正を AI に任せる
- 人がレビューしやすい単位に PR を分割して出す
それぞれもう少し詳しく書きます。
1. まずは「バージョンアップの材料」を決める
最初にやったのは、バージョンアップの道標となるドキュメント探しです。
私は以下のドキュメントをもとに、バージョンアップを行いました。
2. サイトを元にタスク化を行う
早速、ClaudeCode に投げてタスク化してもらいます。
見つけたページをそのまま人力で読むのはつらいので、 Claude Code に URL を投げて、現在のタスクフォーマットを元にドキュメント化してもらいました。
プロンプトイメージは、こんな感じです。
Bootstrap 4 → 5 のバージョンアップをしたいです。
以下のドキュメントを読み込んで、
- 破壊的変更
- クラス名の変更
- jQuery 依存からの移行
を中心に、本プロジェクトで変更や修正が必要なものをチェックボックスで整理してください。
フォーマットは、task-template.md を元に作成してください。
チェックボックスは、各見出しごとに対応させ、破壊的変更に関してはmustで対応タスクを作成してください。
バージョンアップに必要な情報があれば、適宜質問し、不明点がない状態までブラッシュアップしてください。
（ここに URL を貼る）
すると、このようなアウトプットになりました。
## 仕様
### アップグレード方針
- Bootstrap 4.6.2 → Bootstrap 5.0.x
- jQueryは削除せず維持（既存の独自実装で使用中）
- Bootstrap 5のJavaScriptはVanilla JS版を使用
- 既存のjQuery実装とBootstrap 5のVanilla JS実装を共存させる
### 影響範囲
- **主要影響箇所**:
- ⚪︎⚪︎⚪︎⚪︎
- **jQuery使用箇所**（維持）:
- rails-ujs
- ⚪︎個のカスタムJSファイル
## 調査ログ
### 現状調査結果
- ⚪︎⚪︎⚪︎
### 重要な破壊的変更まとめ
- **フォーム**: `.form-group`、`.form-row`、`.form-inline`の削除
- **バッジ**: `.badge-*`色クラスの削除、`.badge-pill`の削除
- **ユーティリティ**: RTL対応でクラス名変更（ml/mr→ms/me等）
- **テーブル**: `.thead-light`/`.thead-dark`の削除
- **コンポーネント**: `.media`、`.jumbotron`、`.card-deck`の削除
- **JavaScript**: data属性のネームスペース化（data-* → data-bs-*）
## 修正・実装対象ファイル一覧
### 設定ファイル
1. **package.json** - Bootstrapバージョン更新、@popperjs/core追加
2. **webpack.config.js** - Bootstrap JSインポート設定更新
### JavaScriptファイル（Bootstrap依存部分のみ更新）
1. **app/assets/javascripts/application.js** - Bootstrap初期化
2. **webpack.config.js** - エントリポイント設定
### テンプレートファイル
- データ属性の一括置換が必要な全HTMLテンプレート
## 実装手順
### 実装ステップ
#### 1. 依存関係の更新
##### パッケージのアップグレード
- [] package.jsonでbootstrapを5.0.xへ更新
- [] @popperjs/coreをv2.xで追加
- [] jQueryは維持（既存機能で必要）
- [] npm installを実行
##### Webpack設定の更新
- [] webpack.config.jsでBootstrap JSのインポート方法を更新
- [] Popper.jsの設定を@popperjs/coreに変更
- [] jQueryとBootstrap 5の共存設定を追加
#### 2. HTML/テンプレートの更新
##### データ属性の名前空間変更
**参考資料**: https://getbootstrap.com/docs/5.0/migration/#javascript
- [] `data-toggle` → `data-bs-toggle`
- [] `data-target` → `data-bs-target`
- [] `data-dismiss` → `data-bs-dismiss`
- [] `data-placement` → `data-bs-placement`
- [] その他のdata属性を`data-bs-*`に更新
※ 実際にはもっと行が並びますが、雰囲気だけ。
ここまでやると、作業がブラックボックス化せずに
- 人間目線でも「何をやるのか」が見える
- 後から振り返るときのドキュメントにもなる
という状態になります。
3. 一つ一つ、AI に修正してもらう
いよいよ実作業です。
今回、かなり作業箇所が多く、一度に修正すると差分が見えにくい形だったため、
1項目あたりに一度作業方針を確認してもらい、yes が出たら修正する形で進めていきました。
また、作業ごとにはログを作成してもらい、いつどのファイルをどうやって修正したか後からでも追えるようにしていました。
## 実装ログ
### 調査フェーズ
- 2025-10-10: 現状調査完了、jQuery使用箇所の確認
### 実装フェーズ
- 2025-10-10: 依存関係更新、package.jsonでBootstrap 5.0.0へ更新
- 2025-10-10: Webpack設定更新、@popperjs/core対応
- 2025-10-10: データ属性の名前空間変更（data-* → data-bs-*）
- 修正ファイル一覧：
- ⚪︎⚪︎⚪︎
- 2025-10-10: Bootstrap 5.0.0でBackdropエラー発生、5.0.1へアップグレードして解決
- 2025-10-10: グリッドシステムの更新確認
- `.no-gutters`、`.gutter-*`、`.order-*`クラスは使用されていないため、修正不要と確認
4. 修正がある程度溜まってきた段階でPRを作成
最終的にはレビューをしていただく必要があるため、なるべくチェックボックスごとにコミットを作成し、差分が確認しやすいよう意識して、PRを切り分けました。
やってみてよかったこと・はまりどころ
よかったところ・工夫点
- バージョンアップで読むべき ChangeLog の負担がかなり減った
- いつもは全変更を追うのがつらいのですが、AI に関係ありそうな部分だけ抜き出してもらえたのが楽でした
- タスク一覧があることで、見落としへの不安が減った
- 破壊的変更が多くて不安だったが、人と AI のダブルチェックで進められたので安心感があった
- プロジェクト独自の条件にも対応しやすかった
- Bootstrap 5 では jQuery 依存の削減がポイントですが、本プロジェクトでは Bootstrap 以外でも独自に jQuery を使っています
- 「ここは残す」「ここは置き換える」といった方針を事前に AI に伝えながら進めることで、共存させつつバージョンアップできました
- 単純作業と大量修正だったので、AI との相性がよかった
- 約 130 ファイル（2000 行弱）の差分が出ましたが、パターン化できる修正を AI に任せることで、作業時間をかなり短縮できました
はまりどころ
- 特定バージョン固有のバグには気付きづらい
- 一度 v5.0.0 に上げた際、そのバージョン特有のバグに当たりましたが、修正が v5.0.1 で入っていることに AI は気付けませんでした
- 「どのバージョンで直っているか」「既知のバグかどうか」といった情報は、自分でリリースノートや Issue を追う必要がありました
- プロジェクト固有の CSS / コンポーネントは伝えないと考慮されない
- 最初の段階では独自クラスが考慮されておらず、意図せず新たな Bootstrap のクラスに置き換えられそうになりました
- 「このクラスは触らない」「このコンポーネントは特殊」といったルールを、最初に明示しておくのが大事ですが、この把握が難しいです...
- 画面の見た目チェックは結局人間の仕事
- レイアウト崩れや微妙な余白の違いは、AI からは検知できません
- 自動化できる部分とそうでない部分の線引きは、あらかじめチーム内で握っておくとスムーズだと感じました
まとめ：めんどくさいバージョンアップこそ、AI の良い使いどころ
Bootstrap のような UI フレームワークのメジャーバージョンアップは、
- 情報を集めるのがつらい
- 作業自体は単調になりがち
- でも影響範囲は広くて怖い
という、エンジニアにとってはなかなかしんどいイベントです。
今回、Claude Code に
- ドキュメント要約
- タスクリストの作成
- ファイル単位の修正案作成・作業
までを任せてみて、かなりバージョンアップ作業への可能性を感じました。
同じように、古いライブラリから新しいライブラリへの移行などにも応用できると思うので、これからもいろいろな方法を模索していきたいと思います。