rails-conventions

Rails 規約エンジニア

このワークフローに従い、タスクに必要な参照のみを読み込んでください。

実行ワークフロー

1. 変更を提案する前に、コードベースを調べます。
2. ユーザーが移行を依頼していない限り、既存の規約に合わせます。
3. まず Rails の規約と素の Ruby を使います。
4. テストを伴う、小さく元に戻しやすい変更を優先します。
5. アーキテクチャを選択する際は、トレードオフを明示します。
6. ガイダンスを変更したり、新しい API を導入したりする前に、バージョン依存の API を Rails または gem の公式ドキュメントで確認します。
7. ジェネレーターが管理するファイルは、ジェネレーターを実行してのみ作成します。決して自作しないでください。

Rails の必須デフォルト

Rails アプリケーションは Rails アプリケーションらしくあるべきです。余分なアーキテクチャ層を導入する前に、フレームワーク標準のリソース、モデル、コントローラー、ジョブ、メーラー、ビューの境界を優先します。Rails にその問題を解決する直接的な規約がある場合は、他のエコシステムから借りたアーキテクチャを避けてください。

Rails 公式ガイド、gem の公式ドキュメント、確立されたローカルアプリの規約は、スタイルプロファイルより優先されます。レイアウトにはリポジトリで設定されているフォーマッターとリンターを使用してください。このスキルのスタイル例に合わせることだけを目的として、抑制コメントを追加したり、Lint ルールを変更したりしないでください。37signals に着想を得たガイダンスは、現在のアプリや Rails API に優先する権威ではなく、趣味の指針として扱います。

クラスとモジュールは、その存在意義を示す必要があります。動作を明確に保つために必要な概念、ファイル、コード行を最小限にしてください。主な目的が命名、間接化、またはテストの容易化であるラッパー、エイリアス、ファサード、並行する抽象化を追加しないでください。

識別子名には所有者を明示します。id と uuid はローカルアプリケーションが所有します。eid は、別のアプリケーションまたはプロバイダーが所有し、ローカルに保存される識別子を意味します。ローカルの id や uuid に eid の別名を付けてはいけません。レコードが複数の外部所有者の識別子を持つ場合は、place_eid、listing_eid、review_eid のような修飾名を使います。ローカル識別子が *_eid になるのは、その識別子を使用するシステム内に限られ、所有するシステム内ではありません。

すべての Rails プロジェクトでは、通常 docs/domain-terms.md にドメイン用語文書を置き、README または同等のコントリビューター向けエントリーポイントからリンクしてください。この文書では、正規のドメイン用語、非推奨の用語、コード、ルート、パラメーター、API、永続化フィールド、ドキュメントの命名規則を定義します。

ジェネレーターが管理するファイル

Rails または gem インストーラーが生成するはずのファイルを、手書きしてはいけません。タイムスタンプを捏造したり、インストーラーのスタブを作ったり、スキーマダンプを推測して作成したりすると、差異が生じ、デプロイが壊れる原因になります。

ジェネレーター（またはインストーラーのタスク）を実行してから、生成結果を編集します。

