rails-audit-thoughtbot

Rails 監査スキル（thoughtbot のベストプラクティス）

Service Object より Plain Old Ruby Objects（PORO）を重視し、thoughtbot の Ruby Science と Testing Rails のベストプラクティスに基づいて、Ruby on Rails アプリケーションを包括的に監査します。

監査範囲

監査は次の 2 つのモードで実行できます。

1. アプリケーション全体の監査：Rails アプリケーション全体を分析します
2. 対象を絞った監査：特定のファイルまたはディレクトリを分析します

実行フロー

ステップ 1：監査範囲の決定

ユーザーに尋ねるか、依頼内容から推測します。

• 全体監査：app/、spec/ または test/、config/、db/、lib/ 全体を分析します
• 対象を絞った監査：指定されたパスのみを分析します

ステップ 2：オプションのメトリクスを収集する（SimpleCov + RubyCritic）

一度に選択できるよう、両方の質問をまとめて単一の AskUserQuestion でユーザーに尋ねます。

• 質問：「監査を開始する前に、自動メトリクスを収集しますか？\n\n1. SimpleCov — テストスイートを実行して、実際のコードカバレッジ率を取得します\n2. RubyCritic — コードの複雑さ、重複、コードスメルを分析します（テストは実行しません）\n\n最も徹底した監査を行うには、両方をおすすめします。」
• 選択肢：「両方実行（推奨）」／「SimpleCov のみ」／「RubyCritic のみ」／「両方スキップ」

ユーザーの選択に基づき、承認されたサブエージェントを Task ツールで並列に起動します。SimpleCov はテストヘルパーを変更し、RubyCritic はソースファイルを読み取るだけなので、両方を同時に実行しても競合しません。

SimpleCov サブエージェント（承認された場合）：

agents/simplecov_agent.md ファイルを読み、その中のすべての手順に従ってください。監査範囲は次のとおりです：{{SCOPE from Step 1}}。そのファイルで指定されている出力形式で、カバレッジデータを返してください。

RubyCritic サブエージェント（承認された場合）：

agents/rubycritic_agent.md ファイルを読み、その中のすべての手順に従ってください。監査範囲は次のとおりです：{{SCOPE from Step 1}}。そのファイルで指定されている出力形式で、コード品質データを返してください。

両方のエージェントが完了した後、後処理を行います。

• SimpleCov を実行した場合：rm -rf coverage/
• RubyCritic を実行した場合：rm -rf tmp/rubycritic/

応答の解釈：

• COVERAGE_FAILED／RUBYCRITIC_FAILED：該当ツールのデータはありません。SimpleCov の場合は推定モードを使用し、RubyCritic の場合は該当セクションを省略します。失敗理由をレポートに記載します。
• COVERAGE_DATA：解析し、ステップ 4 と 5 で参照できるようコンテキストに保持します（全体のカバレッジ、ディレクトリ別の内訳、カバレッジが最も低いファイル、カバレッジがゼロのファイル）。
• RUBYCRITIC_DATA：解析し、ステップ 4 と 5 で参照できるようコンテキストに保持します（全体スコア、ディレクトリ別評価、評価が最も低いファイル、主なコードスメル、最も複雑なファイル）。

ステップ 3：参考資料を読み込む

分析の前に、関連する参考ファイルを読みます。

• references/code_smells.md - 特定するコードスメルのパターン
• references/testing_guidelines.md - テストのベストプラクティス
• references/poro_patterns.md - PORO および ActiveModel のパターン
• references/security_checklist.md - セキュリティ脆弱性のパターン
• references/rails_antipatterns.md - Rails 固有のアンチパターン（外部サービス、マイグレーション、パフォーマンス）

ステップ 4：カテゴリ別にコードを分析する

すべての分析は、プロジェクトのルートとバンドルのパス内で行ってください。gem のソースを調べるには、bundle show <gem> を使用して場所を特定します（「分析コマンド」の「gem のソースを特定する」を参照）。find / のようなファイルシステム全体を検索するコマンドは、決して実行しないでください。以下のカテゴリをサブエージェントに委任する場合は、各サブエージェントのプロンプトにこの制約を含めてください。

次の順序で分析します。

1. テストの網羅率と品質

   • ステップ 2 で SimpleCov のデータを収集している場合は、推定値ではなく実際のカバレッジ率を使用します
   • ファイルごとの SimpleCov データを相互参照します。カバレッジが 0％ のファイルは「テスト不足」とします
   • テストファイルの不足を確認します
   • テストされていない公開メソッドを特定します
   • テスト構造（Four Phase Test）を確認します
   • テストのアンチパターンを確認します

2. セキュリティ脆弱性

   • SQL インジェクションのリスク
   • マスアサインメントの脆弱性
   • XSS 脆弱性
   • 認証／認可の問題
   • 機密データの漏えい

3. モデルとデータベース

   • ファットモデルの検出
   • バリデーション不足
   • N+1 クエリのリスク
   • コールバックの複雑さ
   • デメテルの法則への違反（のぞき見するモデル）
   • RubyCritic のデータを収集している場合は、評価が D/F のモデル、または複雑度の高いモデルを指摘します

