implement-background-job

バックグラウンドジョブの実装

このスキルは、Rails アプリケーションでバックグラウンドジョブを追加、設定、またはレビューするタスクに使用します。

HARD-GATE

EVERY job MUST have its test written and validated BEFORE implementation:
  1. Write the job spec (idempotency, retry, error handling)
  2. Run the spec — verify it fails
  3. ONLY THEN write the job class

The authoritative perform contract — EVERY perform method does exactly three things:
  1. Load the record from the passed ID
  2. Guard for idempotency / permanent no-op conditions
  3. Delegate the side effect or orchestration to a service object

If perform needs more than that, extract a service.
EVERY job that performs a side effect (charge, email, API call) MUST have
an idempotency check BEFORE the side effect.

コアルール

項目	ルール
引数	オブジェクトではなく ID を渡す
リトライ	一時的なエラーには retry_on（明示的な attempts:）、恒久的なエラーには discard_on
バックエンド（Rails 8）	Solid Queue（データベースベース、Redis 不要）
バックエンド（Rails 7）	高スループットには Sidekiq + Redis
定期実行	config/recurring.yml（Solid Queue）または cron/sidekiq-cron
アンチパターン	引数に ActiveRecord オブジェクトを使わない。本番環境で :inline/:async を使わない。perform にビジネスロジックを書かない

コアプロセス

1. まずジョブスペックを書きます — 冪等性、リトライ、エラーハンドリング — そして実行して失敗することを確認します。
2. HARD-GATE の perform 契約に従ってジョブクラスを書きます。
3. 明示的な attempts: 制限付きの retry_on と、少なくとも 1 つの恒久的なエラーに対する discard_on を追加します。
4. テストスイート全体を実行します。
5. ジョブを 2 回エンキューまたは実行します — 2 回目の実行が no-op であることを確認します。
6. 定期実行ジョブの場合は、config/recurring.yml（Rails 8）または選択したスケジューラ設定で定義します。

拡張リソース

Rails 8 と Rails 7

項目	Rails 7 以前	Rails 8
デフォルト	デフォルトなし。queue_adapter を設定（多くの場合 Sidekiq）	Solid Queue（データベースベース）
開発/テスト	:async または :inline	同じ
定期実行	外部（cron、sidekiq-cron）	config/recurring.yml
ダッシュボード	サードパーティ（Sidekiq Web）	Mission Control Jobs

例

冪等性とリトライを備えたシンなジョブ:

class SendInvoiceReminderJob < ApplicationJob
  queue_as :default
  retry_on Net::OpenTimeout, wait: :polynomially_longer, attempts: 5
  discard_on ActiveRecord::RecordNotFound

  def perform(invoice_id)
    invoice = Invoice.find(invoice_id)
    return if invoice.reminder_sent_at?

    InvoiceReminders::Send.call(invoice:)
  end
end

サービスが副作用と状態更新を担う:

module InvoiceReminders
  class Send
    def self.call(invoice:)
      InvoiceMailer.overdue(invoice).deliver_now
      invoice.update!(reminder_sent_at: Time.current)
    end
  end
end

• BACKENDS.md — Solid Queue と Sidekiq のセットアップ、設定の詳細、Redis の要件。 これらのファイルは、その特定の内容が必要な場合にのみ読み込んでください:

• assets/job_patterns.md — マルチステップのオーケストレーションやバッチジョブパターンを実装する場合に使用します

• assets/retry_examples.md — 上記の基本パターンを超えて、特定のエラークラスに対して retry_on/discard_on を設定する場合に使用します

出力チェックリスト

• バックエンドの決定を明記している（Rails のバージョン/規模 → Solid Queue または Sidekiq）
• ジョブスペックを最初に示している。コマンドを実行し、実装前に失敗することを確認している
• perform は ID を受け取り、レコードを読み込み、冪等性をガードし、サービスに委譲している
• attempts: 制限付きの retry_on と、恒久的なエラーに対する discard_on がある
• 二重実行の検証により、2 回目の実行が no-op であることを確認している
• 定期実行ジョブ（ある場合）が config/recurring.yml またはスケジューラ設定で定義されている
• 運用ドキュメントが要求された場合: バックエンド、リトライ、定期実行スケジュール、冪等性の決定を process_log.md に記録している

連携

スキル	いつ連携するか
review-migration	Solid Queue は DB テーブルを使用する。マイグレーションを安全に追加する
security-check	ジョブはシリアライズされた入力を受け取る。他のエントリポイントと同様に検証する
write-tests	TDD ゲート: 実装前にジョブスペックを書く。perform_enqueued_jobs を使用する
create-service-object	perform をシンに保つ。ビジネスロジックにはサービスオブジェクトを呼び出す