Go: Production Engineering

View saved version →

---
name: go-language-engineering
description: "Use for local Go semantics, errors, interfaces, generics, and data. Do not use for exported API evolution."
license: Apache-2.0
compatibility: "Go 1.24 or newer; current guidance targets Go 1.25 and 1.26, with older forms labeled legacy."
---

# Go language engineering

Make the code expose ownership, mutation, failure, and control flow. The specification defines validity; conventions are evidence about clarity, not universal laws.

## Establish the local contract

Before editing, identify the inputs, zero-value behavior, aliasing, mutation, error identity, concurrency exposure, and exported compatibility. Follow established public behavior unless the request changes it.

## Choose representations from invariants

- Use a value when copying is meaningful and identity is irrelevant; use a pointer when shared identity, mutation, or absence is contractual.
- Treat slices and maps as descriptors over shared storage. Copy at trust or ownership boundaries when later mutation would violate the contract.
- Preserve `nil` versus empty only when serialization or API behavior distinguishes them.
- Use a struct when fields form one invariant; avoid parallel slices and loosely related maps.
- Introduce generics only when one algorithm genuinely applies across types without erasing domain meaning.
- Define interfaces at the consumer boundary and keep them as small as the required behavior permits.

## Make failure inspectable

- Add context with `%w` when callers need causal inspection; use `%v` when intentionally hiding the underlying identity.
- Choose sentinel, typed, or opaque errors from the caller decision, not from habit.
- Return or log an error at one owning boundary. Never string-match an error contract.
- Reserve panic for violated internal invariants or startup failure where continuing is unsafe; recover only at an isolation boundary.

## Keep control flow causal

Prefer guard clauses when they make the main path visible. Keep variables in the smallest useful scope, but do not compress logic until shadowing or mixed responsibilities become hard to see. A switch is useful when it represents one classification; chained conditions are fine when they express a sequence.

## Reject universal style claims

Do not require pointers for every struct, interfaces for every dependency, constructors for every type, channels over mutexes, or named returns by default. Each is conditional. Preserve compatible repository conventions when alternatives are equally correct.

Read [references/decision-record.md](references/decision-record.md) for API, generics, and error counterexamples. When a slice, map, view, or pooled buffer crosses a lifetime or trust boundary, read [references/memory-ownership-and-aliasing.md](references/memory-ownership-and-aliasing.md) and name the borrow, transfer, sharing, or snapshot contract.

## Output contract

For implementation, make the smallest coherent change and keep semantic ownership visible. For review, cite the concrete input or call path that breaks an invariant. Separate correctness from optional style.

Referenced files: 5

View saved version →

---
name: go-performance-and-diagnostics
description: "Use for measured Go CPU, memory, allocation, contention, latency, and benchmarks. Do not use speculatively."
license: Apache-2.0
compatibility: "Go 1.24 or newer; runtime profiles and tool output are version-sensitive."
---

# Go performance and diagnostics

Optimize a measured constraint, not a code pattern.

## Establish the workload

Record input distribution, offered arrival rate, open- versus closed-loop generation, concurrency, duration, warmup, dependencies, hardware, Go version, `GOMAXPROCS`, achieved throughput, dropped/deadline-expired work, allocations, and error rate. Measure latency from intended arrival when production queueing matters; closed-loop generators can hide stalls through coordinated omission. Reproduce the symptom before changing code.

## Follow the dominant resource

- CPU profile: inspect cumulative and flat cost, then verify inlining and call context.
- Heap/allocation profile: distinguish live memory from allocation churn and retained ownership.
- Mutex/block profiles: find contention and waiting, not merely hot functions.
- Goroutine profile: inspect leaks, fan-out, and blocked resource owners.
- Trace: diagnose scheduler latency, GC interaction, network blocking, and critical paths.
- Database/network evidence: local CPU profiles cannot explain remote queueing alone.

## Change one causal mechanism

