---
name: production-engineering
description: >-
  Use only when a request establishes operational risk in deployed or shared software: real data or traffic, side effects, concurrency or overload, dependency failure, public contracts, rollout, recovery, or production diagnosis. Backend, messaging, or external I/O alone are insufficient. Excludes local-only work, frontend-only work, and pure algorithms.
---

# Production Engineering

Move from "the function runs" to "the system behaves correctly within explicit or clearly labeled operating assumptions, fails safely, can be diagnosed, and can recover." Derive obligations from actual risk rather than labels such as prototype, MVP, or production-ready.

## Core obligations

- Do not defer correctness, bounded resources, failure handling, or essential diagnostics that the requested scope needs.
- Match effort to impact and reversibility. A low-volume internal service needs fewer mechanisms than a public high-volume path, but growing resources still need limits.
- Distinguish declared targets, observations, derivations, assumptions, and unknowns. Never present an assumption as measured capacity.
- A request to explain, review, or diagnose does not authorize implementation or external mutation.
- Production data, traffic, configuration, queues, caches, and databases require explicit scope and authorization before mutation.

## Analyze the path

Identify the trigger, success result, critical path, state reads, external calls, persistent side effects, and result confirmation. Classify the workload as synchronous, consumer, scheduled, batch, stream, fan-out, or mixed.

Ask only when missing information changes correctness semantics, architecture, an irreversible data decision, or material cost. Use labeled, reversible defaults for worker counts, batch sizes, pool sizes, and timeouts.

Every resource that grows with traffic, input, tenants, failures, or time needs:

- a limit;
- an observable saturation signal;
- defined behavior at the limit;
- a recovery condition.

## State and failure

Classify state as authoritative, derived, cache, message, coordination, temporary, or aggregate. Define acceptable loss, duplication, staleness, ordering, and compensation. Treat "at-least-once delivery plus idempotent side effects" as a common achievable business-once model; do not claim exactly-once casually.

For each dependency, account for queue and pool wait, deadline, cancellation, retry amplification, and degraded behavior. Retries require a time budget, attempt limit, error classification, backoff, jitter, and idempotency.

## Compatibility decision gate

Inspect public APIs, SDKs, messages, configuration, files, caches, telemetry, and historical data for observable contract changes. If a public contract is affected and the user has not chosen a strategy, explain the impact before implementation and ask them to choose:

1. replace directly;
2. preserve compatibility.

Data migration is a separate decision, not a third compatibility strategy. Private implementation changes with unchanged external behavior can proceed.

## Diagnostics, lifecycle, and evidence

Provide risk-proportionate metrics, traces, and structured logs for critical transitions, dependencies, protection mechanisms, and recovery. Logging is a diagnostic side path; it must not become an unbounded or indefinitely blocking dependency of the business path.

Check startup, readiness, reconnection, backlog catch-up, rolling restart, and graceful shutdown when the task owns long-lived work. Select verification from unit, boundary, integration, concurrency, benchmark, load, fault, mixed-version, or production observation according to the actual claim.

## Reference router

- Read [references/workload-and-capacity.md](references/workload-and-capacity.md) for load, concurrency, queues, batches, fan-out, skew, or incomplete capacity evidence.
- Read [references/state-and-concurrency.md](references/state-and-concurrency.md) for persistent writes, consumers, idempotency, locks, state machines, retries with side effects, or multi-instance races.
- Read [references/dependencies-and-resilience.md](references/dependencies-and-resilience.md) for databases, caches, external APIs, storage, messaging, slow I/O, deadlines, retries, overload, or degradation.
- Additionally read [references/technologies/external-systems.md](references/technologies/external-systems.md) only for the product-specific section actually used.
- Read [references/compatibility-rollout-and-rollback.md](references/compatibility-rollout-and-rollback.md) for public contract changes, historical data, mixed versions, rollout, migration, or rollback.
- Read [references/runtime-diagnostics.md](references/runtime-diagnostics.md) when designing or changing metrics, tracing, logging, audit events, overload signals, or diagnostic failure behavior.
- Read [references/lifecycle-and-recovery.md](references/lifecycle-and-recovery.md) for background work, reconnects, warm-up, backlog recovery, schedulers, multi-instance deployment, or graceful shutdown.
- Read [references/verification-and-handoff.md](references/verification-and-handoff.md) only when the verification choice is non-obvious, the user asks for evidence or capacity guarantees, or the result will guide a risky release.

Report only task-relevant operating assumptions, protection and recovery behavior, diagnostics, compatibility constraints, evidence, and remaining risks. Do not use labels such as "production-grade" or "scalable" instead of boundaries and evidence.