rails-upgrade

Rails のアップグレード

概要

このスキルは、Rails アプリケーションをアップグレードするための体系的なワークフローを提供し、バージョン 5.2 から最新リリースまでを対象とします。GitHub API 経由で railsdiff.org から設定差分をリアルタイムに取得し、Grep、Glob、Read ツールでコードベースを直接調査して、構造化されたアップグレードレポートを作成します。外部スキルへの依存は不要です。

開始時に宣言: 「このアップグレードを進めるため、rails-upgrade スキルを使用します。」

リリース状況

2026-08-13 に rails/rails を基に確認済みです。

系列	最新パッチ	ステータス
8.1.x	8.1.3.1	現行の安定版
8.0.x	8.0.5.1	メンテナンス中（バグ修正＋セキュリティ修正）
7.2.x	7.2.3.2	セキュリティ修正のみ
8.2	8.2.0.alpha (main)	開発中 — リファレンスの 8.1 → 8.2 セクションを参照

7.2 より古いバージョンは上流でサポートされておらず、セキュリティパッチも提供されません。

必ずマイナーバージョンだけでなく、正確なターゲットパッチを確認してください。
https://rubygems.org/api/v1/versions/rails.json（または gem list rails --remote --all）を確認し、ターゲット系列の最新パッチを指定します。8.1.3.1 が存在するのに 8.1.0 へアップグレードすると、既知の CVE が未修正のままになります。

Ruby バージョンの互換性

Rails	最小 Ruby バージョン	推奨 Ruby バージョン
5.2	2.2.2	2.5+
6.0–6.1	2.5.0	2.7+
7.0–7.1	2.7.0	3.1+
7.2	3.1.0	3.3+
8.0–8.1	3.2.0	3.3+
8.2 (未リリース)	3.3.1	3.4+

Rails 8.2 では Ruby の最低バージョンが 3.3.1 に引き上げられます。Ruby 3.2 のアプリは、8.1 より先に進む前に Ruby をアップグレードする必要があります。2 つの変更を別々にデバッグできるよう、現在の Rails バージョンのまま、先に Ruby をアップグレードしてください。

ワークフロー

ステップ 0：バージョンの評価

1. Gemfile と Gemfile.lock を読み、現在の Rails gem のバージョンを確認します
2. config/application.rb を読み、現在の config.load_defaults の値を確認します
3. .ruby-version または Gemfile で Ruby のバージョンを確認し、上記の互換性表と照合します
4. ターゲットバージョンが指定されていない場合は、ユーザーに確認します
5. ターゲットを正確なパッチバージョンに決定します（上記の「リリース状況」を参照）— ターゲット系列の最新パッチを指定します
6. 複数のマイナーバージョンをまたぐ場合は、段階的にアップグレードする計画を立てます（例：7.0 → 8.0 の場合は、7.0 → 7.1 → 7.2 → 8.0）
7. 出力：バージョン評価の概要（現在の Rails、現在の Ruby、ターゲットの Rails パッチ、必要な Ruby、アップグレード経路）

---

ステップ 0.5：Active Storage / libvips のセキュリティゲート

HARD GATE: Applies to every app that uses Active Storage with the vips variant processor.
CVE-2026-66066 (critical) — arbitrary file read and possible RCE via crafted image uploads.
Fixed in 8.1.3.1, 8.0.5.1, 7.2.3.2.

次の両方に該当するアプリが影響を受けます。

• config.active_storage.variant_processor が :vips である — load_defaults 7.0 以降のデフォルトであり、それ以降のデフォルトでも変更されていません
• 信頼できないユーザーからの画像アップロードを受け付ける

アップグレード前に実施する確認事項：

1. config/ 内で variant_processor を Grep します — 見つからない場合、デフォルトの :vips が適用されます
2. インストール済みの libvips を確認します：vips --version。修正適用後は、libvips が古い処理をブロックできないため、libvips が 8.13 未満の場合、Rails は起動時にエラーを発生させます。libvips のアップグレードは後続作業ではなく、前提条件です。
3. Gemfile.lock 内の ruby-vips を確認します — プロセス内で Vips.block_untrusted(true) を使用するには >= 2.2.1 が必要です
4. ユーザーに警告します：BMP、ICO、PSD のバリアント生成はエラーになります。アプリがこれらの形式のバリアントを提供している場合は、variable_content_types から削除し、デプロイ前に代替手段を計画してください。
5. アプリが影響を受けるバージョンで稼働し、信頼できないアップロードにさらされていた場合は、secret_key_base、マスターキー、およびアプリのプロセスからアクセスできるすべての認証情報をローテーションするようユーザーに伝えます。アップグレードによって脆弱性は解消されますが、漏えいしたシークレットが無効になるわけではありません。

