rails-upgrade-assistant

Rails Upgrade Assistant Skill v1.0

スキルの概要

• 名前： Rails Upgrade Assistant
• バージョン： 1.0
• 目的： Rails 7.0 から 8.1.1 までのアプリケーションをインテリジェントにアップグレードします
• ベース： GitHub の公式 Rails CHANGELOG
• アップグレード戦略： 順番にのみアップグレードします（バージョンのスキップは禁止）

---

主な機能

このスキルでは、次の3ステップで Rails アプリケーションを順番にアップグレードできます。

ステップ1：破壊的変更の検出スクリプト

• Claude が、対象のアップグレードに合わせた実行可能な bash スクリプトを生成します
• スクリプトがユーザーのコードベースをスキャンして、破壊的変更を検出します
• ファイル名と行番号を示して問題を特定します
• 検出結果レポート（TXT ファイル）を生成します
• 30 秒未満で実行できます
• Neovim 連携用に、影響を受けるファイルを一覧表示します

ステップ2：ユーザーがスクリプトを実行し、検出結果を共有

• ユーザーがプロジェクトディレクトリで検出スクリプトを実行します
• スクリプトが rails_{version}_upgrade_findings.txt を出力します
• ユーザーが検出結果レポートを Claude に共有します

ステップ3：実際の検出結果に基づくレポートを Claude が生成

• 包括的なアップグレードレポート： 破壊的変更の分析、変更前と変更後のコード例、⚠️ フラグ付きのカスタムコードに関する警告、段階的な移行計画、テストチェックリスト、ロールバック計画
• app:update プレビューレポート： 設定ファイルの変更内容（変更前と変更後）を正確に表示し、新規作成するファイルを一覧表示します。影響度（HIGH/MEDIUM/LOW）を評価し、Neovim バッファーの一覧もすぐに利用できる形式で提示します

ユーザーのメリット：

• ⏱️ アップグレードごとに2～3時間を節約できます（検出を自動化）
• 🎯 破壊的変更を90％以上の精度で検出します
• 📋 すべての問題について、ファイル名と行番号を明確に示します
• 🚀 仮定ではなく、実際に検出された問題に基づくレポートを作成します
• 📊 アップグレード全体を50％高速化します

---

起動パターン

次のような発言があった場合、Claude はこのスキルを起動します。

最初のアップグレード依頼（検出スクリプトを生成）：

• 「Rails アプリを [version] にアップグレードして」
• 「Rails [x] から [y] へのアップグレードを手伝って」
• 「Rails [version] の破壊的変更を教えて」
• 「[x] から [y] へのアップグレード計画を立てて」
• 「使用中の Rails のバージョンを教えて」
• 「Rails アプリを分析してアップグレードして」
• 「Rails [version] 用の検出スクリプトを作って」
• 「破壊的変更の検出スクリプトを生成して」
• 「コード内の破壊的変更を探して」

スクリプト実行後（レポートを生成）：

• 「検出結果のファイルはこちらです」
• 「スクリプトを実行しました。結果はこちらです」
• 「検出スクリプトで [X] 件の問題が見つかりました」
• 「この検出結果を分析してもらえますか？」
• ユーザーが検出結果ファイルを共有またはアップロードする

特定のレポートを依頼（検出結果の共有後のみ）：

• 「app:update による変更を見せて」
• 「Rails [version] の設定変更をプレビューして」
• 「アップグレードレポートを生成して」
• 「包括的なレポートを作成して」

---

重要：順次アップグレード戦略

⚠️ バージョンのスキップは禁止です

Rails のアップグレードは、必ず次の順序で行う必要があります。

7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x

バージョンをスキップすることはできません。 例：

• ❌ 7.0 → 7.2（7.1 をスキップ）
• ❌ 7.0 → 8.0（7.1 と 7.2 をスキップ）
• ✅ 7.0 → 7.1（正しい順序）
• ✅ 7.1 → 7.2（正しい順序）

ユーザーが複数段階のアップグレード（例：7.0 → 8.1）を依頼した場合：

1. 順番にアップグレードする必要があることを説明します
2. 個別の段階に分けます
3. 各段階について個別のレポートを生成します
4. 次の段階に進む前に、各段階を完了するよう推奨します

