Background Jobs skill for Claude Code

# Framework recipes

Read only the section for the backend in use. Check installed versions first; option
names below match current major versions (BullMQ 5, Celery 5, Sidekiq 7/8).

## BullMQ (Node, Redis)

```ts
import { Queue, Worker, UnrecoverableError } from "bullmq";
import IORedis from "ioredis";

const connection = new IORedis(process.env.REDIS_URL!, { maxRetriesPerRequest: null }); // required for workers

export const emailQueue = new Queue("email", {
  connection,
  defaultJobOptions: {
    attempts: 8,
    backoff: { type: "exponential", delay: 2000 },   // 2s, 4s, 8s ...
    removeOnComplete: { age: 24 * 3600, count: 10_000 },
    removeOnFail: { age: 14 * 24 * 3600 },            // keep failures for inspection
  },
});

await emailQueue.add("welcome", { userId }, { jobId: `welcome:${userId}` }); // dedupe while job exists

const worker = new Worker("email", async (job) => {
  const user = await users.find(job.data.userId);
  if (!user) throw new UnrecoverableError("user deleted");   // no further retries
  await mailer.send(user.email, "welcome", { idempotencyKey: job.id });
}, { connection, concurrency: 20, limiter: { max: 50, duration: 1000 } });

worker.on("failed", (job, err) => log.error({ jobId: job?.id, err }, "job failed"));
process.on("SIGTERM", async () => { await worker.close(); process.exit(0); });
```

- Repeatable/cron jobs: `await queue.upsertJobScheduler("nightly-report", { pattern: "0 3 * * *" }, { name: "report", data: {} })`
  (job schedulers replaced the older repeatable-jobs API in v5.16+).
- Use the Redis `noeviction` policy; an evicting Redis silently loses jobs.
- Stalled jobs: if a worker's event loop blocks longer than `lockDuration` (default 30 s),
  the job is considered stalled and retried. Keep CPU work in sandboxed processors
  (pass a file path to `Worker`) or raise `lockDuration`.
- Failed jobs past attempts remain in the `failed` set: that is the dead letter. Alert on
  `await queue.getJobCounts("failed", "waiting", "delayed")`.

## Celery (Python)

```python
# celery_app.py
app = Celery("app", broker=os.environ["BROKER_URL"])
app.conf.update(
    task_acks_late=True,                 # ack after success, so crashes redeliver
    task_reject_on_worker_lost=True,
    worker_prefetch_multiplier=1,        # fair dispatch for long tasks
    task_time_limit=300,                 # hard kill
    task_soft_time_limit=270,            # raises SoftTimeLimitExceeded first
    broker_transport_options={"visibility_timeout": 3600},  # Redis/SQS: must exceed longest task + ETA
    task_routes={"app.tasks.bulk_*": {"queue": "bulk"}},
)

@app.task(bind=True, autoretry_for=(requests.Timeout, requests.ConnectionError),
          retry_backoff=True, retry_backoff_max=3600, retry_jitter=True, max_retries=8)
def send_receipt(self, order_id: str) -> None:
    order = Order.objects.get(pk=order_id)
    if order.receipt_sent_at:
        return
    mailer.send_receipt(order, idempotency_key=f"receipt-{order_id}")
    Order.objects.filter(pk=order_id, receipt_sent_at__isnull=True).update(receipt_sent_at=now())
```

- `acks_late` + Redis/SQS means tasks exceeding `visibility_timeout` are redelivered to
  another worker while still running. Countdown/ETA tasks also count against it.
- Beat: run exactly one `celery -A app beat` process; use `django-celery-beat` for
  DB-managed schedules.
- Dead letters: Celery has no built-in DLQ for Redis. Record failures in an
  `on_failure` handler or a `task_failure` signal into a table; with RabbitMQ configure
  a dead-letter exchange on the queue.
- Start workers: `celery -A app worker -Q default,critical -c 8 --max-tasks-per-child 1000`.
- Shutdown: SIGTERM is a warm shutdown (finish current tasks). Set the container grace
  period above `task_time_limit` or accept redelivery.

## Sidekiq (Ruby)

```ruby
class SyncInvoiceJob
  include Sidekiq::Job
  sidekiq_options queue: :default, retry: 10, dead: true

  sidekiq_retry_in do |count, exception|
    case exception
    when Faraday::ClientError then :kill            # permanent: straight to Dead set
    else (count**4) + 15 + rand(10 * (count + 1))   # Sidekiq default curve with jitter
    end
  end

  def perform(invoice_id)
    invoice = Invoice.find_by(id: invoice_id) or return
    return if invoice.synced?
    Accounting.push(invoice, idempotency_key: "invoice-#{invoice_id}")
    invoice.update!(synced_at: Time.current)
  end
end
```

- Default 25 retries span about 20 days; lower it for user-facing work.
- Arguments must be simple JSON types (strings, numbers, arrays, hashes with string keys);
  Sidekiq 7 warns and can raise on others (`Sidekiq.strict_args!`).
- Dead set (`retry` exhausted) is the DLQ; it is capped (10,000 jobs / 6 months by default).
- Concurrency in `config/sidekiq.yml` (`concurrency: 10`); weights per queue
  (`queues: [[critical, 6], [default, 3], [bulk, 1]]`).
- Shutdown: Sidekiq stops fetching on TSTP/TERM and waits `timeout` (default 25 s) then
  pushes unfinished jobs back to Redis.

## Amazon SQS + Lambda or workers

- Visibility timeout at least 6x the consumer timeout for Lambda event sources; for
  long-running workers extend it with `ChangeMessageVisibility` while working.
- Redrive policy `maxReceiveCount` 3-5 to a DLQ; alarm on `ApproximateNumberOfMessagesVisible`
  for the DLQ > 0 and on `ApproximateAgeOfOldestMessage` for the main queue.
- Batch consumers report partial failures (`ReportBatchItemFailures`) so one bad message
  does not retry the whole batch.
- FIFO queues: ordering and dedupe per `MessageGroupId`, 5-minute dedupe window by
  `MessageDeduplicationId`; throughput is per group.
- Replay DLQ messages with the console or `aws sqs start-message-move-task --source-arn <dlq-arn>`.

## Solid Queue (Rails 8)

- Configure workers and dispatchers in `config/queue.yml`, recurring tasks in
  `config/recurring.yml`. Runs on the database; keep job tables in a separate database
  (Rails 8 default `queue` database) to avoid contention.
- Failed executions stay in `solid_queue_failed_executions`; inspect and retry with
  Mission Control Jobs.