出典：GHSA-xr9x-r78c-5hrm

ステップ 1：テストスイートの検証

HARD GATE: Run the test suite before ANY upgrade work.
If tests fail: STOP. Report failures. Do NOT proceed until baseline is green.
A failing baseline makes post-upgrade failures ambiguous.

1. フレームワークを特定します：spec/（RSpec）または test/（Minitest）があるか確認します
2. 実行します：bundle exec rspec または bundle exec rails test
3. 記録します：テスト総数、成功数、失敗数、保留数
4. 失敗がある場合：停止して内容を報告し、修正を支援できることを伝えます
5. すべて成功した場合：ベースラインとして記録し、ステップ 2 に進みます

---

ステップ 2：設定の差分（railsdiff.org）

GitHub のデータソースを使用して、railsdiff.org から最新の設定差分を取得します。

URL: https://api.github.com/repos/railsdiff/rails-new-output/compare/v{CURRENT}...v{TARGET}

例：https://api.github.com/repos/railsdiff/rails-new-output/compare/v7.2.0...v8.0.0

WebFetch を使用し、次のプロンプトを指定します：「これらのバージョン間で変更されたすべてのファイルを一覧表示してください。ファイルごとに、名前、ステータス（追加／変更／削除）、変更内容の概要（1～2 文）を示してください。」

結果を次のカテゴリに分類します：

• 変更された設定ファイル（config/、config/environments/、config/initializers/）
• インフラストラクチャファイル（Dockerfile、bin/、Gemfile テンプレート）
• アセットパイプラインの変更
• 追加されたファイル（対象バージョンで新規）
• 削除されたファイル

API の取得に失敗した場合の代替手順： その旨を記録し、references/detection-patterns.md と references/breaking-changes.md の静的データのみを使用して進めます。

複数ステップのアップグレードの場合： 実行中の現在の段階の差分のみを取得します。

---

ステップ 3：コードレベルの検出

1. references/detection-patterns.md の該当するバージョンのセクションを読みます
2. 各パターンについて、指定されたパス内でそのパターンを直接 Grep ツールで検索します
3. 該当箇所をファイル名と行番号、マッチした内容とともに収集します
4. references/gem-compatibility.md を読み、既知の問題がある gem が Gemfile.lock に含まれているか確認します
5. 該当する「Upgrading from X to Y」セクションを skills/rails-guides/references/upgrading_ruby_on_rails.md で照合します
6. 可能な場合は検索を並列実行します（1 つのメッセージで複数の Grep 呼び出しを行います）
7. 検出結果をまとめます：
   • アップグレード前に必ず修正する項目
   • アップグレード後に必ず修正する項目
   • 対応が必要な非推奨警告
   • 更新が必要な gem

---

ステップ 4：load_defaults の検証

HARD GATE: Verify config.load_defaults status before proceeding.
If new_framework_defaults_*.rb exists with uncommitted changes from a PREVIOUS upgrade: STOP.
Those must be resolved before starting a new upgrade.

1. config/application.rb を読み、config.load_defaults の値を確認します
2. config/initializers/new_framework_defaults_*.rb を Glob で検索します
3. 以前のアップグレードで追加された、コメントアウトされていない行を含むファイルがある場合：停止し、先に解決します
4. 該当するバージョン移行について references/load-defaults-guide.md を読みます
5. load_defaults の移行計画を作成します。安全に有効化できる設定と、先にコード変更が必要な設定を特定します

---

ステップ 5：アップグレードレポート

変更を加える前に、すべての検出結果を構造化されたレポートにまとめます：

## Rails Upgrade Report: {CURRENT} → {TARGET}

### Environment
- Current Rails: {version}
- Target Rails: {version}
- Ruby: {version} (compatible: yes/no)
- Test baseline: {N} tests, all passing

### Configuration Changes (from railsdiff.org)
{Categorized list from Step 2, or "Could not fetch — using static reference" if API failed}

### Code Changes Required

#### Must Fix Before Version Bump
{Findings from Step 3 with file:line references}

#### Must Fix After Version Bump (Deprecations Becoming Errors)
{Findings}

#### Deprecation Warnings to Address
{Findings}

### Gem Updates Required
| Gem | Current | Required | Notes |
|-----|---------|----------|-------|
{From Step 3 gem check}

### load_defaults Transition Plan
{From Step 4}

### Recommended Approach
- Direct upgrade (changes are minimal) OR
- Dual-boot with next_rails (changes are substantial — see references/dual-boot-guide.md)

### Estimated Effort
{Based on number and severity of findings}

---

ステップ 6：アップグレードの実行

HARD GATE: Present the upgrade report to the user and get explicit approval.
Do NOT modify any files until the user approves the report.

