rails-stack-conventions

Rails Stack Conventions

このプロジェクトのコードを記述または生成する際は、これらの規約に従ってください。スタック：Ruby on Rails、PostgreSQL、Hotwire（Turbo + Stimulus）、Tailwind CSS。

スタイル： プロジェクトでリンターを使用している場合、書式設定の基準としてリンターを優先してください。横断的な設計原則（DRY、YAGNI、構造化ログ、ディレクトリごとのルール）については、rails-code-conventionsを使用してください。

HARD-GATE：テストを実装の必須条件とする

ALL new code MUST have its test written and validated BEFORE implementation.
  1. Write the spec: bundle exec rspec spec/[path]_spec.rb
  2. Verify it FAILS — output must show the feature does not exist yet
  3. Write the implementation code
  4. Verify it PASSES — run the same spec and confirm green
  5. Refactor if needed, keeping tests green
See rspec-best-practices for the full gate cycle.

機能開発のワークフロー

一般的な機能では、次の順序でスタックのパターンを組み合わせます。

1. モデル — バリデーション、関連、スコープを追加します。ループ内で使用する関連は includes で事前読み込みします
2. サービスオブジェクト — コントローラーから複雑なビジネスロジックを切り出します（ruby-service-objectsを参照）
3. コントローラー — アクションを薄く保ち、サービスに処理を委譲します。turbo_stream形式とhtml形式で応答します
4. ビュー／Turbo の配線 — 動的なセクションを<turbo-frame>タグで囲み、コントローラーからturbo_streamレスポンスをブロードキャストします
5. Stimulus — Turbo だけではクライアント側のインタラクションに対応できない場合にのみ、コントローラーを追加します
6. Tailwind — ビューにユーティリティクラスを適用し、繰り返し使うパターンはパーシャルまたは Stimulus のターゲットに切り出します

次のレイヤーに接続する前に、各ステップを個別にテストできる状態にしておきます。

主なコードパターン

Hotwire：Turbo Frames

<%# Wrap a section to be replaced without a full page reload %>
<turbo-frame id="order-<%= @order.id %>">
  <%= render "orders/details", order: @order %>
</turbo-frame>

<%# Link that targets only this frame %>
<%= link_to "Edit", edit_order_path(@order), data: { turbo_frame: "order-#{@order.id}" } %>

Hotwire：Turbo Streams（コントローラーからブロードキャスト）

respond_to do |format|
  format.turbo_stream do
    render turbo_stream: turbo_stream.replace(
      "order_#{@order.id}",
      partial: "orders/order",
      locals: { order: @order }
    )
  end
  format.html { redirect_to @order }
end

N+1 の回避 — 事前読み込み

# BAD — triggers one query per order
@orders = Order.where(user: current_user)
@orders.each { |o| o.line_items.count }

# GOOD — single JOIN via includes
@orders = Order.includes(:line_items).where(user: current_user)

サービスオブジェクト（複雑なビジネスロジックをコントローラーから切り出す）

# Controller stays thin — delegate to service
result = Orders::CreateOrder.call(user: current_user, params: order_params)
if result[:success]
  redirect_to result[:order], notice: "Order created"
else
  @order = Order.new(order_params)
  render :new, status: :unprocessable_entity
end

.callパターンとレスポンス形式の詳細は、ruby-service-objectsを参照してください。

セキュリティ

このプロジェクトでは、認証にDevise、認可にPunditを使用しています。アクセス制御対象のリソースを導入するすべての機能に、これらを適用してください。

避けるべき落とし穴

問題	正しい方法
ビュー内のビジネスロジック	ヘルパー、プレゼンター、または Stimulus コントローラーを使用する
ループ内の N+1 クエリ	ループの前にincludesで事前読み込みする
「手早い」テストで FactoryBot を省略する	フィクスチャは壊れやすいため、常にファクトリーを使用する
ビジネスロジックが15行以上あるコントローラーアクション	サービスオブジェクトに切り出す
必須フィールドにバリデーションがないモデル	存在性／形式のバリデーションを追加する
Ruby の条件分岐を10行以上埋め込んだビュー	ロジックをプレゼンターまたはパーシャルに移す
I18n に置くべき文字列のハードコード	t()ヘルパーを使用する

連携

スキル	連携するタイミング
rails-code-conventions	設計原則、構造化ログ、パス固有のルールを確認するとき
rails-code-review	既存のコードをこれらの規約に照らしてレビューするとき
ruby-service-objects	ビジネスロジックをサービスオブジェクトに切り出すとき
rspec-best-practices	テスト規約と、完全なレッド／グリーン／リファクタリングの TDD サイクルを確認するとき
rails-architecture-review	規約の範囲を超えて構造をレビューするとき