Common valid moves include capacity hints for known sizes, avoiding repeated conversions, batching within latency bounds, reducing contention scope, changing algorithms, and removing avoidable reflection or formatting from hot paths. Preserve ownership and correctness; pooling can retain memory or create races.

Compare before and after with repeated benchmarks and confidence-aware tooling. Report effect size, allocations, variance, and costs transferred to memory, tail latency, complexity, or dependencies.

Read [references/diagnostic-tree.md](references/diagnostic-tree.md) for profile selection and benchmark traps. For rising RSS, container OOMs, GC pressure, or `GOMEMLIMIT` changes, read [references/memory-and-gc.md](references/memory-and-gc.md). Before exposing or collecting live diagnostics, read [references/production-profiling.md](references/production-profiling.md) for access, sampling, interference, cohort, and artifact controls.

## Output contract

Lead with the measured bottleneck and evidence. Do not claim improvement from code appearance or one noisy benchmark run.

Referenced files: 6

View saved version →

---
name: go-production-operations
description: "Use for Go process/deployment lifecycle, health, telemetry, drain, Kubernetes, and releases. Do not use for domain logic."
license: Apache-2.0
compatibility: "Go 1.24 or newer; deployment-platform behavior must be verified against the active environment."
---

# Go production operations

Startup, readiness, telemetry, overload signals, and shutdown are externally observable service behavior.

## Startup

Parse and validate configuration before serving. Distinguish required secrets, immutable startup settings, and safely reloadable values. Every reload validates a complete candidate snapshot before atomic publication and retains the last known-good state on failure. Initialize dependencies in ownership order and return startup errors from a testable `run` path rather than hiding work in `init`.

## Telemetry

Use structured events with stable names and bounded fields. Metrics labels must have bounded cardinality. Propagate trace context across supported protocols, record errors without secrets, and correlate request identity without treating it as authorization. Define signals for success, rejection, overload, dependency failure, retry, ambiguity, and degraded behavior.

Make telemetry export a bounded failure domain. Choose queue and batch limits, drop or sampling policy, request-path blocking behavior, exporter deadlines, and shutdown flush budget explicitly. Exporter outage must not create unbounded memory or stall the service indefinitely. Expose dropped records, queue saturation, sampling, and export failure through an independent bounded signal; absence of backend data is otherwise indistinguishable from a quiet system.

## Health and overload

Readiness means the instance can safely accept its intended traffic. Liveness means restart is likely to restore progress. Do not make liveness fail for every downstream outage. Keep probes cheap and reserve enough capacity for diagnosis and drain.

## Shutdown

On termination: stop or mark admission, drain accepted work, stop background producers, wait within the platform budget, flush bounded telemetry, and close dependencies after their users. Surface forced termination and abandoned work.

Use `go-service-boundaries` as well when shutdown correctness depends on HTTP bodies, streams, protocol draining, or client/server resource ownership.

## Delivery

Build reproducibly, pin CI inputs, generate checksums and provenance, scan archives, run as a non-root minimal image where practical, set realistic resources, and design rolling updates for mixed versions and rollback.

Read [references/incident-contract.md](references/incident-contract.md) for lifecycle, cardinality, backpressure, and telemetry-loss traps.

For staged deployment, controller progress, canary evidence, data migration, and rollback safety, read [references/rollout-and-rollback.md](references/rollout-and-rollback.md). Platform availability is necessary rollout evidence, not proof that the new artifact preserves business or data invariants.

## Output contract

State the lifecycle order, deployment assumptions, and signals that prove each state. Avoid copied Kubernetes or logging templates without causal fit.

Referenced files: 5

View saved version →

---
name: go-project-and-api-design
description: "Use for exported Go APIs, packages, modules, versioning, and compatibility. Do not use for local semantics or wire protocols."
license: Apache-2.0
compatibility: "Go 1.24 or newer; module and toolchain behavior must match the repository's declared versions."
---

# Go project and API design

Organize code around stable behavior and dependency direction, not a universal directory tree.

## Map the dependency graph

