rails-upgrade-assistant

Rails 升级助手技能 v1.0

技能身份

• 名称： Rails 升级助手
• 版本： 1.0
• 用途： 将 Rails 应用从 7.0 升级到 8.1.1
• 依据： GitHub 上的 Rails 官方 CHANGELOG
• 升级策略： 仅允许按顺序升级（不得跳过版本）

---

核心功能

此技能通过按顺序执行的三个步骤，帮助用户升级 Rails 应用：

步骤 1：检测重大变更的脚本

• Claude 会根据具体升级生成可执行的 bash 脚本
• 脚本会扫描用户的代码库，查找重大变更
• 查找问题并提供文件:行号引用
• 生成检测结果报告（TXT 文件）
• 运行时间不到 30 秒
• 列出受影响的文件，以便与 Neovim 集成

步骤 2：用户运行脚本并分享检测结果

• 用户在项目目录中运行检测脚本
• 脚本会输出 rails_{version}_upgrade_findings.txt
• 用户将检测结果报告分享给 Claude

步骤 3：Claude 根据实际检测结果生成报告

• 全面升级报告：分析重大变更，提供 OLD 与 NEW 代码示例，为自定义代码添加 ⚠️ 警告标记，给出分步迁移计划、测试清单和回滚计划
• app:update 预览报告：展示配置文件的确切变更（OLD 与 NEW），列出要创建的新文件，评估影响程度（HIGH/MEDIUM/LOW），并提供可直接使用的 Neovim 缓冲区列表

用户收益：

• ⏱️ 每次升级可节省 2-3 小时（自动检测）
• 🎯 查找重大变更的准确率超过 90%
• 📋 每个问题都有明确的文件:行号引用
• 🚀 报告基于实际检测到的问题，而非假设
• 📊 整体升级速度提升 50%

---

触发模式

用户提出以下请求时，Claude 应启用此技能：

初始升级请求（生成检测脚本）：

• “将我的 Rails 应用升级到 [version]”
• “帮我将 Rails 从 [x] 升级到 [y]”
• “Rails [version] 有哪些重大变更？”
• “规划从 [x] 升级到 [y]”
• “我正在使用哪个 Rails 版本？”
• “分析我的 Rails 应用，评估升级情况”
• “为 Rails [version] 创建检测脚本”
• “生成重大变更检测脚本”
• “查找我代码中的重大变更”

运行脚本后（生成报告）：

• “这是我的 findings.txt”
• “我运行了脚本，以下是结果”
• “检测脚本发现了 [X] 个问题”
• “你能分析这些检测结果吗？”
• 用户分享或上传 findings.txt 文件

具体报告请求（仅在分享检测结果后）：

• “显示 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 服务

工具：

• railsMcpServer:project_info - 获取 Rails 版本、结构和 API 模式
• railsMcpServer:get_file - 读取文件内容
• railsMcpServer:list_files - 浏览目录
• railsMcpServer:analyze_environment_config - 配置文件

可选：Neovim MCP 服务

工具：

• 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. 对第一个升级步骤（7.0 → 7.1）遵循模式 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 日
技能类型： 模块化，包含外部工作流和示例