承認後の実行手順：

1. アップグレードブランチを作成します：git checkout -b rails-{TARGET}-upgrade
2. Gemfile を更新します：Rails のバージョンを上げ、特定した gem も更新します
3. bundle update rails（競合が発生したら解決します）
4. ステップ 2 の設定差分を参考に、設定を変更します
5. アップグレード前に必ず修正するコード上の問題（ステップ 3）を修正します
6. テストスイートを実行し、失敗に対処します
7. bin/rails app:update を実行します（変更をそれぞれ確認し、自動承認しないでください）
8. ステップ 4 の移行計画に従って config.load_defaults を更新します
9. テストスイートを再度実行します
10. 可能な範囲で、残りの非推奨警告を修正します
11. テスト結果とともに最終状況を報告します

---

複数ステップのアップグレード

複数のマイナーバージョンを飛び越えてアップグレードする場合（例：6.1 → 8.0）：

1. すべての段階を算出します：6.1 → 7.0 → 7.1 → 7.2 → 8.0
2. 各段階について、ステップ 0～6 を順番に実行します
3. 現在の段階ですべてのテストが成功するまで、次の段階に進まないでください
4. 各段階の後、次に進む前に config.load_defaults が更新されていることを確認します
5. 計画時には、references/breaking-changes.md の難易度表を参照します

---

デュアルブートを使用するタイミング

次の場合は、デュアルブート（next_rails gem）を使用してください。

• アップグレードの難易度が高または非常に高い場合（7.2 → 8.0、6.1 → 7.0）
• アプリのコードが 50k LOC を超える、または gem の依存関係が複雑な場合
• アップグレード中もチームが機能をリリースする必要がある場合

次の場合は、デュアルブートを使用しないでください。

• 難易度が簡単または中程度の場合（7.0 → 7.1、8.0 → 8.1）
• コードベースが小さい場合（10k LOC 未満）
• 破壊的変更が少なく、局所的な場合

---

Rails 8.2 へのアップグレード（未リリース）

Rails 8.2 は main 上の 8.2.0.alpha であり、リリースされていません。本番アプリをアップグレードしないでください。参照資料に 8.1 → 8.2 の情報があるのは、次の 2 つの理由からです。

1. Rails 8.1 の非推奨警告では、削除されるバージョンとして 8.2 が示されています。 8.2 でどのように扱われるかを知らずに、8.1 の非推奨項目を正しく評価することはできません。
2. 8.1 上での準備は無料です。 8.2 で削除される項目には、8.1 で動作する修正方法があります。

ユーザーから 8.2 について尋ねられた場合は、未リリースであることを伝えたうえで、参照資料を使って、8.1 のまま対応できる項目を列挙してください。これらの情報に依拠する前に、必ず main で再確認してください。未リリースの内容は変わる可能性があり、8.1 の機能の少なくとも 1 つ（schema.rb の列をアルファベット順に並べる機能）は、すでに main で取り消されています。

8.2 の最新情報を取得するには、次を実行します。

./scripts/fetch-changelogs.sh main ./changelogs

セットアップについては、references/dual-boot-guide.md を参照してください。

---

参照ファイル

ファイル	内容
references/breaking-changes.md	バージョンの組み合わせ別の破壊的変更（5.2 → 8.2）、高／中／低の表
references/deprecation-timeline.md	非推奨項目が導入、警告、削除された時期（9.0 の予定まで）
references/gem-compatibility.md	人気の gem 約 50 種と、Rails の各リリースで必要なバージョン
references/load-defaults-guide.md	load_defaults の全設定（5.2 → 8.2）、リスク区分、移行ガイダンス
references/detection-patterns.md	コードレベルの検出に使う Grep／Glob パターン。バージョンの組み合わせ別に整理
references/dual-boot-guide.md	next_rails のデュアルブート設定、NextRails.next? のパターン、CI 設定
references/troubleshooting.md	よくあるアップグレードエラーとその解決方法
scripts/fetch-changelogs.sh	任意のバージョンまたは main のコンポーネント CHANGELOG を GitHub から取得

関連資料：

• skills/rails-guides/references/upgrading_ruby_on_rails.md — Rails 公式アップグレードガイド（3,000 行以上）

---

クレジット

以下の成果に基づいています。

• OmbuLabs.ai / FastRuby.io（MIT）— FastRuby.io のアップグレード手法、検出パターン、gem の互換性データ
• Mario Alberto Chávez Cárdenas（MIT）— 破壊的変更の参照表、非推奨タイムラインの形式

いずれも MIT ライセンスのもとで使用しています。元のソース：

• https://github.com/ombulabs/claude-code_rails-upgrade-skill
• https://github.com/mariochavez/rails-upgrade-skill