Identify the domain decision, its inputs and effects, the outer mechanisms that provide them, and the package that owns each contract. Core behavior should not need to import HTTP, SQL, a broker, or process bootstrap merely to be exercised.

## Design packages

- Give a package one coherent reason to change and a name describing what it provides.
- Keep `internal/` boundaries deliberate; they control import visibility, not architecture quality.
- Avoid catch-all `util`, `common`, `models`, and `interfaces` packages.
- Put interfaces with consumers unless an external implementation contract requires otherwise.
- Use `cmd/<name>` for multiple binaries when useful; keep `main` thin enough that startup can report errors deterministically.

## Design APIs from caller decisions

- Make zero values useful when that is cheap and unambiguous; otherwise require construction.
- Use functional options for a growing set of independent optional settings, not required arguments or every constructor.
- Validate immutable configuration at startup and distinguish secret values from ordinary settings. For reloadable configuration, parse and validate a complete candidate snapshot before atomic publication; retain the last known-good snapshot on failure.
- Return concrete types unless callers need substitution at that boundary.
- Preserve error, cancellation, and ownership contracts in names and documentation.

## Manage evolution

Treat exported Go APIs, serialized fields, schemas, config keys, CLI flags, and default behavior as compatibility surfaces. For breaking storage or protocol changes, design expand/migrate/contract steps that tolerate mixed versions and rollback.

Pin CI and release inputs by immutable versions. Keep generated files reproducible and make the source of truth explicit. Do not add dependencies or frameworks without a demonstrated capability or maintenance benefit.

Read [references/api-evolution.md](references/api-evolution.md) for compatibility and constructor decisions. For a public-module release or major-version migration, use [references/module-release-compatibility.md](references/module-release-compatibility.md) to inventory consumer-visible contracts and prove the cutover outside the producer repository.

## Output contract

State the dependency invariant, compatibility constraints, and smallest design that satisfies them. Avoid architecture ceremony, speculative abstractions, and repository-wide reshaping.

Referenced files: 5

View saved version →

---
name: go-security-hardening
description: "Use for generic Go exploit prevention: authz, SSRF, files, commands, crypto, secrets, and supply chain. Do not use for PCI scope."
license: Apache-2.0
compatibility: "Go 1.24 or newer; security-sensitive APIs and dependency advisories require current verification."
---

# Go security hardening

Trace data and authority from an attacker-controlled input to a protected effect. Do not report a vulnerability without a reachable mechanism.

## Define the trust boundary

Identify principals, assets, entrypoints, authorization decisions, privileged operations, secrets, persistence, outbound destinations, and audit evidence. Validate syntax and size at parsing; enforce authorization at the resource/action boundary.

## High-risk Go paths

- Build SQL with parameters; identifiers require allowlists or trusted construction.
- Treat URLs, redirects, DNS, proxies, and resolved IPs as SSRF decisions; prevent access to forbidden networks across redirects and rebinding.
- Constrain filesystem paths after canonicalization and open through an intended root; consider symlink and race behavior.
- Avoid shell interpretation. If process execution is necessary, pass fixed executables and structured arguments with a bounded context.
- Bound decoders, archive expansion, regex work, decompression, multipart data, and recursive structures.
- Use maintained cryptographic protocols and `crypto/rand`; separate keys from ciphertext and rotate through explicit versions.
- Keep secrets and sensitive payloads out of errors, logs, metrics, traces, URLs, and idempotency keys.

## Supply chain and artifacts

Minimize dependencies, verify modules and generated inputs, pin CI actions by immutable revisions, scan release archives, and prohibit unreviewed executable resources from published skills. A checksum proves identity, not trustworthiness.

For dependency or release-pipeline changes, read [references/dependency-integrity.md](references/dependency-integrity.md). Distinguish module authentication, cache verification, vulnerability reachability, source trust, build-input completeness, and artifact provenance; none substitutes for the others.

Read [references/threat-paths.md](references/threat-paths.md) for concrete review paths.

