review-engine

Review Engine

在审查现有 Rails 引擎或提出改进建议时使用此技能。

快速参考

审查领域	关键检查项
命名空间	使用了 isolate_namespace；边界清晰；不会泄漏宿主常量
宿主集成	配置接口、适配器；不直接访问宿主模型
初始化	加载时无副作用；在 config.to_prepare 中使用可安全重载的钩子
迁移	有文档说明，通过生成器复制；没有隐式或破坏性步骤
Dummy 应用	存在于 spec/ 中；用于集成测试；会测试实际挂载和配置

硬性门槛

Before writing findings, confirm every row in the Quick Reference table has been addressed:
- [ ] Namespace isolation verified
- [ ] Host integration points checked
- [ ] `engine.rb` initializer blocks inspected
- [ ] Migration/generator flow confirmed
- [ ] Dummy app presence and usage confirmed
- [ ] Integration tests exercise real mount

If any box cannot be checked (e.g., file not provided), record it as an open assumption.

核心流程

1. 识别引擎类型和用途。 阅读 lib/<engine_name>/engine.rb 和 lib/<engine_name>/railtie.rb。确认引擎是隔离式还是普通式。
2. 检查命名空间和公共 API 范围。 检查是否使用了 isolate_namespace，以及是否存在未限定的顶层常量引用。
3. 检查与宿主应用的集成点。 标记直接引用宿主常量的情况。确认宿主依赖通过配置接口传递。
4. 检查初始化和重载行为。 检查 initializer、config.to_prepare 和 ActiveSupport.on_load。标记在 require 时、初始化代码块之外修改全局状态的行为。
5. 检查迁移、生成器和安装流程。 确认迁移通过生成器复制。检查是否存在破坏性或不可逆迁移。
6. 检查 dummy 应用和集成测试。 确认存在 spec/dummy/，且会测试挂载点。
7. 按严重程度总结发现。 优先列出高严重程度的问题。架构问题之前不要列出低严重程度的问题。

高严重程度问题示例（引擎访问宿主应用内部）：

# Bad: engine assumes host model
class MyEngine::SomeService
  def call
    User.find(current_user_id)  # User is host app; engine is coupled
  end
end

修复方法：引入配置（MyEngine.config.user_finder = ->(id) { User.find(id) }）并使用该配置。

良好示例（配置接口）：

# Good: engine uses configured dependency
class MyEngine::SomeService
  def call
    MyEngine.config.user_finder.call(current_user_id)
  end
end

不良示例（在 require 时打补丁——无法安全重载）：

# Bad: patches at require time — double-includes on code reload
ActionController::Base.include(MyEngine::ControllerHelpers)

良好示例（通过 ActiveSupport.on_load 延迟加载）：

# Good: patches only when the framework component is ready, reload-safe
ActiveSupport.on_load(:action_controller) do
  include MyEngine::ControllerHelpers
end

输出格式

要求审查引擎时，你的输出文件 answer.md 必须符合以下要求：

1. 先列出发现： 在具体产物 answer.md 中，将发现部分（按 HIGH -> MEDIUM -> LOW 排序）作为第一个部分（如果要求提供计划，则紧跟简短计划之后）。每项发现都应包含严重程度、受影响的文件/区域、风险和可信的最小修复方案。
2. 验证命令： 包含使用过的验证命令，包括用于检查命名空间隔离的 grep -r "isolate_namespace" lib/、用于检查破坏性或不可逆更改的迁移审计命令（例如 grep -R "remove_column\|drop_table\|change_column" db/migrate lib/**/db/migrate），以及用于验证初始化重载安全性的 grep -r "ActiveSupport.on_load" lib/ 或 grep -r "initializer" lib/。
3. 包含尚未确认的假设和建议的后续更改。
4. 如果没有实质性发现，请明确说明，并提及仍存在的测试覆盖缺口。
5. 语言——除非用户明确要求其他语言，否则必须使用英语。

集成

技能	何时串联
create-engine	实施建议的修复或重构引擎时
test-engine	添加缺失的 dummy 应用或集成测试覆盖时
upgrade-engine	评估 Rails/Ruby 版本支持或弃用影响时

扩展参考

补充细节——完成核心流程后再查阅。

严重性级别

• 高 — 导致生产故障或破坏宿主集成（例如，直接耦合宿主常量、不安全的启动时副作用、没有 down 方法的不可逆迁移）。
• 中 — 降低可维护性，或使引擎在不同宿主应用中变得脆弱（例如，未记录的配置接缝、缺少安装生成器、没有虚拟应用）。
• 低 — 风格或轻微的清晰度问题；不要在架构问题之前提出。

常见错误

• 在架构审查之前先审查代码风格。
• 漏掉虚拟应用覆盖检查（虚拟应用必须存在并且实际使用）。
• 忽略 engine.rb（它通常包含启动时副作用）。

扩展资源（渐进式披露）

仅在需要相关内容时加载这些文件：

• FINDINGS.md — 需要示例审查发现格式和严重性分类示例时使用
• assets/examples.md — 需要完整的引擎审查示例及其发现和建议时使用
• assets/finding-schema.json — 需要引擎审查发现输出的结构化架构时使用