rails-upgrade

Rails Upgrade Assistant スキル

スキルの概要

• 名前： Rails Upgrade Assistant
• 目的： 2.3 から 8.1 までの Rails アプリケーションをインテリジェントにアップグレードします
• スキルの種類： 外部ワークフローとサンプルを備えたモジュール型
• アップグレード戦略： 順次アップグレードのみ（バージョンのスキップ不可）
• 方法論： FastRuby.io のアップグレードのベストプラクティスと電子書籍「The Complete Guide to Upgrade Rails」に基づいています
• クレジット： FastRuby.io（OmbuLabs）による「The Complete Guide to Upgrade Rails」に基づくコンテンツです

---

用語

用語	意味	場所
ワークフロー	アップグレードの流れを構成する番号付きの単位。1 ファイルにつき 1 つです	workflows/<NN>-<name>-workflow.md
ステップ	ワークフローファイル内の Step N ヘッダーです	ワークフロー内
リファレンス	必要に応じて読み込む資料です。ルックアップテーブル、プレイブック、条件分岐などが該当します	references/<name>-reference.md

サブステップはありません。「Step 4.1」は、連続する 2 つのステップか、1 つのステップ内の条件分岐（### A.／### B. ヘッダー）のいずれかです。ワークフロー全体は Workflow NN、ステップはファイルパスとステップ番号で参照します（例：workflows/01-run-test-suite-workflow.md Step 4）。見出しでは Stage、Phase、Sub-step、ドット付きのステップ番号を使用しません。

---

依存関係

• dual-boot スキル（github.com/ombulabs/claude-code_dual-boot-skill）— next_rails gem を使用して、デュアルブート環境をセットアップおよび管理します。セットアップ、NextRails.next? のコードパターン、CI の設定、アップグレード後のクリーンアップを扱います。Workflow 04 で使用するため、インストールが必要です。
  • Workflow 04 のファイル：workflows/04-setup-next-rails-workflow.md
• rails-load-defaults スキル（github.com/ombulabs/claude-code_rails-load-defaults-skill）— リスクを段階的に評価しながら、load_defaults を段階的に更新します（Tier 1：低リスク、Tier 2：コードベースの grep が必要、Tier 3：人によるレビューが必要）。Rails のバージョンアップグレード完了後、最後のステップとして使用します。

---

基本的な方法論（FastRuby.io のアプローチ）

このスキルは、FastRuby.io の実績あるアップグレード方法論に従います。

1. 段階的なアップグレード - 常にマイナーまたはメジャーバージョンを 1 つずつアップグレードします
2. まずは評価 - 変更を加える前に、範囲を把握します
3. デュアルブートテスト - 移行期間中、next_rails gem を使用して両方のバージョンをテストします
4. テストカバレッジ - アップグレード前に十分なテストカバレッジを確保します（80% 以上を目指します）
5. Gem の互換性 - 各ステップで RailsBump を使用して Gem の互換性を確認します
6. 非推奨警告 - アップグレード前に非推奨項目に対処します
7. 後方互換性のある変更 - バージョンを上げる前に、小さな変更を本番環境にデプロイします

主なリソース：

• next_rails を使用するデュアルブートのセットアップについては、dual-boot スキルに委任します（依存関係を参照）
• 非推奨項目の管理については、references/deprecation-warnings-reference.md を参照してください
• アップグレードを継続的に維持する方法については、references/staying-current-reference.md を参照してください

---

重要：NextRails.next? を使用したデュアルブートのコードパターン

現在の Rails バージョンと対象の Rails バージョンの両方で動作する必要があるコード修正を提案する場合（デュアルブート）、必ず next_rails gem の NextRails.next? を使用してください。respond_to? やその他の機能検出パターンは使用しないでください。

以下については、dual-boot スキルに委任します。

• セットアップと初期化（next_rails --init、Gemfile.next）
• NextRails.next? のコードパターンとサンプル
• デュアルブートテストの CI 設定
• アップグレード後のクリーンアップ（デュアルブート分岐の削除）

依存関係： dual-boot スキルが必要です

---

利用可能なリソース

コアドキュメント

• SKILL.md - このファイル（エントリーポイント）

バージョン別ガイド（必要に応じて読み込み）