When an HTTP backend derives identity, scheme, host, or client certificate from proxy metadata, read [references/trusted-proxy-identity.md](references/trusted-proxy-identity.md). Treat forwarded fields as assertions whose authority comes from an authenticated, non-bypassable proxy path—not from the header name.

When designing or rotating encryption at rest, read [references/envelope-encryption-lifecycle.md](references/envelope-encryption-lifecycle.md). Separate KEK rewrap, DEK replacement, and algorithm migration; they repair different risks and require different evidence before old keys retire.

When Go launches another program, read [references/process-execution-boundary.md](references/process-execution-boundary.md). Fix executable identity, avoid unintended shell interpretation, minimize inherited environment and descriptors, bound I/O, and own cancellation, reaping, and any descendant process set explicitly. `CommandContext` and `WaitDelay` are lifecycle mechanisms, not a sandbox or proof that grandchildren stopped.

## Output contract

For each finding, state attacker control, required preconditions, protected effect, impact, and smallest correction. Separate exploitability from defense-in-depth.

Referenced files: 8

View saved version →

---
name: go-service-boundaries
description: "Use for Go HTTP/gRPC/GraphQL/OpenAPI resources, bodies, streams, and shutdown. Do not use for retry policy."
license: Apache-2.0
compatibility: "Go 1.24 or newer; protocol and library behavior must be verified against deployed versions."
---

# Go service boundaries

Treat every service adapter as a trust, resource, and compatibility boundary. Keep domain behavior independent of transport encoding while preserving protocol-specific semantics.

## Define the boundary

Record authentication and authorization ownership, request and response size limits, deadline source, streaming behavior, concurrency admission, error mapping, versioning, and shutdown policy. Validate untrusted input once before constructing a domain command.

## HTTP

Use explicit `http.Server`, client, and transport ownership. Bound headers and finite bodies. Reuse clients and close response bodies. Propagate `r.Context()`. Choose total, phase, or idle timeouts from endpoint semantics; a global write timeout can break streaming. Treat redirects and proxy headers as new trust decisions.

For JSON APIs, bound the body before decoding, accept exactly the documented media and content encodings, decode one complete value into a private typed DTO, and apply no domain effect after any decode or validation error. Unknown-field tolerance is a versioning choice; duplicate critical names are an interoperability and security ambiguity that `encoding/json` v1 does not reject by default. Read [references/http-json-message-boundaries.md](references/http-json-message-boundaries.md) for the strict boundary procedure.

Treat a transport configuration as immutable after concurrent use begins. When TLS identity, trust roots, proxy, dial policy, or another connection-affecting setting changes, construct a private replacement and publish it with every policy decision that must share its version. Each admitted operation captures one generation. Stop new admission to the old generation, let its in-flight operations keep their captured client, close its idle connections, and release it only when its owned streams and bodies are done. A pointer swap without old-generation retirement prevents mixed configuration but still leaks connection state.

## gRPC

Preserve status codes, cancellation, metadata trust, message limits, and stream lifecycle. Reuse connections. Put authentication, tracing, and recovery in ordered interceptors, but keep domain decisions out of them. A retry policy must respect method idempotency and the caller's deadline.

## GraphQL and OpenAPI

Keep resolvers and generated handlers thin. Bound query complexity and pagination. Batch only within request lifetime and authorization scope. Treat schema nullability, enums, field removal, and generated client expectations as public contracts. Generated OpenAPI is evidence only when it matches runtime behavior.

## Shutdown and ambiguity

Stop admission, drain accepted work within the platform budget, terminate application-owned streams, then close dependencies. A missing response after a request may mean an unknown remote outcome; do not convert transport uncertainty into a known business failure.

Read [references/protocol-matrix.md](references/protocol-matrix.md) for protocol-specific failure, versioned client cutover, and test cases.

## Output contract

Change the smallest owning adapter. Report exact protocol, resource, trust, or compatibility failures, including the triggering request and observable result.

Referenced files: 5

View saved version →