---

利用可能なリソース

基本ドキュメント

• docs/README.md - 人間が読みやすい概要
• docs/QUICK-REFERENCE.md - コマンドのクイックリファレンス
• docs/USAGE-GUIDE.md - 詳細な使い方ガイド

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

• 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
• version-guides/upgrade-8.0-to-8.1.md - Rails 8.0 → 8.1

ワークフローガイド（成果物の生成時に読み込み）

• workflows/upgrade-report-workflow.md - アップグレードレポートの生成方法
• workflows/detection-script-workflow.md - 検出スクリプトの生成方法
• workflows/app-update-preview-workflow.md - app:update プレビューの生成方法

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

• examples/simple-upgrade.md - 単一ホップのアップグレード例
• examples/multi-hop-upgrade.md - 複数ホップのアップグレード例
• examples/detection-script-only.md - 検出スクリプトのみを求める場合
• examples/preview-only.md - プレビューのみを求める場合

参考資料

• reference/breaking-changes-by-version.md - クイック参照
• reference/multi-hop-strategy.md - 複数バージョンの計画
• reference/deprecations-timeline.md - 非推奨化の追跡
• reference/testing-checklist.md - 包括的なテスト
• reference/pattern-file-guide.md - パターンファイルの使用方法
• reference/quality-checklist.md - 納品前の確認
• reference/troubleshooting.md - よくある問題と解決策

検出スクリプトのリソース

• detection-scripts/patterns/rails-72-patterns.yml - Rails 7.2 のパターン
• detection-scripts/patterns/rails-80-patterns.yml - Rails 8.0 のパターン
• detection-scripts/patterns/rails-81-patterns.yml - Rails 8.1 のパターン
• detection-scripts/templates/detection-script-template.sh - Bash テンプレート

レポートのテンプレート

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

---

MCP ツールの統合

必須：Rails MCP Server

ツール：

• railsMcpServer:project_info - Rails のバージョン、構成、API モードを取得
• railsMcpServer:get_file - ファイルの内容を読み取る
• railsMcpServer:list_files - ディレクトリを参照する
• railsMcpServer:analyze_environment_config - 設定ファイルを確認する

任意：Neovim MCP Server

ツール：

• nvimMcpServer:get_project_buffers - 開いているファイルを一覧表示する
• nvimMcpServer:update_buffer - ファイルの内容を更新する

---

大まかなワークフロー

ユーザーからアップグレードを依頼された場合は、次のワークフローに従います。

ステップ 1：現在のバージョンを検出する

1. Call: railsMcpServer:project_info
2. Store: current_version, target_version, project_type, project_root

ステップ 2：検出スクリプトのリソースを読み込む

1. Read: detection-scripts/patterns/rails-{VERSION}-patterns.yml
2. Read: detection-scripts/templates/detection-script-template.sh
3. Read: workflows/detection-script-workflow.md (for generation instructions)

ステップ 3：検出スクリプトを生成する

1. Follow workflow in detection-script-workflow.md
2. Generate version-specific bash script
3. Deliver script to user
4. Instruct user to run script and share findings.txt

ステップ 4：ユーザーがスクリプトを実行するまで待つ

User runs: ./detect_rails_{version}_breaking_changes.sh
Script outputs: rails_{version}_upgrade_findings.txt
User shares findings back with Claude

ステップ 5：レポート生成用のリソースを読み込む

1. Read: templates/upgrade-report-template.md
2. Read: version-guides/upgrade-{FROM}-to-{TO}.md
3. Read: templates/app-update-preview-template.md
4. Read: workflows/upgrade-report-workflow.md
5. Read: workflows/app-update-preview-workflow.md

ステップ 6：ユーザーが実際に確認した内容を分析する

1. Parse the findings.txt file
2. Extract detected breaking changes and affected files
3. Read user's actual config files for context
4. Identify custom code patterns from findings

ステップ 7：確認内容に基づいてレポートを生成する

成果物 #1：包括的なアップグレードレポート

• ワークフロー： workflows/upgrade-report-workflow.md を参照
• 入力： スクリプトで確認した実際の内容 + バージョンガイドのデータ
• 出力： ユーザーのプロジェクトから取得した実際のコード例を含むレポート

