Back to Details

rails-upgrade

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Rails Upgrade Assistant Skill

Rails升级助手技能

Skill Identity

技能信息

  • Name: Rails Upgrade Assistant
  • Purpose: Intelligent Rails application upgrades from 2.3 through 8.1
  • Skill Type: Modular with external workflows and examples
  • Upgrade Strategy: Sequential only (no version skipping)
  • Methodology: Based on FastRuby.io upgrade best practices and "The Complete Guide to Upgrade Rails" ebook
  • Attribution: Content based on "The Complete Guide to Upgrade Rails" by FastRuby.io (OmbuLabs)
  • 名称: Rails Upgrade Assistant
  • 用途: 支持Rails 2.3到8.1版本的智能应用升级
  • 技能类型: 模块化设计，包含外部工作流和示例
  • 升级策略: 仅支持顺序升级（禁止跨版本升级）
  • 方法论: 基于FastRuby.io升级最佳实践和《Rails升级完全指南》电子书
  • 归属: 内容基于FastRuby.io（OmbuLabs）出品的《Rails升级完全指南》

Dependencies

依赖项

  • rails-load-defaults skill (github.com/ombulabs/claude-code_rails-load-defaults-skill) — Handles incremental 
    load_defaults
    updates with tiered risk assessment (Tier 1: low-risk, Tier 2: needs codebase grep, Tier 3: requires human review). Must be installed for Step 2 of the upgrade workflow.
  • dual-boot skill (github.com/ombulabs/claude-code_dual-boot-skill) — Sets up and manages dual-boot environments using the 
    next_rails
    gem. Covers setup, 
    NextRails.next?
    code patterns, CI configuration, and post-upgrade cleanup. Must be installed for Step 4 of the upgrade workflow.
  • rails-load-defaults skill (github.com/ombulabs/claude-code_rails-load-defaults-skill) — 处理
    load_defaults
    的增量更新，附带分级风险评估（1级：低风险，2级：需要代码库检索，3级：需要人工审核）。升级工作流的第2步必须安装此依赖。
  • dual-boot skill (github.com/ombulabs/claude-code_dual-boot-skill) — 使用
    next_rails
    gem搭建和管理双启动环境，覆盖配置、
    NextRails.next?
    代码模式、CI配置、升级后清理等能力。升级工作流的第4步必须安装此依赖。

Core Methodology (FastRuby.io Approach)

核心方法论（FastRuby.io 方案）

This skill follows the proven FastRuby.io upgrade methodology:
  1. Incremental Upgrades - Always upgrade one minor/major version at a time
  2. Assessment First - Understand scope before making changes
  3. Dual-Boot Testing - Test both versions during transition using 
    next_rails
    gem
  4. Test Coverage - Ensure adequate test coverage before upgrading (aim for 80%+)
  5. Gem Compatibility - Check gem compatibility at each step using RailsBump
  6. Deprecation Warnings - Address deprecations before upgrading
  7. Backwards Compatible Changes - Deploy small changes to production before version bump
Key Resources:
  • DELEGATE to the 
    dual-boot
    skill for dual-boot setup with 
    next_rails
    (see Dependencies)
  • See 
    reference/deprecation-warnings.md
    for managing deprecations
  • See 
    reference/staying-current.md
    for maintaining upgrades over time
本技能遵循经过验证的FastRuby.io升级方法论：
  1. 增量升级 - 每次仅升级一个次版本/主版本
  2. 评估优先 - 变更前先明确升级范围
  3. 双启动测试 - 过渡阶段使用
    next_rails
    gem同时测试两个版本
  4. 测试覆盖 - 升级前确保足够的测试覆盖率（目标80%以上）
  5. Gem兼容性 - 每一步都使用RailsBump检查gem兼容性
  6. 弃用警告处理 - 升级前先解决所有弃用警告
  7. 向后兼容变更 - 版本升级前先将小型变更部署到生产环境
核心资源：
  • 双启动环境搭配
    next_rails
    的配置请委托给
    dual-boot
    技能处理（见依赖项）
  • 弃用项管理可查看
    reference/deprecation-warnings.md
  • 长期维护升级节奏可查看
    reference/staying-current.md

CRITICAL: Dual-Boot Code Pattern with 
NextRails.next?

重要说明：搭配
NextRails.next?
的双启动代码模式

When proposing code fixes that must work with both the current and target Rails versions (dual-boot), always use 
NextRails.next?
from the 
next_rails
gem — never use 
respond_to?
or other feature-detection patterns.
DELEGATE to the 
dual-boot
skill for:
  • Setup and initialization (
    next_rails --init
    , 
    Gemfile.next
    )
  • NextRails.next?
    code patterns and examples
  • CI configuration for dual-boot testing
  • Post-upgrade cleanup (removing dual-boot branches)
DEPENDENCY: Requires the dual-boot skill
当提供需要同时兼容当前和目标Rails版本（双启动）的代码修复方案时，必须使用
next_rails
gem提供的
NextRails.next?
方法 — 禁止使用
respond_to?
或其他特性检测模式。
以下场景请委托给
dual-boot
技能处理：
  • 环境配置和初始化（
    next_rails --init
    、
    Gemfile.next
    ）
  • NextRails.next?
    代码模式和示例
  • 双启动测试的CI配置
  • 升级后清理（移除双启动分支）
依赖要求： 需要安装dual-boot skill

Core Workflow (5-Step Process)

核心工作流（5步流程）

Step 0: Verify Latest Patch Version (MANDATORY PRE-STEP)