旧バージョンのRails：

• version-guides/upgrade-3.2-to-4.0.md - Rails 3.2 → 4.0（Strong Parameters）
• version-guides/upgrade-4.0-to-4.1.md - Rails 4.0 → 4.1（Spring、secrets.yml、enum）
• version-guides/upgrade-4.1-to-4.2.md - Rails 4.1 → 4.2（ActiveJob、Web Console）
• version-guides/upgrade-4.2-to-5.0.md - Rails 4.2 → 5.0（ApplicationRecord）

モダンなRails：

• version-guides/upgrade-5.0-to-5.1.md - Rails 5.0 → 5.1（暗号化されたシークレット）
• version-guides/upgrade-5.1-to-5.2.md - Rails 5.1 → 5.2（Active Storage、Credentials）
• version-guides/upgrade-5.2-to-6.0.md - Rails 5.2 → 6.0（Zeitwerk）
• version-guides/upgrade-6.0-to-6.1.md - Rails 6.0 → 6.1（水平シャーディング）
• version-guides/upgrade-6.1-to-7.0.md - Rails 6.1 → 7.0（Hotwire/Turbo）
• version-guides/upgrade-7.0-to-7.1.md - Rails 7.0 → 7.1（複合キー）
• version-guides/upgrade-7.1-to-7.2.md - Rails 7.1 → 7.2（トランザクションジョブ）
• version-guides/upgrade-7.2-to-8.0.md - Rails 7.2 → 8.0（Propshaft）
• version-guides/upgrade-8.0-to-8.1.md - Rails 8.0 → 8.1（bundler-audit）

例（ユーザーが説明を求めている場合に読み込み）

• examples/simple-upgrade.md - 1段階のアップグレード例
• examples/multi-hop-upgrade.md - 複数段階のアップグレード例

外部依存関係

• dual-boot skill - next_rails を使ったデュアルブートのセットアップと管理（ワークフロー 04）（https://github.com/ombulabs/claude-code_dual-boot-skill）
• rails-load-defaults skill - load_defaults の段階的な整合（ワークフロー 12）（https://github.com/ombulabs/claude-code_rails-load-defaults-skill）
• upgrade-cleanup companion plugin - ユーザーが起動します。デュアルブートの足場を削除し、NextRails.next? / NextRails.current? の分岐を取り除きます。次の段階に向けた非推奨項目のトリアージは、このスキルが引き続き担当します。

参考資料

• references/sequential-strategy-reference.md - 順次アップグレードのルール（バージョンを飛ばさない）と、サポート対象のアップグレードパスの表。ワークフロー 03 で読み込みます。
• references/request-patterns-reference.md - リクエストの形式ごとに実行するワークフロー（全体のアップグレード、複数段階、分析のみ、レポートのみ）。セッション開始時に読み込みます。
• references/next-hop-readiness-reference.md - 「次のRailsバージョンに向けて何が必要ですか？」への読み取り専用の回答。次段階への対応状況を確認するリクエスト形式の場合に読み込みます。
• references/no-test-suite-smoke-reference.md - 実行可能なRSpec/Minitestテストスイートが存在しない場合、ワークフロー 01 から読み込みます - Railsの起動、ルート、マイグレーションの状態、ビルドのスモークテストのベースラインと、確信度が部分的である旨のレポート
• references/deprecation-warnings-reference.md - 非推奨項目の検出と修正
• references/staying-current-reference.md - Railsのリリースに追随する方法
• references/breaking-changes-by-version-reference.md - クイックリファレンス
• references/multi-hop-strategy-reference.md - 複数バージョンにわたる計画
• references/testing-checklist-reference.md - 包括的なテスト
• references/gem-compatibility-reference.md - Gemの更新順序と「互換バージョンなし」の対処手順（フォーク／ベンダー化／置き換え）。ワークフロー 06 の互換性チェックでブロッカーが見つかった場合にのみ読み込みます。
• references/js-compressor-sprockets-mismatch-reference.md - 対象のRailsがSprocketsを2.x系に固定している場合に、terserを動作させ続ける方法。JS_COMPRESSOR_GEM_MISMATCH が発生した場合にのみ読み込みます。

検出パターンのリソース