成果物 #2：app:update のプレビュー

• ワークフロー： workflows/app-update-preview-workflow.md を参照
• 入力： 実際の設定ファイル + 確認内容
• 出力： 実際のファイルパスと変更を含むプレビュー

ステップ 8：レポートを提示する

1. Present Comprehensive Upgrade Report first
2. Present app:update Preview Report second
3. Explain next steps
4. Offer interactive help with Neovim (if available)

---

詳細なワークフローを読み込むタイミング

詳しい手順が必要な場合は、ワークフローファイルを読み込みます。

ステップ 1 - 検出スクリプトの生成前に読み込む：

• workflows/detection-script-workflow.md - 検出スクリプトを作成する前に読み込みます

ステップ 2 - ユーザーがスクリプトを実行する（Claude の操作は不要）

ステップ 3 - レポートの生成前（確認内容を受け取った後）に読み込む：

• workflows/upgrade-report-workflow.md - アップグレードレポートを作成する前に読み込みます
• workflows/app-update-preview-workflow.md - プレビューを作成する前に読み込みます

ユーザーが例を求めている場合に読み込む：

• examples/simple-upgrade.md - ユーザーがシンプルなアップグレードについて尋ねた場合
• examples/multi-hop-upgrade.md - ユーザーが複雑なアップグレードについて尋ねた場合
• examples/detection-script-only.md - ユーザーが検出スクリプトのみを求めている場合
• examples/preview-only.md - ユーザーがプレビューのみを求めている場合

参照が必要な場合に読み込む：

• reference/pattern-file-guide.md - YAML パターンファイルを処理する場合
• reference/quality-checklist.md - 出力を納品する前
• reference/troubleshooting.md - 問題が発生した場合

---

品質チェックリスト

納品前に確認してください。

検出スクリプトの場合：

• すべての {PLACEHOLDERS} が実際の値に置き換えられている
• パターンが対象の Rails バージョンに一致している
• スクリプトにパターンファイルのすべての破壊的変更が含まれている
• ファイルパスがユーザーの実際のプロジェクト構成を使用している
• ユーザーへの指示が明確である

ユーザーがスクリプトを実行した後（レポート生成前）：

• ユーザーから findings.txt を受け取り、解析した
• 検出された破壊的変更をすべて特定した
• 影響を受けるファイルパスを収集した
• findings に含まれるカスタムコードの警告を記録した

包括的なアップグレードレポートの場合：

• すべての {PLACEHOLDERS} が実際の値に置き換えられている
• スクリプトの実際の findings を使用している（一般的な例ではない）
• 破壊的変更のセクションに実際のファイル名と行番号への参照が含まれている
• カスタムコードの警告が実際に検出された問題に基づいている
• コード例に影響を受けるファイルのユーザーの実際のコードを使用している
• 次の手順が明確に示されている

app:update プレビューの場合：

• すべての {PLACEHOLDERS} が実際の値に置き換えられている
• ファイル一覧がユーザーの実際の設定ファイルと一致している
• 差分が現在の設定と対象バージョンの実際の差分に基づいている
• Neovim のバッファー一覧に影響を受けるファイルのみが含まれている
• 次の手順が明確に示されている

詳細なチェックリスト： reference/quality-checklist.md を参照してください

---

よくあるリクエストのパターン

パターン 1：完全なアップグレードのリクエスト

ユーザーの発言： 「Rails アプリを 8.1 にアップグレードしてください」

対応 - フェーズ 1（スクリプトの生成）：

1. 読み込み：workflows/detection-script-workflow.md
2. 検出スクリプトを生成する
3. 実行手順とともにスクリプトを提供する
4. ユーザーが findings.txt を共有するまで待つ

対応 - フェーズ 2（レポートの生成）：

1. findings.txt を解析する
2. 読み込み：workflows/upgrade-report-workflow.md
3. 読み込み：workflows/app-update-preview-workflow.md
4. 包括的なアップグレードレポートを生成する（実際の findings を使用）
5. app:update プレビューを生成する（実際の findings を使用）
6. 構成の参考として examples/simple-upgrade.md を参照する

パターン 2：複数段階のリクエスト

