rails-upgrade

Rails 升级助手技能

技能身份

• 名称： Rails Upgrade Assistant
• 用途： 将 Rails 应用智能升级至 2.3 到 8.1
• 技能类型： 模块化，包含外部工作流和示例
• 升级策略： 仅逐步升级（不得跳过版本）
• 方法论： 基于 FastRuby.io 升级最佳实践和电子书《The Complete Guide to Upgrade Rails》
• 出处： 内容基于 FastRuby.io（OmbuLabs）的《The Complete Guide to Upgrade Rails》

---

术语

术语	含义	位置
工作流	升级流程中一个带编号的单元，对应一个文件	workflows/<NN>-<name>-workflow.md
步骤	工作流文件中的 Step N 标题	工作流内部
参考资料	按需加载的材料：查找表、操作手册、条件分支	references/<name>-reference.md

没有子步骤：“Step 4.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）——以分级风险评估（Tier 1：低风险，Tier 2：需要对代码库执行 grep，Tier 3：需要人工审核）处理增量 load_defaults 更新。在 Rails 版本升级完成后作为最后一步使用。

---

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

此技能遵循经验证的 FastRuby.io 升级方法论：

1. 增量升级 - 始终一次升级一个次要或主要版本
2. 先评估 - 在进行更改前了解范围
3. 双启动测试 - 过渡期间使用 next_rails gem 测试两个版本
4. 测试覆盖率 - 升级前确保测试覆盖率充足（目标为 80% 以上）
5. Gem 兼容性 - 每一步都使用 RailsBump 检查 gem 兼容性
6. 弃用警告 - 升级前处理弃用项
7. 向后兼容的更改 - 在提升版本号之前，将小规模更改部署到生产环境

关键资源：

• 双启动设置请委托给 dual-boot 技能（参见依赖项）
• 弃用项的处理方式参见 references/deprecation-warnings-reference.md
• 长期维护升级参见 references/staying-current-reference.md

---

关键：使用 NextRails.next? 的双启动代码模式

提出必须同时适用于当前和目标 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、枚举）
• 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（加密的 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（水平分片）
• 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 - 单步升级示例
• examples/multi-hop-upgrade.md - 多步升级示例

外部依赖

• dual-boot skill - 使用 next_rails 设置和管理双启动（Workflow 04）（https://github.com/ombulabs/claude-code_dual-boot-skill）
• rails-load-defaults skill - 逐步对齐 load_defaults（Workflow 12）（https://github.com/ombulabs/claude-code_rails-load-defaults-skill）
• upgrade-cleanup companion plugin - 由用户触发。移除双启动脚手架，并删除 NextRails.next? / NextRails.current? 分支。弃用项分流仍由此 skill 负责，供下一步升级使用。

参考资料

• references/sequential-strategy-reference.md - 顺序升级规则（不可跳过版本）以及受支持升级路径的表格。在 Workflow 03 中加载。
• references/request-patterns-reference.md - 每种请求形式（完整升级、多步升级、仅分析、仅报告）对应运行哪些工作流。在会话开始时阅读。
• references/next-hop-readiness-reference.md - 只读解答“升级到下一个 Rails 版本需要做什么？”。针对 Next-Hop Readiness 请求形式加载。
• references/no-test-suite-smoke-reference.md - 当不存在可运行的 RSpec/Minitest 测试套件时，从 Workflow 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 更新顺序以及“无兼容版本”应对方案（fork / vendor / replace）。仅当 Workflow 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 - 对应用运行某一步升级所需的所有模式，并打印发现项表格。在 Workflow 05 中运行此脚本，而不是针对每个模式分别运行一次 Grep。
• detection-scripts/gem_limits.rb - 仅根据 lockfile 列出 gemspec 排除了目标 Rails 的已锁定 Gem。在 Workflow 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	提前设置。委托给 External Dependencies 下列出的技能	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 方法（渐进式升级，先进行评估）

此前列在这里的其他内容都已移至其对应的工作流中：请参阅各工作流的“用途”和“关卡”。