awesome-copilot/instructions/ruby-on-rails.instructions_ja.md

description	applyTo
Ruby on Railsのコーディング規約とガイドライン	**/*.rb

Ruby on Rails

一般的なガイドライン

• RuboCopスタイルガイドに従い、一貫性のあるフォーマットのためにrubocop、standardrb、rufoなどのツールを使用する。
• 変数/メソッドにはsnake_case、クラス/モジュールにはCamelCaseを使用する。
• メソッドは短く、焦点を絞る；複雑さを減らすために早期リターン、ガード節、プライベートメソッドを使用する。
• 短い名前や汎用的な名前よりも意味のある名前を優先する。
• 必要な時のみコメントを書く — 明らかなことの説明は避ける。
• クラス、メソッド、モジュールに単一責任原則を適用する。
• 継承よりもコンポジションを優先；再利用可能なロジックをモジュールやサービスに抽出する。
• コントローラーは薄く保つ — ビジネスロジックをモデル、サービス、またはコマンド/クエリオブジェクトに移動する。
• 「Fat Model, Skinny Controller」パターンを思慮深く、明確な抽象化で適用する。
• 再利用性とテスト性のためにビジネスロジックをサービスオブジェクトに抽出する。
• ビューの重複を減らし簡素化するためにパーシャルまたはビューコンポーネントを使用する。
• 否定条件にはunlessを使用するが、明確性のためにelseとの組み合わせは避ける。
• 深くネストした条件分岐を避ける — ガード節とメソッド抽出を優先する。
• 複数のnilチェックの代わりに安全ナビゲーション（&.）を使用する。
• 手動のnil/空チェックよりも.present?、.blank?、.any?を優先する。
• ルーティングとコントローラーアクションでRESTful規約に従う。
• リソースを一貫してスキャフォールドするためにRailsジェネレーターを使用する。
• 属性を安全にホワイトリスト化するためにストロングパラメーターを使用する。
• より良いモデルの明確性と検証のためにenumと型付き属性を優先する。
• マイグレーションはデータベース非依存にする；可能な場合は生SQLを避ける。
• 外部キーと頻繁にクエリされるカラムには常にインデックスを追加する。
• モデルだけでなくDBレベルでnull: falseとunique: trueを定義する。
• メモリ使用量を減らすため大きなデータセットの反復処理にはfind_eachを使用する。
• 明確性と再利用性のためにモデルでクエリをスコープ化するかクエリオブジェクトを使用する。
• before_actionコールバックは控えめに使用 — その中でビジネスロジックを避ける。
• 高価な計算や頻繁にアクセスされるデータの保存にはRails.cacheを使用する。
• ハードコーディングの代わりにRails.root.join(...)でファイルパスを構築する。
• 明示的な関係性のためにアソシエーションでclass_nameとforeign_keyを使用する。
• Rails.application.credentialsまたは環境変数を使用してシークレットと設定をコードベースから除外する。
• モデル、サービス、ヘルパーの分離されたユニットテストを書く。
• エンドツーエンドロジックをリクエスト/システムテストでカバーする。
• メール送信やAPI呼び出しなどのノンブロッキング操作にはバックグラウンドジョブ（ActiveJob）を使用する。
• テストデータをきれいにセットアップするためにFactoryBot（RSpec）またはfixtures（Minitest）を使用する。
• putsの使用を避ける — byebug、pry、またはロガーユーティリティでデバッグする。
• 複雑なコードパスとメソッドをYARDまたはRDocで文書化する。

アプリディレクトリ構造

• ビジネスロジックをカプセル化するためapp/servicesディレクトリにサービスオブジェクトを定義する。
• 検証と送信ロジックを管理するためapp/formsに配置されたフォームオブジェクトを使用する。
• APIレスポンスをフォーマットするためapp/serializersディレクトリにJSONシリアライザーを実装する。
• リソースへのユーザーアクセスを制御するためapp/policiesに認可ポリシーを定義する。
• app/graphql内でスキーマ、クエリ、ミューテーションを組織化してGraphQL APIを構造化する。
• 特殊な検証ロジックを強制するためapp/validatorsにカスタムバリデーターを作成する。
• より良い再利用性とテスト性のためapp/queriesで複雑なActiveRecordクエリを分離・カプセル化する。
• ActiveModelタイプ動作を拡張またはオーバーライドするためapp/typesディレクトリにカスタムデータ型と変換ロジックを定義する。

コマンド

• 新しいモデル、コントローラー、マイグレーションを作成するためrails generateを使用する。
• データベースマイグレーションを適用するためrails db:migrateを使用する。
• 初期データでデータベースを投入するためrails db:seedを使用する。
• 最後のマイグレーションを元に戻すためrails db:rollbackを使用する。
• REPL環境でRailsアプリケーションと対話するためrails consoleを使用する。
• 開発サーバーを開始するためrails serverを使用する。
• テストスイートを実行するためrails testを使用する。
• アプリケーション内の定義されたすべてのルートをリストするためrails routesを使用する。
• 本番用にアセットをコンパイルするためrails assets:precompileを使用する。

API開発ベストプラクティス

• RESTful規約に従うためRailsのresourcesを使用してルートを構造化する。
• バージョン管理と前方互換性のため名前空間化されたルート（例：/api/v1/）を使用する。
• 一貫した出力のためActiveModel::Serializerまたはfast_jsonapiを使用してレスポンスをシリアライズする。
• 各レスポンスに適切なHTTPステータスコードを返す（例：200 OK、201 Created、422 Unprocessable Entity）。
• リソースの読み込みと認可のためbefore_actionフィルターを使用し、ビジネスロジックには使用しない。
• 大きなデータセットを返すエンドポイントにはページネーション（例：kaminariまたはpagy）を活用する。
• ミドルウェアまたはrack-attackなどのgemを使用して機密エンドポイントをレート制限・スロットリングする。
• エラーコード、メッセージ、詳細を含む構造化されたJSON形式でエラーを返す。
• ストロングパラメーターを使用して入力パラメーターをサニタイズ・ホワイトリスト化する。
• 内部ロジックをレスポンスフォーマットから分離するためカスタムシリアライザーまたはプレゼンターを使用する。
• 関連データの先行読み込み時にincludesを使用してN+1クエリを避ける。
• メール送信や外部APIとの同期などのノンブロッキングタスクにはバックグラウンドジョブを実装する。
• デバッグ、可観測性、監査のためリクエスト/レスポンスメタデータをログに記録する。
• OpenAPI（Swagger）、rswag、またはapipie-railsを使用してエンドポイントを文書化する。
• 必要に応じてAPIへのクロスオリジンアクセスを許可するためCORSヘッダー（rack-cors）を使用する。
• 機密データがAPIレスポンスやエラーメッセージに決して露出しないことを確認する。

フロントエンド開発ベストプラクティス

• WebpackerまたはesbuildでRails 6+のJavaScriptパック、モジュール、フロントエンドロジックを管理するメインディレクトリとしてapp/javascriptを使用する。
• モジュラー性を保つためファイルタイプではなくコンポーネントまたはドメインでJavaScriptを構造化する。
• Rails-nativeアプリでリアルタイム更新と最小限のJavaScriptのためHotwire（Turbo + Stimulus）を活用する。
• HTMLに動作をバインドし、UIロジックを宣言的に管理するためStimulusコントローラーを使用する。
• app/assets/stylesheets下でSCSSモジュール、Tailwind、またはBEM規約を使用してスタイルを組織化する。
• 繰り返しマークアップをパーシャルまたはコンポーネントに抽出してビューロジックをクリーンに保つ。
• セマンティックHTMLタグを使用し、すべてのビューでアクセシビリティ（a11y）ベストプラクティスに従う。
• インラインJavaScriptとスタイルを避ける；代わりに明確性と再利用性のため別の.jsまたは.scssファイルにロジックを移動する。
• キャッシュと圧縮のためアセットパイプラインまたはバンドラーを使用してアセット（画像、フォント、アイコン）を最適化する。
• Rails生成HTMLとStimulusでフロントエンドインタラクティビティをブリッジするためdata-*属性を使用する。
• システムテスト（Capybara）またはCypressやPlaywrightなどのツールを使用した統合テストでフロントエンド機能をテストする。
• 本番環境で不要なスクリプトやスタイルを防ぐため環境固有のアセット読み込みを使用する。
• UIを一貫性があり拡張可能に保つためデザインシステムまたはコンポーネントライブラリに従う。
• 遅延読み込み、Turboフレーム、JS遅延を使用してfirst-paint時間（TTFP）とアセット読み込みを最適化する。

テストガイドライン

• ビジネスロジックを検証するためtest/models（Minitest）またはspec/models（RSpec）を使用してモデルのユニットテストを書く。
• テストデータをきれいで一貫して管理するためfixtures（Minitest）またはFactoryBotでのfactories（RSpec）を使用する。
• RESTful API動作をテストするためtest/controllersまたはspec/requests下でコントローラーspecを組織化する。
• 共通テストデータを初期化するためRSpecのbeforeブロックまたはMinitestのsetupを優先する。
• テストでの外部API呼び出しを避ける — テスト環境を分離するためWebMock、VCR、またはstub_requestを使用する。
• 完全なユーザーフローをシミュレートするためMinitestのsystem testsまたはRSpecのCapybaraでのfeature specsを使用する。
• 遅くて高価なテスト（例：外部サービス、ファイルアップロード）を別のテストタイプまたはタグに分離する。
• 適切なコードカバレッジを確保するためSimpleCovなどのテストカバレッジツールを実行する。
• テストでsleepを避ける；MinitestやRSpecでActiveJob::TestHelperを使用してperform_enqueued_jobsを使用する。
• テスト間でクリーンな状態を維持するためデータベースクリーニングツール（rails test:prepare、DatabaseCleaner、またはtransactional_fixtures）を使用する。
• ActiveJob::TestHelperまたはhave_enqueued_jobマッチャーを使用してジョブをエンキューし実行してバックグラウンドジョブをテストする。
• CI ツール（例：GitHub Actions、CircleCI）を使用して環境間でテストが一貫して実行されることを確認する。
• 再利用可能で表現力豊かなテストロジックのためカスタムマッチャー（RSpec）またはカスタムアサーション（Minitest）を使用する。
• より高速で対象を絞ったテスト実行のためタイプ（例：:model、:request、:feature）でテストをタグ付けする。
• 脆弱なテストを避ける — 明示的に必要でない限り特定のタイムスタンプ、ランダム化されたデータ、または順序に依存しない。
• 複数レイヤー（モデル、ビュー、コントローラー）にわたるエンドツーエンドフローの統合テストを書く。
• テストを高速、信頼性があり、本番コードと同じくらいDRYに保つ。