AGENT SKILL

queue-rules

MUST NOT / SHOULD NOT rules for background work: queue producers and workers, scheduled jobs, sweeps, reconcilers, backfills, leases, and dedup. Use when writing or reviewing a job, a worker, an enqueue call, or any loop that reads rows on a schedule.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 11
Forks
1

01 前言 Front Matter

name
queue-rules
description
MUST NOT / SHOULD NOT rules for background work: queue producers and workers, scheduled jobs, sweeps, reconcilers, backfills, leases, and dedup. Use when writing or reviewing a job, a worker, an enqueue call, or any loop that reads rows on a schedule.

03 SKILL.md 正文

Queue and background-job rules

MUST NOT is a defect. SHOULD NOT needs a stated, measured reason.

Producers and workers

  • MUST NOT drop the promise of an enqueue or schedule call; await it, or mark deliberate fire-and-forget with void and a rejection handler.
  • MUST NOT enqueue inside a transaction that may roll back; enqueue after commit. Exception: when the enqueue is the only durable handoff (a consumer whose idempotency row is its only record), enqueue inside the transaction so a failed enqueue rolls the row back; the enqueue must tolerate collisions, and the worker must be idempotent and treat a missing row as a retry.
  • MUST NOT rename a job or change its payload in one step; ship worker support for both shapes, then switch producers, then drop the old once no old-shape jobs remain queued, delayed, or retrying.
  • MUST NOT assume a unique job id prevents duplicate runs; it only dedupes enqueues. Make the work idempotent.
  • MUST NOT key dedup ids by entity alone; include the triggering event, because retained jobs still hold the id.
  • MUST NOT put shared-queue jobs in no ordering lane or with implicit concurrency; one family starves the rest.
  • MUST NOT expect priority to reorder work inside one FIFO lane; give urgent work its own lane.
  • MUST NOT size a global per-key cap as if it were per-process worker concurrency.
  • MUST NOT put high-volume work or dispatchers in the same lane as ordinary tasks.
  • MUST NOT ship a job whose only failure recovery is the dead-letter queue; add a reconciler or document the accepted loss.
  • MUST NOT put secrets or personal data in payloads; pass ids.
  • MUST NOT make producer code import worker code; producers enqueue, workers execute.
  • MUST NOT do slow external work on a request path or in an event-forwarding function; enqueue it.
  • MUST NOT treat a dedup id collision as a failure. If finished or failed jobs keep their ids, check that job's state before treating the work as queued.
  • MUST NOT trust a framework's retry counter without checking that no middleware resets it.
  • MUST NOT expect a code deploy to change concurrency or prefetch settings read at worker start; restart the workers.
  • SHOULD NOT put mutable state in a payload; pass ids and re-read when the job runs. Facts fixed when the event happened, such as the price charged, belong in the payload.
  • SHOULD NOT sleep inside a job; defer it through the queue.
  • SHOULD NOT do the work inside a message consumer; enqueue a job, then ack.
  • SHOULD NOT ship bulk work without sizing it against production volume.
  • SHOULD NOT put business logic in processors; call the service that owns the write.
  • SHOULD NOT add an outbox or lease table by default; use job id = row id, enqueue after commit, and a bounded re-enqueue sweep.

Leases

  • MUST NOT renew, complete, or fail leased work without matching your lease token; zero rows means you lost it.
  • MUST NOT set a lease TTL below the job's lock duration, or release a lease with a plain delete; compare-and-delete by token.
  • MUST NOT hold a lease across a deferral that never returns; release first.
  • MUST NOT let a lease-contention path fall through into the guarded work; defer this job with bounded, jittered delay.

Sweeps and bounded iteration

  • MUST NOT loop until empty or default a cap to infinity; cap rows, batches, or time per run, persist position, report remaining work.
  • MUST NOT treat a cursor or stream as a work bound; it bounds memory only.
  • MUST NOT fan out with unbounded Promise.all; bound both the input set and concurrency.
  • MUST NOT scan every entity to find work; read work-item rows through an index-served predicate.
  • MUST NOT restart external listings from page one each run; carry the continuation token and stop on a repeat.
  • MUST NOT let a delayed repair overwrite a newer value; recompute from current source state or compare an existing timestamp instead of adding a version column for it.
  • MUST NOT resume a time window without overlap.
  • MUST NOT hardcode batch size, page size, or window as literals; bind validated config.
  • MUST NOT clear a "needs work" flag unconditionally when a run ends; compare-and-clear against the version you read, or a change that arrived mid-run is lost.
  • MUST NOT self-requeue without a no-progress guard.
  • MUST NOT leave a non-terminal state without a timeout exit, or pick work without an ORDER BY.
  • SHOULD NOT combine unrelated triggers in one sweep with OR; one dispatcher per signal, same idempotent job.
  • SHOULD NOT add a new sweeper for a repair an existing reconciler can make idempotently.

04 同仓库更多 Skills

jonathanong
jonathanong/no-mistakes

rollout-rules

MUST NOT / SHOULD NOT rules for shipping changes safely: feature flags, deploy order across services, API and message compatibility, irreversible actions, and string-referenced config. Use when adding a flag, changing an API or message contract, deploying a change that spans services, or touching money-moving or irreversible actions.

★ 11
jonathanong
jonathanong/no-mistakes

observability-rules

MUST NOT / SHOULD NOT rules for logs, metrics, and alerts: static messages and structured fields, personal data, metric cardinality, fields monitors depend on, absence alerts, and context binding. Use when adding or reviewing logging, metrics, or monitors.

★ 11
jonathanong
jonathanong/no-mistakes

integrations-rules

MUST NOT / SHOULD NOT rules for third-party APIs and inbound webhooks: response classification, retries and idempotency, delivery records, payload mapping, timestamps and units, batch failure policy, and signature verification. Use when calling, parsing, or receiving a partner or vendor API.

★ 11
jonathanong
jonathanong/no-mistakes

typescript-rules

MUST NOT / SHOULD NOT rules for TypeScript, JavaScript, and Node.js: async and promises, errors, mutation, aliases and dead paths, static analysis, process lifecycle, HTTP clients, caches like Redis or Valkey, and package boundaries. Use when writing or reviewing TS/JS or Node code.

★ 11
jonathanong
jonathanong/no-mistakes

security-rules

MUST NOT / SHOULD NOT rules for application security and HTTP APIs: secrets, auth and sessions, SSRF, injection, CSRF, CSP, LLM prompts, response exposure, and API shape. Use when writing or reviewing an endpoint, auth code, secret handling, outbound fetches, or LLM calls.

★ 11
jonathanong
jonathanong/no-mistakes

rust-rules

MUST NOT / SHOULD NOT rules for Rust: lints, test layout, file size, parallelism, hot loops, caching, build hygiene, and performance claims. Use when writing or reviewing Rust code or running heavy cargo builds.

★ 11