apply-stack-conventions

スタック規約を適用する

クイックリファレンス

スタック領域	デフォルトの規約
Rails MVC	コントローラーは薄く保つ。自明でないビジネスロジックはサービスオブジェクトへ移す
PostgreSQL	includes で N+1 を回避する。整合性の確保にはデータベース制約を使う
Hotwire	Stimulus より Turbo Frames/Streams を優先する。Turbo で対話性を扱えない場合にのみ Stimulus に頼る
Tailwind	ビューではユーティリティを使う。繰り返し現れる UI はパーシャル/コンポーネントへ抽出する
認証	アクセス制御されたリソースに触れるすべてのアクションに Devise 認証と Pundit 認可を適用する

HARD-GATE: TDD サイクル

すべての新しいコードは、実装の前にテストを書き、検証されていなければなりません。すべてのレイヤーで次のサイクルを正確に守ってください:

1. スペックファイルを書く — パスだけでなく、ファイルの内容全体を示す
2. 実行する: bundle exec rspec spec/[path]_spec.rb — FAILS することを確認する（Observed RED output）
3. 実装コードを書く
4. 同じコマンドを再実行する — PASSES することを確認する（Observed GREEN output）
5. 必要ならリファクタリングし、テストをグリーンに保つ

CRITICAL: すべてのテストコマンドはシェル/ターミナルツールを使って実行してください。ターミナル出力を捏造、モック、シミュレートしないでください。実際に観測した出力をコピー&ペーストしてください。環境がテストの実行をサポートしていない場合は、停止してユーザーに伝えてください — 検証済みの RED 出力なしに実装へ進まないでください。

Red-Green サイクルの例

スペックファイル — spec/models/order_spec.rb

require 'rails_helper'

RSpec.describe Order, type: :model do
  describe 'validations' do
    it 'is invalid without a total' do
      order = build(:order, total: nil)
      expect(order).not_to be_valid
      expect(order.errors[:total]).to include("can't be blank")
    end
  end
end

実行コマンド

bundle exec rspec spec/models/order_spec.rb

Observed RED output — 実際のターミナル出力をここに貼り付けてください（失敗を期待）

モデル実装 — app/models/order.rb

class Order < ApplicationRecord
  validates :total, presence: true
end

Observed GREEN output — 実際のターミナル出力をここに貼り付けてください（成功を期待）

コアプロセス

スタック: Ruby on Rails、PostgreSQL、Hotwire（Turbo + Stimulus）、Tailwind CSS。

スタイル: プロジェクトがリンターを使っている場合、フォーマットの信頼できる情報源として扱ってください。横断的な設計原則（DRY、YAGNI、構造化ログ、ディレクトリごとのルール）については、apply-code-conventions を使用してください。

機能開発ワークフロー

一般的な機能では、スタックのパターンを次の順序で組み立てます:

1. モデル — バリデーション、関連、スコープを追加する。ループ内で使う関連は includes でeager load する
2. サービスオブジェクト — コントローラーから自明でないビジネスロジックを抽出する（create-service-object を参照）
3. コントローラー — アクションは薄く保つ。サービスへ委譲する。turbo_stream と html フォーマットで応答する
4. ビュー / Turbo の配線 — 動的なセクションを <turbo-frame> タグで囲む。コントローラーから turbo_stream レスポンスをブロードキャストする
5. Stimulus — クライアント側の対話性を Turbo だけでは扱えない場合にのみコントローラーを追加する
6. Tailwind — ビューにユーティリティクラスを適用する。繰り返し現れるパターンはパーシャルや Stimulus ターゲットへ抽出する

各ステップは、次のレイヤーへ配線する前に、単独でテスト可能な状態を保つべきです。最終成果物には、モデル/クエリ、サービス、コントローラー/リクエスト、ビュー/Turbo、Stimulus、Tailwind それぞれの焦点を絞ったスペックまたはチェックを挙げる Layer isolation セクションを含めてください。レイヤーが変更されていない場合は「該当なし」と記し、どのレイヤーも黙って省略しないでください。

サービスオブジェクトパターン

コントローラーは .call を介してサービスへ委譲します。サービスは結果のハッシュを返します。完全なパターンと実装の詳細については、create-service-object と assets/snippets/service_object.rb を参照してください。

# app/controllers/orders_controller.rb
def create
  result = CreateOrderService.call(order_params)
  if result[:success]
    redirect_to result[:record], notice: 'Order created.'
  else
    render :new, status: :unprocessable_entity
  end
end

eager loading のパターンと N+1 の修正については、以下の Extended Resources セクションを参照してください。

避けるべき落とし穴

問題	正しいアプローチ
15 行以上のビジネスロジックを持つコントローラーアクション	.call パターンを使ってサービスオブジェクトへ抽出する
認可チェックなしで保護されたリソースにアクセスする	アクセス制御されたデータに触れるすべてのアクションに Pundit ポリシーを適用する

出力スタイル

すべての応答には、必ず次のセクションをこの順序で含めてください。

1. スタックの決定 — どの Rails、PostgreSQL、Hotwire、Stimulus、Tailwind、認証、およびサービスオブジェクトの規約が適用されるか。
2. 実装前のテストファーストの証明 — レイヤーごとに HARD-GATE サイクル（spec ファイルの内容 → RED 出力 → 実装 → GREEN 出力）に従います。
3. レイヤーの分離 — 変更された各レイヤーに対して焦点を絞った spec/チェックを行い、変更されていないレイヤーは「該当なし」とマークします。
4. レイヤーごとの実装 — モデル/クエリ、サービス、コントローラー、ビュー、Stimulus、Tailwind の変更を分離します。
5. パフォーマンスとセキュリティのチェック — N+1 の防止、認可ポリシーの使用、安全でないパラメータ/コンテンツの処理。

拡張リソース（段階的開示）

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

• assets/snippets/eager_loading.rb — N+1 クエリを修正するために eager loading パターンを適用するときに使用します
• assets/snippets/n_plus_one_fix_example.rb — before/after を含む完全な N+1 修正例が必要なときに使用します
• assets/snippets/service_object.rb — コントローラーのロジックをサービスオブジェクトに抽出するときに使用します
• assets/snippets/turbo_frame.html.erb — Turbo Frame パターンを実装するときに使用します
• assets/snippets/stimulus_controller.js — Stimulus コントローラーを追加するときに使用します
• assets/snippets/tailwind_component.html.erb — Tailwind でスタイル設定されたビューコンポーネントを構築するときに使用します

連携

スキル	チェーンするタイミング
apply-code-conventions	設計原則、構造化ログ、パス固有のルールについて
code-review	既存のコードをこれらの規約に照らしてレビューするとき
create-service-object	ビジネスロジックをサービスオブジェクトに抽出するとき
write-tests	テストの規約と完全な red/green/refactor の TDD サイクルについて
review-architecture	規約を超えた構造的なレビューについて