第0步：确认当前最新补丁版本（强制前置步骤）

  • CRITICAL: Before any upgrade work begins, verify the app is on the latest patch release of its current Rails series
  • Read 
    Gemfile.lock
    to find the exact current Rails version (e.g., 
    3.2.19
    )
  • Compare against the latest patch for that series:
    • EOL series (≤ 6.1): Use the static table in 
      reference/multi-hop-strategy.md
    • Active series (≥ 7.0): Query the RubyGems API at runtime (see 
      reference/multi-hop-strategy.md
      for commands)
  • If the app is NOT on the latest patch:
    • Inform user: "Your app is on Rails X.Y.Z but the latest patch is X.Y.W — you should upgrade to the latest patch first"
    • Guide user through updating the Gemfile and running 
      bundle update rails
    • Run test suite after patch upgrade to verify nothing broke
    • Deploy patch upgrade before proceeding with the minor/major version hop
  • If the app IS on the latest patch → Proceed to Step 1
  • Why: Patch releases contain security fixes, bug fixes, and additional deprecation warnings that make the next version hop safer and easier to debug
  • 重要提醒： 开始任何升级工作前，必须确认应用运行在当前Rails系列的最新补丁版本上
  • 读取
    Gemfile.lock
    获取当前准确的Rails版本（例如
    3.2.19
    ）
  • 与当前系列的最新补丁版本对比：
    • 已停止维护的系列（≤ 6.1）： 使用
      reference/multi-hop-strategy.md
      中的静态对照表
    • 仍在维护的系列（≥ 7.0）： 运行时查询RubyGems API（命令参考
      reference/multi-hop-strategy.md
      ）
  • 如果应用未运行在最新补丁版本：
    • 告知用户：「您的应用当前运行在Rails X.Y.Z版本，最新补丁版本为X.Y.W — 您应该先升级到最新补丁版本」
    • 引导用户更新Gemfile并运行
      bundle update rails
    • 补丁升级后运行测试套件确认没有功能损坏
    • 补丁版本部署后再继续次版本/主版本升级
  • 如果应用已经运行在最新补丁版本 → 进入第1步
  • 设计原因： 补丁版本包含安全修复、bug修复和额外的弃用警告，能让后续版本升级更安全，也更易调试问题

Step 1: Run Test Suite (MANDATORY FIRST STEP)

第1步：运行测试套件（强制第一步）

  • CRITICAL: Before any upgrade work begins, run the existing test suite
  • Claude executes 
    bundle exec rspec
    or 
    bundle exec rails test
    to verify baseline
  • All tests MUST pass before proceeding with any upgrade
  • If tests fail, stop and help user fix failing tests first
  • Record test count and coverage as baseline metrics
  • See 
    workflows/test-suite-verification-workflow.md
    for details
  • 重要提醒： 开始任何升级工作前，必须运行现有测试套件
  • Claude执行
    bundle exec rspec
    或
    bundle exec rails test
    确认基准功能正常
  • 所有测试必须全部通过才能继续升级流程
  • 如果测试失败，暂停升级先协助用户修复失败的测试
  • 记录测试数量和覆盖率作为基准指标
  • 详细流程可查看
    workflows/test-suite-verification-workflow.md

Step 2: Verify load_defaults Matches Current Rails Version

第2步：确认load_defaults与当前Rails版本匹配

  • CRITICAL: Check if 
    load_defaults
    in 
    config/application.rb
    matches the current Rails gem version
  • DELEGATE to the 
    rails-load-defaults
    skill for detection and incremental update
  • That skill handles tiered, per-config updates with test runs between each change
  • If 
    load_defaults
    matches current Rails version → Proceed to Step 3
  • DEPENDENCY: Requires the rails-load-defaults skill
  • 重要提醒： 检查
    config/application.rb
    中的
    load_defaults
    配置是否与当前Rails gem版本匹配
  • 检测和增量更新请委托给
    rails-load-defaults
    技能处理
  • 该技能会处理分级的逐配置更新，每次变更后都会运行测试
  • 如果
    load_defaults
    与当前Rails版本匹配 → 进入第3步
  • 依赖要求： 需要安装rails-load-defaults skill

Step 3: Run Breaking Changes Detection (DIRECT)

第3步：运行破坏性变更检测（直接执行）

  • Claude runs detection checks directly using Grep, Glob, and Read tools
  • No script generation - Claude searches the codebase in real-time
  • Finds issues with file:line references
  • Collects all findings immediately
  • See 
    workflows/direct-detection-workflow.md
    for patterns to search
  • Claude直接使用Grep、Glob和读取工具运行检测检查
  • 无需生成脚本 - Claude实时检索代码库
  • 定位问题并返回「文件:行号」引用
  • 立即收集所有检测结果
  • 检索模式可查看
    workflows/direct-detection-workflow.md

Step 4: Generate Reports Based on Findings

第4步：基于检测结果生成报告

  • Comprehensive Upgrade Report: Breaking changes analysis with OLD vs NEW code examples, custom code warnings with ⚠️ flags, step-by-step migration plan, testing checklist and rollback plan
  • app:update Preview Report: Shows exact configuration file changes (OLD vs NEW), lists new files to be created, impact assessment (HIGH/MEDIUM/LOW)
  • 全面升级报告：包含新旧代码示例对比的破坏性变更分析、带⚠️标识的自定义代码警告、分步迁移计划、测试检查清单和回滚方案
  • app:update预览报告：展示准确的配置文件变更（新旧对比）、待创建的新文件列表、影响程度评估（高/中/低）

Trigger Patterns

触发模式

Claude should activate this skill when user says:
Upgrade Requests:
  • "Upgrade my Rails app to [version]"
  • "Help me upgrade from Rails [x] to [y]"
  • "What breaking changes are in Rails [version]?"
  • "Plan my upgrade from [x] to [y]"
  • "What Rails version am I using?"
  • "Analyze my Rails app for upgrade"
  • "Find breaking changes in my code"
  • "Check my app for Rails [version] compatibility"
Specific Report Requests:
  • "Show me the app:update changes"
  • "Preview configuration changes for Rails [version]"
  • "Generate the upgrade report"
  • "What will change if I upgrade?"
