review-architecture

架构审查

快速参考

领域	检查内容
控制器	仅负责协调——不含领域逻辑
模型	负责持久化 + 内聚的领域规则，而非编排
服务	创建真正的边界，而不仅仅是搬移代码
回调	小而明确——无隐藏的业务逻辑
Concern	每个 concern 只承担一项内聚的能力
外部集成	置于专用的协作者之后

HARD-GATE（权威验证规则）

DO NOT list findings that do not survive code-level confirmation.
Verify each High-severity finding by reading the actual code to confirm it is a real structural problem.
If verification reveals it is not genuine, downgrade it or remove it entirely.
If no source files were provided or read, do not invent High findings. Return an
architecture review checklist or assumptions block instead, and say code-level
confirmation is required before reporting findings.
SECRET SAFETY: code-level evidence must never reproduce secrets, tokens, API
keys, passwords, private keys, session cookies, or credential values. If a file
contains a hard-coded secret, report only the file/path, symbol name, credential
type, and a redacted fingerprint such as `[REDACTED_API_KEY]`; do not quote the
literal value.

核心流程

当任务是审查或改进 Rails 应用或库的结构时，使用此技能。

核心原则： 优先处理边界问题，而非风格问题。优先选择简单的对象和显式的流程，而非隐藏的行为。

审查顺序

1. 确定主要入口点：控制器、任务、模型、服务。
2. 检查领域逻辑位于何处。
3. 检查模型的职责、回调和关联。
4. 检查控制器的大小和编排。
5. 阅读每一个 concern、helper 和 presenter：它是否只做一件内聚的事，还是混合了审计 + 通知 + 邮件 + 外部 API 调用？混合的 concern 根据影响范围属于 High 或 Medium 严重级别。将任何只被单个类使用的 concern 视为删除候选——改为内联。
6. 检查抽象是澄清了设计，还是仅仅搬移了代码。
7. 根据上述 HARD-GATE 验证每一条 High 严重级别的发现——确认真实的结构性问题，对发现的任何类凭据值进行脱敏。

严重级别

High 严重级别的发现

• 隐藏在回调或宽泛 concern 中的业务逻辑
• 控制器内联编排多步骤领域工作流
• 模型直接耦合到 HTTP、任务、邮件器或外部 API
• 增加了间接性却没有明确职责的抽象
• 跨层常量访问使代码难以变更

Medium 严重级别的发现

• 控制器或任务之间重复的工作流逻辑
• 承载过多查询或策略逻辑的 scope 或类方法
• 泄漏领域行为的 helper 或 presenter
• 包装琐碎单行代码的服务对象
• 组合了不相关职责的 concern——检查应用中的每一个 concern

输出风格

1. 范围：说明该任务是架构/结构审查，而非风格审查，并确定所检查的 Rails 入口点。
2. 顺序：从入口点开始。然后按审查领域顺序撰写发现。
3. 边界优先视角：优先关注领域逻辑位于何处、流程是否显式，以及抽象是澄清了设计还是仅仅搬移了代码。
4. 发现结构：每条发现使用四字段结构：

   **Severity:** High
   **Affected file:** app/controllers/orders_controller.rb — OrdersController#create
   **Risk:** Controller runs a 5-step domain workflow. Partial state on failure; untestable without HTTP.
   **Improvement:** Extract to Orders::CreateOrder.call(params). Controller handles response/redirect only.
   

5. High 严重级别验证：对于每一条 High 发现，说明所读取的具体代码级证据（依据 HARD-GATE）。对任何类似密钥的字面量进行脱敏。绝不要使用代表性文件路径或编造的行号作为证据。
6. 完整性：对于每条发现，包含严重级别、受影响的文件或领域、结构为何有风险，以及最小可信的改进。然后列出未决假设和建议的后续重构步骤。
7. 语言：除非明确要求否则，必须使用英文。

集成

技能	何时串联
code-review	用于较小范围和 PR 审查

扩展资源（渐进式披露）

仅当需要其特定内容时加载这些文件：

• assets/examples.md — 当你需要包含发现和建议的完整架构审查示例时使用
• assets/findings_schema.json — 当你需要架构审查发现输出的结构化 JSON schema 时使用