ユーザーの発言： 「Rails 7.0 から 8.1 へのアップグレードを手伝ってください」

対応：

1. 段階的なアップグレードが必要であることを説明する
2. examples/multi-hop-upgrade.md を参照する
3. パターン 1 に従い、最初の段階（7.0 → 7.1）を進める
4. 最初の段階が完了したら、次の段階でも繰り返す

パターン 3：検出スクリプトのみ

ユーザーの発言： 「Rails 8.0 用の検出スクリプトを作成してください」

対応：

1. 読み込み：workflows/detection-script-workflow.md
2. 検出スクリプトのみを生成する
3. examples/detection-script-only.md を参照する
4. まだレポートは生成しない（findings が届くまで待つ）

パターン 4：ユーザーが findings を共有して戻ってきた場合

ユーザーの発言： 「こちらが findings.txt です」またはスクリプトの出力を共有する

対応：

1. findings.txt を解析する
2. 読み込み：workflows/upgrade-report-workflow.md
3. 読み込み：workflows/app-update-preview-workflow.md
4. 包括的なアップグレードレポートを生成する
5. app:update プレビューを生成する

パターン 5：プレビューのみ（findings の共有後）

ユーザーの発言： 「Rails 7.2 の app:update による変更を表示してください」

対応：

1. ユーザーが findings を共有しているか確認する
2. 共有済みの場合：workflows/app-update-preview-workflow.md を読み込み、生成する
3. 共有されていない場合：まず検出スクリプトを実行するようユーザーに依頼する
4. examples/preview-only.md を参照する

---

重要な原則

1. 必ず最初に検出スクリプトを生成する（ユーザーがレポートのみを希望し、findings を共有済みの場合を除く）
2. ユーザーがスクリプトを実行するまで待つ（レポートは実際の findings に依存する）
3. 必ず実際の findings を使用する（レポートに一般的な例を使わない）
4. カスタムコードには必ず警告を付ける（検出された問題に基づいて ⚠️ 警告を示す）
5. 必ずテンプレートを使用する（一貫性を保つため）
6. 必ず品質を確認する（納品前に確認する）
7. 必要に応じてワークフローを読み込む（すべてをメモリーに保持しない）
8. 段階的なプロセスが重要（スクリプト → findings → レポート）

---

ファイル構成

このスキルはモジュール構造に従っています。

rails-upgrade-assistant/
├── SKILL.md                          # This file (high-level)
├── workflows/                        # Detailed how-to guides
│   ├── upgrade-report-workflow.md
│   ├── detection-script-workflow.md
│   └── app-update-preview-workflow.md
├── examples/                         # Usage examples
│   ├── simple-upgrade.md
│   ├── multi-hop-upgrade.md
│   ├── detection-script-only.md
│   └── preview-only.md
├── reference/                        # Reference documentation
│   ├── pattern-file-guide.md
│   ├── quality-checklist.md
│   └── troubleshooting.md
├── version-guides/                   # Version-specific guides
├── templates/                        # Report templates
└── detection-scripts/                # Pattern files and templates

読み込む対象とタイミング：

• 成果物を生成するときは workflows/ を読み込む
• ユーザーに説明が必要なときは examples/ を読み込む
• 詳細なガイダンスが必要なときは reference/ を読み込む

---

成功基準

アップグレード支援セッションが成功したと判断される条件：

✅ 検出スクリプトを生成した（フェーズ 1）
✅ ユーザーがスクリプトを実行し、findings.txt を共有した（フェーズ 2）
✅ 実際の検出結果を使用して包括的なアップグレードレポートを生成した（フェーズ 3）
✅ 実際の検出結果を使用して app:update のプレビューを生成した（フェーズ 3）
✅ 汎用的な例ではなく、検出結果に含まれるユーザーの実際のコードを使用した
✅ 検出された問題に基づき、すべてのカスタムコードに ⚠️ 警告を付けた
✅ 明確な次の手順を提示した
✅ 対話型のサポートを提供した（Neovim が利用可能な場合）

検証： reference/quality-checklist.md を参照してください。

---

バージョン： 1.0
最終更新日： 2025 年 11 月 2 日
スキルの種類： 外部ワークフローと例を備えたモジュール型