当用户发出以下请求时，Claude应该激活本技能：
升级请求：
  • "Upgrade my Rails app to [version]" / 「将我的Rails应用升级到[版本]」
  • "Help me upgrade from Rails [x] to [y]" / 「帮我把Rails从[x]版本升级到[y]版本」
  • "What breaking changes are in Rails [version]?" / 「Rails[版本]有哪些破坏性变更？」
  • "Plan my upgrade from [x] to [y]" / 「帮我规划从[x]到[y]的升级方案」
  • "What Rails version am I using?" / 「我当前用的是哪个Rails版本？」
  • "Analyze my Rails app for upgrade" / 「分析我的Rails应用升级可行性」
  • "Find breaking changes in my code" / 「找出我代码里的破坏性变更」
  • "Check my app for Rails [version] compatibility" / 「检查我的应用和Rails[版本]的兼容性」
特定报告请求：
  • "Show me the app:update changes" / 「展示app:update的变更」
  • "Preview configuration changes for Rails [version]" / 「预览Rails[版本]的配置变更」
  • "Generate the upgrade report" / 「生成升级报告」
  • "What will change if I upgrade?" / 「升级后会有哪些变化？」

CRITICAL: Sequential Upgrade Strategy

重要说明：顺序升级策略

⚠️ Version Skipping is NOT Allowed

⚠️ 禁止跨版本升级

Rails upgrades MUST follow a sequential path. Examples:
For Rails 5.x to 8.x:
5.0.x → 5.1.x → 5.2.x → 6.0.x → 6.1.x → 7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x
You CANNOT skip versions. Examples:
  • ❌ 5.2 → 6.1 (skips 6.0)
  • ❌ 6.0 → 7.0 (skips 6.1)
  • ❌ 7.0 → 8.0 (skips 7.1 and 7.2)
  • ✅ 5.2 → 6.0 (correct)
  • ✅ 7.0 → 7.1 (correct)
  • ✅ 7.2 → 8.0 (correct)
If user requests a multi-hop upgrade (e.g., 5.2 → 8.1):
  1. Explain the sequential requirement
  2. Break it into individual hops
  3. Generate separate reports for each hop
  4. Recommend completing each hop fully before moving to next
Rails升级必须遵循顺序升级路径，示例：
从Rails 5.x升级到8.x：
5.0.x → 5.1.x → 5.2.x → 6.0.x → 6.1.x → 7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x
禁止跨版本升级，示例：
  • ❌ 5.2 → 6.1（跳过6.0版本）
  • ❌ 6.0 → 7.0（跳过6.1版本）
  • ❌ 7.0 → 8.0（跳过7.1和7.2版本）
  • ✅ 5.2 → 6.0（正确）
  • ✅ 7.0 → 7.1（正确）
  • ✅ 7.2 → 8.0（正确）
如果用户请求多跳升级（例如5.2 → 8.1）：
  1. 告知用户必须顺序升级的要求
  2. 将升级拆分为多个单独的升级步骤
  3. 为每个步骤生成单独的报告
  4. 建议用户完成一个步骤的全部升级后再进入下一个步骤

Supported Upgrade Paths

支持的升级路径

Legacy Rails (2.3 - 4.2)

旧版本Rails（2.3 - 4.2）

FromToDifficultyKey ChangesRuby Required
2.3.x3.0.xVery HardXSS protection, routes syntax1.8.7 - 1.9.3
3.0.x3.1.xMediumAsset pipeline, jQuery1.8.7 - 1.9.3
3.1.x3.2.xEasyRuby 1.9.3 support1.8.7 - 2.0
3.2.x4.0.xHardStrong Parameters, Turbolinks1.9.3+
4.0.x4.1.xMediumSpring, secrets.yml1.9.3+
4.1.x4.2.xMediumActiveJob, Web Console1.9.3+
4.2.x5.0.xHardActionCable, API mode, ApplicationRecord2.2.2+
起始版本目标版本难度核心变更所需Ruby版本
2.3.x3.0.x非常难XSS防护、路由语法1.8.7 - 1.9.3
3.0.x3.1.x中等资源管道、jQuery1.8.7 - 1.9.3
3.1.x3.2.x简单支持Ruby 1.9.31.8.7 - 2.0
3.2.x4.0.x难强参数、Turbolinks1.9.3+
4.0.x4.1.x中等Spring、secrets.yml1.9.3+
4.1.x4.2.x中等ActiveJob、Web控制台1.9.3+
4.2.x5.0.x难ActionCable、API模式、ApplicationRecord2.2.2+

Modern Rails (5.0 - 8.1)

新版本Rails（5.0 - 8.1）

FromToDifficultyKey ChangesRuby Required
5.0.x5.1.xEasyEncrypted secrets, yarn default2.2.2+
5.1.x5.2.xMediumActive Storage, credentials2.2.2+
5.2.x6.0.xHardZeitwerk, Action Mailbox/Text2.5.0+
6.0.x6.1.xMediumHorizontal sharding, strict loading2.5.0+
6.1.x7.0.xHardHotwire/Turbo, Import Maps2.7.0+
7.0.x7.1.xMediumComposite keys, async queries2.7.0+
7.1.x7.2.xMediumTransaction-aware jobs, DevContainers3.1.0+
7.2.x8.0.xVery HardPropshaft, Solid gems, Kamal3.2.0+
8.0.x8.1.xEasyBundler-audit, max_connections3.2.0+
起始版本目标版本难度核心变更所需Ruby版本
5.0.x5.1.x简单加密密钥、默认集成yarn2.2.2+
5.1.x5.2.x中等Active Storage、凭证管理2.2.2+
5.2.x6.0.x难Zeitwerk自动加载、Action Mailbox/Text2.5.0+
6.0.x6.1.x中等水平分库、严格加载2.5.0+
6.1.x7.0.x难Hotwire/Turbo、Import Maps2.7.0+
7.0.x7.1.x中等复合主键、异步查询2.7.0+
7.1.x7.2.x中等事务感知任务、DevContainers3.1.0+
7.2.x8.0.x非常难Propshaft、Solid全家桶gem、Kamal3.2.0+
8.0.x8.1.x简单Bundler-audit、max_connections配置3.2.0+