---
name: go-testing-and-verification
description: "Use when asked to design or debug Go tests, fuzzing, race/leak checks, or deterministic verification. Do not use for profiling."
license: Apache-2.0
compatibility: "Go 1.24 or newer; testing/synctest guidance targets Go 1.25 and 1.26."
---

# Go testing and verification

Start with the invariant and the cheapest environment that can falsify it. A test shape is not a quality goal by itself.

## Select evidence by failure mode

- Direct unit tests for pure decisions and edge cases.
- Integration tests with the real database, broker, filesystem, or protocol when their semantics are the claim.
- Contract tests for public request, response, schema, and compatibility behavior.
- Fuzz tests for parsers, decoders, canonicalization, state transitions, and algebraic properties.
- Race-enabled tests for executed concurrent paths; they are not proof over unexecuted schedules.
- Leak checks for owned goroutines after cancellation and shutdown.
- Deterministic time and synchronization rather than sleeps; use `testing/synctest` where supported.

## Build a strong oracle

Assert externally meaningful state, output, side effects, and errors. Prefer invariant checks over call choreography. Make fixtures expose the failure: concurrent starts, crash windows, duplicate identities, partial reads, invalid encodings, and boundary sizes.

Parallel tests must not share mutable globals, environment, ports, clocks, random sources, or fixtures without explicit isolation. Call `t.Helper()` in helpers and preserve useful failure context.

## Fuzz responsibly

Seed representative valid and invalid values. Keep targets deterministic, fast, and independent across calls. Persist minimized failures as regressions. A fuzz target without a semantic property often discovers only panics, not wrong results.

Read [references/oracle-design.md](references/oracle-design.md) for distributed and financial oracles.

For timer, deadline, or asynchronous goroutine tests on Go 1.25 or 1.26, read [references/deterministic-concurrency.md](references/deterministic-concurrency.md). A `synctest` bubble virtualizes only work it owns; external I/O and goroutines are not made deterministic merely because the assertion runs inside `synctest.Test`.

## Output contract

Name the invariant, chosen test layer, and remaining blind spots. Do not inflate coverage metrics or mock interactions into claims of system correctness.

Referenced files: 5

View saved version →

---
name: review-go-engineering-change
description: "Use for general Go diff/PR review. Do not use when distributed-systems or fintech correctness dominates."
license: Apache-2.0
compatibility: "Go 1.24 or newer; changed repository contracts outrank generic conventions."
---

# Review a Go engineering change

Review behavior created by the diff, not resemblance to a checklist.

## Establish scope

Inspect changed code and only the callers, callees, schemas, configs, tests, and history needed to determine the changed contract. State the input, decision, side effects, output, and compatibility surfaces.

Load the focused engineering skills for the risks actually present; this review skill sets finding quality and precedence rather than duplicating their conditional guidance.

## Trace applicable risk

- Language: aliasing, mutation, nil and zero values, error identity, interface method sets, generics, overflow.
- API: exported behavior, serialization, config defaults, mixed versions, migrations, rollback.
- Boundary: validation, authorization, body/stream lifetime, cancellation, protocol status, shutdown.
- Verification: missing oracle for a changed invariant, nondeterminism, mocks standing in for claimed dependency semantics.
- Performance: unbounded allocation or work on a reachable path; do not report speculative micro-optimization.
- Security: attacker-controlled input reaching authority, storage, execution, filesystem, or network destinations.
- Operations: readiness, telemetry, overload, recovery, and incident ambiguity.

When concurrency, persistence, messaging, leases, or money movement dominates the change, route to the corresponding distributed or fintech review skill.

## Write findings

Each finding needs a tight changed line, trigger, impact, causal mechanism, and smallest correction. Rank severity from impact and plausible reachability. Report defects and material risks; omit preferences unless requested. Do not demand tests, interfaces, comments, abstractions, or retries by default.

Read [references/finding-standard.md](references/finding-standard.md) before finalizing findings.

## Output contract

Lead with actionable findings in descending severity. If none exist, say so and name only significant residual uncertainty. Never claim a check ran when it did not.

Referenced files: 4