4. コントローラー

   • ファットコントローラーの検出
   • コントローラー内のビジネスロジック
   • ストロングパラメーターの不足
   • レスポンス処理
   • モノリシックなコントローラー（RESTful でないアクション、7 個を超えるアクション）
   • 肥大化したセッション（ID ではなくオブジェクトを保存）
   • RubyCritic のデータを収集している場合は、評価が D/F のコントローラー、または複雑度の高いコントローラーを指摘します

5. コード設計とアーキテクチャ

   • サービスオブジェクト → PORO へのリファクタリングを推奨します
   • 大きなクラス
   • 長いメソッド
   • フィーチャーエンヴィ
   • デメテルの法則への違反
   • 単一責任の原則への違反
   • RubyCritic のデータを収集している場合は、評価が D/F のファイルや複雑度の高いファイルを、手動のコードレビューでの指摘と相互参照します

6. ビューとプレゼンター

   • ビュー内のロジック（PHPitis）
   • DRY のためのパーシャル不足
   • ヘルパーの複雑さ
   • ビュー内のクエリロジック

7. 外部サービスとエラー処理

   • ファイア・アンド・フォーゲット（HTTP 呼び出しの例外処理不足）
   • 応答の遅いサービス（タイムアウトの不足、バックグラウンド処理にすべき同期呼び出し）
   • rescue のみの文
   • サイレントな失敗（戻り値を確認せずに保存）

8. データベースとマイグレーション

   • 問題のあるマイグレーション（モデルへの参照、down メソッドの不足）
   • 外部キー、多態関連、一意性バリデーションに対するインデックスの不足
   • パフォーマンスのアンチパターン（SQL クエリではなく Ruby による反復処理）
   • トランザクションを使わない一括操作

ステップ 5：監査レポートを生成する

プロジェクトのルートに RAILS_AUDIT_REPORT.md を作成し、references/report_template.md で定義された構成にします。

ステップ 2 で SimpleCov のカバレッジデータを収集している場合は、レポートテンプレートのテストセクションの SimpleCov 版 を使用します。カバレッジデータを利用できない場合は、推定版 を使用します。

ステップ 2b で RubyCritic のデータを収集している場合は、レポートテンプレートの RubyCritic 版を使用して、コード品質メトリクス セクションをレポートに含めます。RubyCritic のデータを利用できない場合は、利用不可版 を使用します。

重要度の定義

• Critical：セキュリティ脆弱性、データ損失のリスク、本番環境を停止させる問題
• High：パフォーマンスの問題、重要な処理経路におけるテスト不足、重大なコードの問題
• Medium：コードの問題、規約違反、保守性に関する懸念
• Low：スタイルの問題、小規模な改善、提案

主な検出パターン

サービスオブジェクト → PORO へのリファクタリング

app/services/ 内のクラスを見つけた場合：

• *Service、*Manager、*Handler という名前のクラス
• .call または .perform メソッドだけを持つクラス
• 推奨事項：ドメイン名詞に名前を変更し、ActiveModel::Model を include します

ファットモデルの検出

次のいずれかに該当するモデル：

• 200 行を超える
• 公開メソッドが 15 個を超える
• 関連性のない複数の責務を持つ
• 推奨事項：コンポジションを使用して PORO に抽出します

ファットコントローラーの検出

以下に該当するコントローラーを検出します。

• アクションが15行を超える
• ビジネスロジック（リクエスト／レスポンスの処理以外）が含まれる
• インスタンス変数への代入が複数ある
• 推奨事項：フォームオブジェクトまたはドメインモデルに切り出します

テスト不足の検出

app/ 内の各 Ruby ファイルについて、以下を確認します。

• 対応する _spec.rb または _test.rb があるか
• 公開メソッドがテストされているか
• テストされていないファイルとメソッドを報告します

分析コマンド

シェルコマンドではなく、Claude Code の組み込みツールを使用してください。より高速で、権限を適切に処理でき、よりよい出力が得られます。

• 種類ごとに Ruby ファイルを検索：app/models/**/*.rb、app/controllers/**/*.rb、app/services/**/*.rb などのパターンを指定して、Glob ツールを使用します
• テストファイルを検索：spec/**/*_spec.rb または test/**/*_test.rb を指定して、Glob を使用します
• コード内のパターンを検索：Grep ツールを使用します（例：rescue\s*$、\.save\b、params\.permit! を検索）
• ファイルを読み込み、行数を数える：Read ツールでファイルを確認し、出力から行数を数えます
• 長いファイルを検索：Glob で app/**/*.rb ファイルをすべて一覧表示し、それぞれを Read で読み込んで行数を確認します
• gem のソースを特定：分析に gem が提供するコード（Devise、Administrate、Madmin などのエンジンに含まれるベースコントローラーや concern など）の読み込みが必要な場合は、bundle show <gem>（または bundle exec gem which <gem>/<path>）を使用してインストール済み gem のディレクトリを特定し、その中で Read／Grep を使用します。プロジェクトルートと bundle のパス以外を検索しないでください。find / やホームディレクトリ全体を対象とする glob は使用しないでください。

レポートの出力

監査レポートは必ずプロジェクトルートの RAILS_AUDIT_REPORT.md に保存し、ユーザーに提示してください。