Available Resources

可用资源

Core Documentation

核心文档

  • SKILL.md
    - This file (entry point)
  • SKILL.md
    - 本文件（入口点）

Version-Specific Guides (Load as needed)

特定版本指南（按需加载）

Legacy Rails:
  • version-guides/upgrade-3.2-to-4.0.md
    - Rails 3.2 → 4.0 (Strong Parameters)
  • version-guides/upgrade-4.2-to-5.0.md
    - Rails 4.2 → 5.0 (ApplicationRecord)
Modern Rails:
  • version-guides/upgrade-5.0-to-5.1.md
    - Rails 5.0 → 5.1 (Encrypted secrets)
  • 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 (Horizontal sharding)
  • 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 (Composite keys)
  • version-guides/upgrade-7.1-to-7.2.md
    - Rails 7.1 → 7.2 (Transaction jobs)
  • 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)
旧版本Rails：
  • version-guides/upgrade-3.2-to-4.0.md
    - Rails 3.2 → 4.0（强参数）
  • 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、凭证管理）
  • 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）

Workflow Guides (Load when generating deliverables)

工作流指南（生成交付物时加载）

  • workflows/test-suite-verification-workflow.md
    - MANDATORY FIRST STEP - How to run and verify test suite
  • EXTERNAL DEPENDENCY: 
    rails-load-defaults
    skill - MANDATORY SECOND STEP - Verify and update load_defaults to match Rails version (https://github.com/ombulabs/claude-code_rails-load-defaults-skill)
  • workflows/direct-detection-workflow.md
    - How to run breaking change detection directly
  • workflows/upgrade-report-workflow.md
    - How to generate upgrade reports
  • workflows/app-update-preview-workflow.md
    - How to generate app:update previews
  • workflows/test-suite-verification-workflow.md
    - 强制第一步 - 如何运行和验证测试套件
  • 外部依赖： 
    rails-load-defaults
    技能 - 强制第二步 - 验证和更新load_defaults匹配Rails版本 (https://github.com/ombulabs/claude-code_rails-load-defaults-skill)
  • workflows/direct-detection-workflow.md
    - 如何直接运行破坏性变更检测
  • workflows/upgrade-report-workflow.md
    - 如何生成升级报告
  • workflows/app-update-preview-workflow.md
    - 如何生成app:update预览

Examples (Load when user needs clarification)

示例（用户需要澄清时加载）

  • examples/simple-upgrade.md
    - Single-hop upgrade example
  • examples/multi-hop-upgrade.md
    - Multi-hop upgrade example
  • examples/simple-upgrade.md
    - 单跳升级示例
  • examples/multi-hop-upgrade.md
    - 多跳升级示例

Reference Materials

参考资料

  • EXTERNAL DEPENDENCY: 
    dual-boot
    skill - Dual-boot setup and management with next_rails (https://github.com/ombulabs/claude-code_dual-boot-skill)
  • reference/deprecation-warnings.md
    - Finding and fixing deprecations
  • reference/staying-current.md
    - Keeping up with Rails releases
  • reference/breaking-changes-by-version.md
    - Quick lookup
  • reference/multi-hop-strategy.md
    - Multi-version planning
  • reference/testing-checklist.md
    - Comprehensive testing
  • reference/gem-compatibility.md
    - Common gem version requirements
  • 外部依赖： 
    dual-boot
    技能 - 使用next_rails搭建和管理双启动环境 (https://github.com/ombulabs/claude-code_dual-boot-skill)
  • reference/deprecation-warnings.md
    - 查找和修复弃用项
  • reference/staying-current.md
    - 跟进Rails版本发布
  • reference/breaking-changes-by-version.md
    - 快速查询
  • reference/multi-hop-strategy.md
    - 多版本升级规划
  • reference/testing-checklist.md
    - 全面测试清单
  • reference/gem-compatibility.md
    - 常用gem版本要求

Detection Pattern Resources

检测模式资源

  • detection-scripts/patterns/rails-*.yml
    - Version-specific patterns for direct detection
  • detection-scripts/patterns/rails-*.yml
    - 直接检测用的特定版本匹配模式

Report Templates

报告模板

  • templates/upgrade-report-template.md
    - Main upgrade report structure
  • templates/app-update-preview-template.md
    - Configuration preview
  • templates/upgrade-report-template.md
    - 主升级报告结构
  • templates/app-update-preview-template.md
    - 配置变更预览

High-Level Workflow

高层工作流

When user requests an upgrade, follow this workflow:
当用户请求升级时，遵循以下工作流：

Step 0: Verify Latest Patch Version (MANDATORY PRE-STEP)

第0步：确认最新补丁版本（强制前置步骤）

⚠️  THIS STEP IS REQUIRED BEFORE ANY OTHER WORK

1. Read Gemfile.lock to find exact current Rails version (e.g., 3.2.19)
2. Compare against latest patch for that series:
   - EOL series (≤ 6.1): use static table in reference/multi-hop-strategy.md
   - Active series (≥ 7.0): query RubyGems API (see reference/multi-hop-strategy.md for commands)
3. If current version < latest patch:
   - INFORM user: "Your app is on Rails X.Y.Z but the latest patch is X.Y.W"
   - Guide through Gemfile update and bundle update rails
   - Run test suite after patch upgrade
   - Deploy patch upgrade before proceeding
   - Do NOT proceed to next minor/major until on latest patch
4. If current version == latest patch:
   - Proceed to Step 1
⚠️  本步骤是所有其他工作的前置必要步骤

1. 读取Gemfile.lock获取当前准确的Rails版本（例如3.2.19）
2. 与当前系列的最新补丁版本对比：
   - 已停止维护的系列（≤ 6.1）：使用reference/multi-hop-strategy.md中的静态对照表
   - 仍在维护的系列（≥ 7.0）：查询RubyGems API（命令参考reference/multi-hop-strategy.md）
3. 如果当前版本 < 最新补丁版本：
   - 告知用户：「您的应用当前运行在Rails X.Y.Z版本，最新补丁版本为X.Y.W」
   - 引导用户更新Gemfile并运行bundle update rails
   - 补丁升级后运行测试套件
   - 补丁版本部署后再继续升级流程
   - 未升级到最新补丁版本前不要进行次版本/主版本升级
4. 如果当前版本 == 最新补丁版本：
   - 进入第1步

Step 1: Run Test Suite (MANDATORY FIRST STEP)

第1步：运行测试套件（强制第一步）

⚠️  THIS STEP IS REQUIRED BEFORE ANY OTHER WORK

1. Read: workflows/test-suite-verification-workflow.md
2. Detect test framework (RSpec, Minitest, or both)
3. Run test suite with: bundle exec rspec OR bundle exec rails test
4. Capture results: total tests, passing, failing, pending
5. If ANY tests fail:
   - STOP the upgrade process
   - Report failing tests to user
   - Offer to help fix failing tests
   - Do NOT proceed until all tests pass
6. If all tests pass:
   - Record baseline metrics (test count, coverage if available)
   - Proceed to Step 2
⚠️  本步骤是所有其他工作的前置必要步骤

1. 读取：workflows/test-suite-verification-workflow.md
2. 检测测试框架（RSpec、Minitest或两者都有）
3. 运行测试套件：bundle exec rspec 或者 bundle exec rails test
4. 捕获结果：总测试数、通过数、失败数、 pending数
5. 如果有任何测试失败：
   - 暂停升级流程
   - 向用户报告失败的测试
   - 主动提供协助修复测试的支持
   - 所有测试通过前不要继续升级流程
6. 如果所有测试通过：
   - 记录基准指标（测试数、覆盖率（如果有））
   - 进入第2步

Step 2: Detect Current Version & Verify load_defaults (BLOCKING STEP)

第2步：检测当前版本并验证load_defaults（阻塞步骤）

⚠️  THIS STEP MAY BLOCK THE UPGRADE

1. Read Gemfile to find current Rails gem version
2. Read config/application.rb for load_defaults version
3. Compare rails_gem_version with load_defaults_version
4. If load_defaults_version < rails_gem_version:
   - DELEGATE to the rails-load-defaults skill for incremental update
   - That skill walks through each config change one at a time, grouped by risk tier
   - Tests are re-run between each change
   - Do NOT proceed until load_defaults matches the current Rails version
5. If load_defaults_version == rails_gem_version:
   - Proceed to Step 3
⚠️  本步骤可能会阻塞升级流程

1. 读取Gemfile获取当前Rails gem版本
2. 读取config/application.rb获取load_defaults版本
3. 对比rails_gem_version和load_defaults_version
4. 如果load_defaults_version < rails_gem_version：
   - 委托给rails-load-defaults技能进行增量更新
   - 该技能会按风险等级分组，逐个处理配置变更
   - 每次变更后都会重新运行测试
   - load_defaults匹配当前Rails版本前不要继续升级流程
5. 如果load_defaults_version == rails_gem_version：
   - 进入第3步

Step 3: Set Up Dual-Boot with next_rails (IF NOT ALREADY SET UP)

第3步：使用next_rails搭建双启动环境（如果还未搭建）

DELEGATE to the dual-boot skill for setup and initialization.
That skill handles:
- Checking if Gemfile.next already exists (to avoid duplicate next? method)
- Adding next_rails gem and running next_rails --init
- Installing dependencies for both Rails versions
- Configuring the Gemfile with if next? conditionals
委托给dual-boot技能进行配置和初始化。
该技能会处理：
- 检查Gemfile.next是否已经存在（避免重复的next?方法）
- 添加next_rails gem并运行next_rails --init
- 安装两个Rails版本的依赖
- 使用if next?条件配置Gemfile

Step 4: Validate Upgrade Path

第4步：验证升级路径

1. Check if upgrade is single-hop or multi-hop
2. If multi-hop, explain sequential requirement
3. Plan individual hops
1. 检查是单跳升级还是多跳升级
2. 如果是多跳升级，告知用户必须顺序升级的要求
3. 规划单独的升级步骤

Step 5: Run Breaking Changes Detection (DIRECT)

第5步：运行破坏性变更检测（直接执行）

Claude runs detection directly using tools - NO script generation needed

1. Read: workflows/direct-detection-workflow.md
2. Read: detection-scripts/patterns/rails-{VERSION}-patterns.yml
3. For each pattern in the patterns file:
   - Use Grep tool to search for the pattern
   - Collect file paths and line numbers
   - Store findings with context
4. Read: version-guides/upgrade-{FROM}-to-{TO}.md for context
5. Compile all findings into structured data
Claude直接使用工具运行检测 - 无需生成脚本

1. 读取：workflows/direct-detection-workflow.md
2. 读取：detection-scripts/patterns/rails-{VERSION}-patterns.yml
3. 遍历模式文件中的每个模式：
   - 使用Grep工具搜索匹配模式
   - 收集文件路径和行号
   - 存储检测结果和上下文
4. 读取：version-guides/upgrade-{FROM}-to-{TO}.md获取上下文
5. 将所有检测结果整理为结构化数据

Step 6: Load Report Resources & Generate Reports

第6步：加载报告资源并生成报告

1. Read: templates/upgrade-report-template.md
2. Read: templates/app-update-preview-template.md
3. Read: workflows/upgrade-report-workflow.md
4. Read: workflows/app-update-preview-workflow.md
Deliverable #1: Comprehensive Upgrade Report
  • Input: Direct detection findings + version guide data
  • Output: Report with real code examples from user's project
Deliverable #2: app:update Preview
  • Input: Actual config files + findings
  • Output: Preview with real file paths and changes
1. 读取：templates/upgrade-report-template.md
2. 读取：templates/app-update-preview-template.md
3. 读取：workflows/upgrade-report-workflow.md
4. 读取：workflows/app-update-preview-workflow.md
交付物1：全面升级报告
  • 输入： 直接检测结果 + 版本指南数据
  • 输出： 包含用户项目真实代码示例的报告
交付物2：app:update预览
  • 输入： 实际配置文件 + 检测结果
  • 输出： 包含真实文件路径和变更的预览

Step 7: Present Reports & Offer Help

第7步：展示报告并提供支持

1. Present Comprehensive Upgrade Report first
2. Present app:update Preview Report second
3. Explain next steps
4. Offer to help implement changes
1. 先展示全面升级报告
2. 再展示app:update预览报告
3. 说明后续步骤
4. 主动提供协助实现变更的支持

Pre-Upgrade Checklist (FastRuby.io Best Practices)

前置检查清单（FastRuby.io最佳实践）

Before starting ANY upgrade:
开始任何升级前：

1. Test Coverage Assessment (AUTOMATED - Step 1 of Workflow)

1. 测试覆盖率评估（自动执行 - 工作流第1步）

  • Run test suite - all tests passing? ← Claude runs this automatically
  • Check test coverage (aim for >70%) ← Claude captures this if SimpleCov is configured
  • Review critical paths have coverage
Note: This step is now automated. Claude will run the test suite and BLOCK the upgrade if any tests fail.
  • 运行测试套件 - 所有测试是否通过？ ← Claude自动运行
  • 检查测试覆盖率（目标>70%） ← 如果配置了SimpleCov，Claude会自动捕获
  • 确认核心路径有测试覆盖
注意： 本步骤已自动化。Claude会运行测试套件，如果有测试失败会阻塞升级流程。

2. Dependency Audit

2. 依赖审计

  • Run 
    bundle outdated
  • Check gem compatibility with target Rails version
  • Identify gems that need upgrading first
  • 运行
    bundle outdated
  • 检查gem与目标Rails版本的兼容性
  • 识别需要优先升级的gem

3. Database Backup

3. 数据库备份

  • Backup production database
  • Backup development/staging databases
  • Verify backup restore process works
  • 备份生产数据库
  • 备份开发/测试环境数据库
  • 验证备份恢复流程可用

4. Git Branch Strategy

4. Git分支策略

  • Create upgrade branch from main/master
  • Set up CI for upgrade branch
  • Plan merge strategy
  • 从main/master分支创建升级分支
  • 为升级分支配置CI
  • 规划合并策略

5. Deprecation Warnings

5. 弃用警告处理

  • Run app with 
    RAILS_DEPRECATION_WARNINGS=1
  • Address existing deprecation warnings
  • Enable verbose deprecations in test environment
  • 使用
    RAILS_DEPRECATION_WARNINGS=1
    运行应用
  • 处理现有弃用警告
  • 在测试环境开启详细弃用提醒

Common Request Patterns

常见请求模式

Pattern 1: Full Upgrade Request

模式1：全量升级请求

User says: "Upgrade my Rails app to 8.1"
Action - Step 0 (MANDATORY: Verify Latest Patch):
  1. Read 
    Gemfile.lock
    for exact Rails version
  2. Compare against latest patch for that series (see 
    reference/multi-hop-strategy.md
    )
  3. If not on latest patch → Guide user through patch upgrade first
  4. If on latest patch → Proceed to Step 1
Action - Step 1 (MANDATORY: Verify Tests Pass):
  1. Load: 
    workflows/test-suite-verification-workflow.md
  2. Detect test framework (RSpec or Minitest)
  3. Run test suite: 
    bundle exec rspec
    or 
    bundle exec rails test
  4. If tests FAIL → STOP and help fix tests first
  5. If tests PASS → Record baseline and proceed
Action - Step 2 (MANDATORY: Verify load_defaults):
  1. Read Gemfile.lock for current Rails gem version
  2. Read config/application.rb for load_defaults version
  3. If load_defaults < Rails gem version:
    • INFORM user: "Your app uses Rails X.Y but load_defaults is set to X.Z"
    • DELEGATE to the 
      rails-load-defaults
      skill for incremental, tiered update
    • That skill handles per-config analysis, test runs, and risk assessment
  4. If load_defaults matches → Proceed to Step 3
Action - Step 3 (Run Detection Directly):
  1. Validate upgrade path
  2. Load: 
    workflows/direct-detection-workflow.md
  3. Load: 
    detection-scripts/patterns/rails-{VERSION}-patterns.yml
  4. Use Grep/Glob/Read tools to search for each pattern
  5. Collect findings with file:line references
Action - Step 4 (Generate Reports):
  1. Load: 
    workflows/upgrade-report-workflow.md
  2. Load: 
    workflows/app-update-preview-workflow.md
  3. Generate Comprehensive Upgrade Report (using direct findings)
  4. Generate app:update Preview (using actual config files)
  5. Present both reports to user
  6. Offer to help implement changes
用户说： "Upgrade my Rails app to 8.1" / 「将我的Rails应用升级到8.1」
操作 - 第0步（强制：验证最新补丁版本）：
  1. 读取
    Gemfile.lock
    获取准确的Rails版本
  2. 与当前系列的最新补丁版本对比（见
    reference/multi-hop-strategy.md
    ）
  3. 如果未运行最新补丁版本 → 先引导用户完成补丁版本升级
  4. 如果已经运行最新补丁版本 → 进入第1步
操作 - 第1步（强制：验证测试通过）：
  1. 加载：
    workflows/test-suite-verification-workflow.md
  2. 检测测试框架（RSpec或Minitest）
  3. 运行测试套件：
    bundle exec rspec
    或
    bundle exec rails test
  4. 如果测试失败 → 暂停升级，先协助修复测试
  5. 如果测试通过 → 记录基准数据，继续下一步
操作 - 第2步（强制：验证load_defaults）：
  1. 读取
    Gemfile.lock
    获取当前Rails gem版本
  2. 读取config/application.rb获取load_defaults版本
  3. 如果load_defaults < Rails gem版本：
    • 告知用户：「您的应用使用Rails X.Y版本，但load_defaults配置为X.Z」
    • 委托给
      rails-load-defaults
      技能进行增量分级更新
    • 该技能会处理逐配置分析、测试运行和风险评估
  4. 如果load_defaults匹配 → 进入第3步
操作 - 第3步（直接运行检测）：
  1. 验证升级路径
  2. 加载：
    workflows/direct-detection-workflow.md
  3. 加载：
    detection-scripts/patterns/rails-{VERSION}-patterns.yml
  4. 使用Grep/Glob/读取工具搜索每个匹配模式
  5. 收集检测结果和「文件:行号」引用
操作 - 第4步（生成报告）：
  1. 加载：
    workflows/upgrade-report-workflow.md
  2. 加载：
    workflows/app-update-preview-workflow.md
  3. 生成全面升级报告（使用直接检测结果）
  4. 生成app:update预览（使用实际配置文件）
  5. 向用户展示两份报告
  6. 主动提供协助实现变更的支持

Pattern 2: Multi-Hop Request

模式2：多跳升级请求

User says: "Help me upgrade from Rails 5.2 to 8.1"
Action - Step 0 (MANDATORY: Verify Latest Patch):
  1. Check exact current version from 
    Gemfile.lock
  2. If not on latest patch of current series → Upgrade to latest patch first
  3. For multi-hop: This check applies at the START and again after each hop
Action - Step 1 (MANDATORY: Verify Tests Pass):
  1. Run test suite BEFORE planning any upgrade work
  2. If tests fail → STOP and fix first
  3. If tests pass → Proceed with planning
Action - Step 2 (MANDATORY: Verify load_defaults):
  1. Check if load_defaults matches current Rails version
  2. If mismatched → Recommend updating load_defaults FIRST
  3. For multi-hop: Ensure load_defaults is current before starting
Action - Step 3 (Plan & Execute):
  1. Explain sequential requirement
  2. Calculate hops: 5.2 → 6.0 → 6.1 → 7.0 → 7.1 → 7.2 → 8.0 → 8.1
  3. Reference: 
    reference/multi-hop-strategy.md
  4. Follow Pattern 1 for FIRST hop (5.2 → 6.0)
  5. After first hop complete, repeat for next hops
  6. IMPORTANT: After each hop, ensure load_defaults is updated before next hop
用户说： "Help me upgrade from Rails 5.2 to 8.1" / 「帮我把Rails从5.2升级到8.1」
操作 - 第0步（强制：验证最新补丁版本）：
  1. 从
    Gemfile.lock
    获取当前准确版本
  2. 如果未运行当前系列的最新补丁版本 → 先升级到最新补丁版本
  3. 多跳升级场景：本检查在升级开始时和每个升级步骤完成后都需要执行
操作 - 第1步（强制：验证测试通过）：
  1. 规划任何升级工作前先运行测试套件
  2. 如果测试失败 → 暂停升级，先修复测试
  3. 如果测试通过 → 进入规划阶段
操作 - 第2步（强制：验证load_defaults）：
  1. 检查load_defaults是否与当前Rails版本匹配
  2. 如果不匹配 → 建议优先更新load_defaults
  3. 多跳升级场景：开始升级前确保load_defaults是当前版本
操作 - 第3步（规划与执行）：
  1. 告知用户必须顺序升级的要求
  2. 计算升级步骤：5.2 → 6.0 → 6.1 → 7.0 → 7.1 → 7.2 → 8.0 → 8.1
  3. 参考：
    reference/multi-hop-strategy.md
  4. 按照模式1处理第一步升级（5.2 → 6.0）
  5. 第一步升级完成后，重复流程处理后续步骤
  6. 重要提醒： 每个步骤完成后，进入下一个步骤前必须更新load_defaults

Pattern 3: Breaking Changes Analysis Only

模式3：仅破坏性变更分析

User says: "What breaking changes affect my app for Rails 8.0?"
Action - Step 0 (MANDATORY: Verify Latest Patch):
  1. Check if on latest patch — warn if not, recommend patching first
Action - Step 1 (MANDATORY: Verify Tests Pass):
  1. Run test suite first
  2. If tests fail → Warn user and recommend fixing first
  3. If tests pass → Proceed with analysis
Action - Step 2 (MANDATORY: Verify load_defaults):
  1. Check load_defaults alignment
  2. If mismatched → Recommend updating first
Action - Step 3 (Run Detection):
  1. Load: 
    workflows/direct-detection-workflow.md
  2. Run detection directly using tools
  3. Present findings summary
  4. Offer to generate full upgrade report
用户说： "What breaking changes affect my app for Rails 8.0?" / 「Rails 8.0有哪些会影响我的应用的破坏性变更？」
操作 - 第0步（强制：验证最新补丁版本）：
  1. 检查是否运行最新补丁版本 — 如果没有发出警告，建议先升级补丁版本
操作 - 第1步（强制：验证测试通过）：
  1. 先运行测试套件
  2. 如果测试失败 → 向用户发出警告，建议先修复测试
  3. 如果测试通过 → 进入分析阶段
操作 - 第2步（强制：验证load_defaults）：
  1. 检查load_defaults是否匹配
  2. 如果不匹配 → 建议优先更新
操作 - 第3步（运行检测）：
  1. 加载：
    workflows/direct-detection-workflow.md
  2. 使用工具直接运行检测
  3. 展示检测结果摘要
  4. 主动提供生成完整升级报告的支持

Quality Checklist

质量检查清单

Before delivering, verify:
For Direct Detection:
  • All patterns from version-specific YAML file checked
  • Grep/Glob tools used correctly for each pattern
  • File:line references collected for all findings
  • Context captured for each finding
For Comprehensive Upgrade Report:
  • All {PLACEHOLDERS} replaced with actual values
  • Used ACTUAL findings from direct detection (not generic examples)
  • Breaking changes section includes real file:line references
  • Custom code warnings based on actual detected issues
  • Code examples use user's actual code from affected files
  • Next steps clearly outlined
For app:update Preview:
  • All {PLACEHOLDERS} replaced with actual values
  • File list matches user's actual config files
  • Diffs based on real current config vs target version
  • Next steps clearly outlined
交付前验证：
直接检测相关：
  • 版本专属YAML文件中的所有模式都已检查
  • 每个模式都正确使用了Grep/Glob工具
  • 所有检测结果都收集了「文件:行号」引用
  • 每个检测结果都捕获了上下文
全面升级报告相关：
  • 所有{占位符}都已替换为实际值
  • 使用了直接检测的真实结果（不是通用示例）
  • 破坏性变更部分包含真实的「文件:行号」引用
  • 自定义代码警告基于实际检测到的问题
  • 代码示例使用了用户受影响文件中的真实代码
  • 后续步骤清晰明确
app:update预览相关：
  • 所有{占位符}都已替换为实际值
  • 文件列表与用户的实际配置文件匹配
  • 差异基于真实的当前配置与目标版本对比
  • 后续步骤清晰明确

Key Principles

核心原则

  1. ALWAYS Verify Latest Patch First (MANDATORY - ensure app is on latest patch of current series before any version hop)
  2. ALWAYS Run Test Suite (MANDATORY - no exceptions, no upgrade work until tests pass)
  3. Block on Failing Tests (if tests fail, STOP and help fix them before any upgrade work)
  4. ALWAYS Verify load_defaults (MANDATORY - check if load_defaults matches current Rails version)
  5. Recommend Updating load_defaults First (if behind current Rails, update load_defaults BEFORE upgrading to next version)
  6. Run Detection Directly (use Grep/Glob/Read tools - no script generation needed)
  7. Always Use Actual Findings (no generic examples in reports)
  8. Always Flag Custom Code (with ⚠️ warnings based on detected issues)
  9. Always Use Templates (for consistency)
  10. Always Check Quality (before delivery)
  11. Load Workflows as Needed (don't hold everything in memory)
  12. Sequential Process is Critical (patch check → tests → load_defaults check → detection → reports)
  13. Follow FastRuby.io Methodology (incremental upgrades, assessment first)
  14. Always Use 
    NextRails.next?
    for Dual-Boot Code     (NEVER use 
    respond_to?
    for version branching. DELEGATE to the 
    dual-boot
    skill for patterns and setup.)
  1. 始终优先验证最新补丁版本（强制要求 - 任何版本升级前确保应用运行在当前系列的最新补丁版本）
  2. 始终运行测试套件（强制要求 - 无例外，测试通过前不进行任何升级工作）
  3. 测试失败时阻塞流程（如果测试失败，暂停升级先协助修复问题）
  4. 始终验证load_defaults（强制要求 - 检查load_defaults是否与当前Rails版本匹配）
  5. 建议优先更新load_defaults（如果落后于当前Rails版本，升级到下一个版本前先更新load_defaults）
  6. 直接运行检测（使用Grep/Glob/读取工具 - 无需生成脚本）
  7. 始终使用真实检测结果（报告中不使用通用示例）
  8. 始终标记自定义代码（基于检测到的问题添加⚠️警告）
  9. 始终使用模板（保证一致性）
  10. 交付前始终检查质量
  11. 按需加载工作流（不需要将所有内容都保存在内存中）
  12. 顺序流程至关重要（补丁检查 → 测试 → load_defaults检查 → 检测 → 报告）
  13. 遵循FastRuby.io方法论（增量升级、评估优先）
  14. 双启动代码始终使用
    NextRails.next?
    （禁止使用
    respond_to?
    做版本分支。模式和配置请委托给
    dual-boot
    技能处理。）

Success Criteria

成功标准

A successful upgrade assistance session:
✅ Verified latest patch version (Step 0 - MANDATORY) ✅ Upgraded to latest patch if needed (before any minor/major hop) ✅ Ran test suite (Step 1 - MANDATORY) ✅ Verified all tests pass (blocked if tests failed) ✅ Recorded baseline metrics (test count, coverage) ✅ Checked load_defaults alignment (Step 2 - MANDATORY) ✅ Recommended load_defaults update if behind (asked user before proceeding) ✅ Updated load_defaults if user agreed (re-ran tests after update) ✅ Ran detection directly (using Grep/Glob/Read tools - no script) ✅ Generated Comprehensive Upgrade Report using actual findings ✅ Generated app:update Preview using actual config files ✅ Used user's actual code from findings (not generic examples) ✅ Flagged all custom code with ⚠️ warnings based on detected issues ✅ Provided clear next steps ✅ Offered to help implement changes
See CHANGELOG.md for version history and current version.
成功的升级协助会话需要满足：
✅ 验证了最新补丁版本（第0步 - 强制要求） ✅ 如果需要已升级到最新补丁版本（任何次版本/主版本升级前） ✅ 运行了测试套件（第1步 - 强制要求） ✅ 验证所有测试通过（测试失败时阻塞流程） ✅ 记录了基准指标（测试数、覆盖率） ✅ 检查了load_defaults匹配情况（第2步 - 强制要求） ✅ 如果load_defaults落后已建议更新（继续流程前征求用户同意） ✅ 如果用户同意已更新load_defaults（更新后重新运行测试） ✅ 直接运行了检测（使用Grep/Glob/读取工具 - 无脚本） ✅ 使用真实检测结果生成了全面升级报告 ✅ 使用真实配置文件生成了app:update预览 ✅ 使用了检测到的用户真实代码（不是通用示例） ✅ 基于检测到的问题为所有自定义代码添加了⚠️警告 ✅ 提供了清晰的后续步骤 ✅ 主动提供了协助实现变更的支持
版本历史和当前版本请查看CHANGELOG.md。