review-architecture

レビューアーキテクチャ

クイックリファレンス

領域	チェックすべきこと
コントローラー	調整のみ — ドメインロジックを含めない
モデル	永続化 + 凝集度の高いドメインルールを担い、オーケストレーションは行わない
サービス	本当の境界を作る — 単にコードを移動させただけにしない
コールバック	小さく予想外のことがない — 隠れたビジネスロジックを含めない
Concern	1 つの Concern につき 1 つの凝集した責務
外部連携	専用の協調オブジェクトの背後に置く

HARD-GATE (Authoritative Verification Rule)

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、ヘルパー、プレゼンターを読みます: 1 つの凝集したことを行っているか、それとも監査 + 通知 + メール + 外部 API 呼び出しを混在させているか? 混在した Concern は、影響範囲に応じて High または Medium の重大度になります。1 つのクラスだけが使用している Concern は削除候補として扱い、代わりにインライン化します。
6. 抽象化が設計を明確にしているか、それとも単にコードを移動させているだけかを確認します。
7. 上記の HARD-GATE に従って、各 High 重大度の指摘を検証します — 実際の構造的問題を確認し、見つかった資格情報のような値は伏せ字にします。

重大度レベル

High 重大度の指摘

• コールバックや広範な Concern に隠されたビジネスロジック
• コントローラーが多段階のドメインワークフローをインラインでオーケストレーションしている
• モデルが HTTP、ジョブ、メーラー、外部 API に直接結合している
• 明確な責務なしに間接層を追加するだけの抽象化
• コードの変更を困難にする、レイヤーを越えた定数への到達

Medium 重大度の指摘

• コントローラーやジョブ間で重複したワークフローロジック
• 過剰なクエリやポリシーロジックを抱えるスコープやクラスメソッド
• ドメインの振る舞いが漏れ出しているヘルパーやプレゼンター
• 些細な一行をラップしただけのサービスオブジェクト
• 無関係な責務を組み合わせた Concern — アプリ内のすべての Concern を確認してください

出力スタイル

1. スコープ: タスクがスタイルレビューではなくアーキテクチャ/構造レビューであることを述べ、検査した Rails のエントリーポイントを特定します。
2. 順序: エントリーポイントから始めます。次に、レビュー領域ごとに並べた指摘を書きます。
3. 境界優先の視点: ドメインロジックがどこに存在するか、フローが明示的か、抽象化が設計を明確にしているか、それとも単にコードを移動させているだけかを優先します。
4. 指摘の構造: すべての指摘は 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 レビューの場合

拡張リソース (Progressive Disclosure)

これらのファイルは、その特定の内容が必要な場合にのみ読み込んでください:

• assets/examples.md — 指摘と推奨事項を含む完全なアーキテクチャレビューの例が必要な場合に使用します
• assets/findings_schema.json — アーキテクチャレビューの指摘出力のための構造化 JSON スキーマが必要な場合に使用します