• detection-scripts/patterns/rails-*.yml - 直接検出用のバージョン別パターン
• detection-scripts/scan_patterns.rb - アプリに対して、ある段階のすべてのパターンを実行し、検出結果の表を出力します。ワークフロー 05 では、パターンごとにGrepを実行する代わりに使用します。
• detection-scripts/gem_limits.rb - lockfileのみを使い、gemspecで対象のRailsが除外されているロック済みGemを一覧表示します。ワークフロー 06 の最初の確認に使用します。

レポートテンプレート

• templates/upgrade-report-template.md - メインのアップグレードレポートの構成
• templates/app-update-preview-template.md - 設定のプレビュー

---

ワークフロー一覧

ユーザーからアップグレードを依頼された場合は、このワークフローに従ってください。順序どおりに進めることが重要です。順番に実行し、各ファイルはその段階に達したときに読み込んでください。ゲートに該当すると進行できません。

#	名前	目的	ファイル
00	最新のパッチを確認	必須の事前ステップ。マイナー／メジャーアップグレードを行う前に、アプリが現在のシリーズの最新パッチを適用していることを確認します	workflows/00-verify-latest-patch-workflow.md
01	テストスイートを実行	必須の最初のステップ。テストスイートの実行方法と検証方法を確認します。失敗がある場合は進行できません	workflows/01-run-test-suite-workflow.md
02	非推奨警告を解決	警告を確認できるようにし、現在のバージョンで出力される警告を収集して、現在のバージョンで修正します	workflows/02-resolve-deprecation-warnings-workflow.md
03	アップグレードパスを検証	単一ホップまたは複数ホップを判断し、各ホップの計画を立てます	workflows/03-validate-upgrade-path-workflow.md
04	next_rails をセットアップ	早期セットアップです。「外部依存関係」に記載されたスキルに委任します	workflows/04-setup-next-rails-workflow.md
05	破壊的変更を検出	破壊的変更を直接検出する方法を確認します	workflows/05-detect-breaking-changes-workflow.md
06	gem の互換性を確認	ロックファイルごとに、対象の Rails バージョンとの gem の互換性を確認します	workflows/06-check-gem-compatibility-workflow.md
07	起動スモークテスト	Gemfile.next で起動し、そこでモデルのテストスイートを実行して、依存関係の解決や grep では検出できない問題を見つけます	workflows/07-boot-smoke-test-workflow.md
08	アップグレードレポートを生成	アップグレードレポートの生成方法を確認します	workflows/08-generate-upgrade-report-workflow.md
09	app:update のプレビューを生成	app:update のプレビューを生成する方法を確認します	workflows/09-generate-app-update-preview-workflow.md
10	実装してアップグレード	レポートを提示し、バージョン更新前に修正が必要な変更を適用し、Gemfile のバージョンを更新して、両方のバージョンでテストを実行します	workflows/10-implement-and-upgrade-workflow.md
11	CI 設定を同期	アップグレード PR を作成する前に必ず実施します。CI 設定がアップグレード後の Gemfile と一致していることを確認します	workflows/11-sync-ci-workflow.md
12	load_defaults を調整	アップグレード完了後に実施します。rails-load-defaults スキルに委任します	workflows/12-align-load-defaults-workflow.md
13	クリーンアップに言及	ユーザーが明示的に依頼した場合に限り、upgrade-cleanup プラグインに委任します	workflows/13-mention-cleanup-workflow.md

「目的」列は要約です。ゲートは各ワークフローの ## Gates セクションにのみ記載されています。実行するワークフローは、依頼の内容（完全なアップグレード、複数ホップ、分析のみ、レポートのみ）によって異なります。references/request-patterns-reference.md を参照してください。

---

主な原則

1. 検出を直接実行する（detection-scripts/scan_patterns.rb を実行してから、影響を受けるファイルを読み込みます。ユーザーに実行させるための検出スクリプトは生成しないでください）
2. 必要に応じてワークフローを読み込む（すべてをメモリに保持しないでください）
3. FastRuby.io の方法論に従う（段階的にアップグレードし、まず評価を行います）

以前ここに記載されていたその他の事項は、それぞれを管轄するワークフローに記載されています。各ワークフローの「目的」と「ゲート」を参照してください。