• マイグレーション：bin/rails generate migration ... / bin/rails g model ...
• メーラー、ジョブ、コントローラー、スキャフォールド：該当する bin/rails g ...
• 認証：アプリの方式である場合は bin/rails generate authentication
• キュー／キャッシュ／ケーブルのインストーラー：gem または Rails のインストールタスク （solid_queue:install、good_job:install など）
• インストーラーが作成するアプリ／フレームワークの設定ファイル（db/*_schema.rb、 config/queue.yml、bin/jobs などの binstub）。ただし、アプリにすでに存在する場合を除きます。

生成後、ファイルをローカルの規約に合わせます。マイグレーションのバージョン番号やタイムスタンプを捏造してはいけません。インストーラーが存在する場合、その出力を記憶に頼って再作成してはいけません。この環境でジェネレーターを実行できない場合は、その旨を伝えてユーザー向けに正確なコマンドを示してください。ファイルを捏造してはいけません。

必須のコードベーススキャン

利用可能な場合は、必ず最初に以下のファイルを読みます。

• Gemfile
• config/application.rb
• config/routes.rb
• config/environments/*.rb（少なくとも対象となる環境）
• app/models/（代表的なモデルを2～5個）
• app/controllers/（代表的なコントローラーを2～5個）
• test/ または spec/
• プロセス／デプロイのエントリーポイント（Procfile*、bin/jobs、config/deploy*.yml、CI 設定）

確認したパターンを記録し、それに従います。

• テストフレームワーク
• 認証／認可の方式
• フロントエンドのスタック（Hotwire、React、ハイブリッド）
• キューバックエンドと実行時のトポロジー
• API の規約とシリアライズの方式

バックグラウンドジョブのバックエンドポリシー

Rails 8 であるという理由だけで、Solid Queue を決めつけないでください。

以下の順にバックエンドを検出します。

1. config.active_job.queue_adapter
2. Gemfile の gem（good_job、solid_queue、その他）
3. ワーカーの実行コマンドとデプロイ設定

以下のルールを適用します。

• good_job が有効な場合は、good_job の規約を維持します。
• solid_queue が有効な場合は、solid_queue の規約を維持します。
• 両方の gem が存在する場合は、設定されているアダプターを優先します。
• 無関係なタスクの一環として、暗黙にキーバックエンドを移行しないでください。
• バックエンド固有の機能が明示的に求められていない限り、バックエンドに依存しない ApplicationJob コードを記述します。

リファレンスの参照

タスクに応じてリファレンスを読み込みます。

• コードスタイル、フォーマット、命名規約、フェイルファスト方針：STYLE.md
• Rails 8 の基本的なデフォルト設定とアップグレード時の制約：references/01-baseline-rails-8.md
• 命名、レイヤリング、コード構成：references/02-naming-and-structure.md
• Active Record、マイグレーション、データモデリング：references/03-models-and-data.md
• PostgreSQL 固有の Active Record 機能：references/03a-active-record-postgresql.md
• コントローラー、パラメーター、リクエストフロー：references/04-controllers-and-params.md
• REST リソースとルート：references/05-routes-rest-and-resources.md
• Hotwire、Turbo、Stimulus のパターン：references/06-hotwire-turbo-stimulus.md
• ジョブのアーキテクチャとアダプターの検出：references/07-background-jobs-overview.md
• GoodJob 固有のパターン：references/07a-background-jobs-good_job.md
• Solid Queue 固有のパターン：references/07b-background-jobs-solid_queue.md
• パフォーマンスとキャッシュ戦略：references/08-performance-caching-and-db.md
• セキュリティレビューのチェックリスト：references/09-security-checklist.md
• テスト戦略と品質ゲート：references/10-testing-strategy.md
• API 専用および混在モードの API パターン：references/11-api-mode-and-serialization.md
• 37signals に着想を得たスタイルプロファイル：references/12-37signals-inspired-profile.md
• コード品質のしきい値と検出パターン：references/13-code-quality-gates.md
• インバウンド／アウトバウンドの Webhook と配信の信頼性：references/14-webhooks.md

タスクの振り分け

タスク	読み込むファイル
Ruby のスタイル、命名、メソッドの順序、フェイルファスト	STYLE.md、references/13-code-quality-gates.md
新しいモデル、マイグレーション、データ不変条件、パーサー	references/03-models-and-data.md、references/03a-active-record-postgresql.md、references/10-testing-strategy.md
コントローラーのパラメーター、認可、セッション、レスポンス	references/04-controllers-and-params.md、references/09-security-checklist.md、references/10-testing-strategy.md
ルートまたはカスタムアクション	references/05-routes-rest-and-resources.md、references/04-controllers-and-params.md
Hotwire、Turbo、Stimulus	references/06-hotwire-turbo-stimulus.md、references/10-testing-strategy.md
バックグラウンドジョブ	references/07-background-jobs-overview.md、アダプター固有の 07a または 07b、references/10-testing-strategy.md
Webhook（受信または送信）	references/14-webhooks.md、references/09-security-checklist.md、references/07-background-jobs-overview.md、references/10-testing-strategy.md
API エンドポイントまたはシリアライザー	references/11-api-mode-and-serialization.md、references/04-controllers-and-params.md、references/09-security-checklist.md
パフォーマンス、キャッシュ、クエリに関する作業	references/08-performance-caching-and-db.md、references/03-models-and-data.md
アーキテクチャまたはオブジェクトの境界	references/02-naming-and-structure.md、references/12-37signals-inspired-profile.md

認証パターン

既存の認証方式とローカルの命名規則を優先してください。新規に Rails 8.1 アプリケーションを作成する場合は、組み込みの認証ジェネレーターを推奨します。スタイルだけを理由に、既存の認証ドメインの名前を変更しないでください。

カスタム認証を実装する場合：

• has_secure_password を使い、bcrypt によるパスワード認証を使用します。
• アカウントの確認とメール認証には、マジックリンクのコード（完全なマジックリンク URL ではありません）を使用します。
• アカウントベースのアプリケーションを新規に作成する場合は、Identity（グローバルなメールアドレスベース）、User（アカウントごとのメンバーシップ）、Session の使用を検討します。
• 認証エンドポイントには厳格なレート制限を設けます。
• httponly と same_site: :lax を指定した署名付き Cookie でセッションを保存します。

出力要件

実装タスクでは、以下を作成します。

1. 生成されたマイグレーションによる必要なスキーマ変更（「ジェネレーターが管理するファイル」を参照）。
2. ローカルの規約に従ったモデル／コントローラー／ビュー／ジョブのコード。
3. ローカルのフレームワークに沿い、責務ごとに分割したテスト（references/10-testing-strategy.md を参照）。
4. リスクに関する簡潔な注記（セキュリティ、パフォーマンス、ロールアウトに関する懸念）。
5. 現行ドキュメントを確認した場合は、バージョン依存の API に関する出典の注記。

レビュータスクでは、以下を優先します。

1. 正確性と動作のリグレッション。
2. セキュリティとデータの整合性。
3. パフォーマンスと運用性。
4. テストの不足。