/sota-golang

name: sota-golang
description: State-of-the-art Go engineering rules (supported Go releases) that Claude applies when writing new Go code or auditing existing Go code. Covers error handling, interface/package design, goroutine and channel correctness, net/http hardening, security (SQL, exec, path traversal, CSPRNG, TLS, supply chain), performance (pprof, allocations, GC, PGO), and tooling/CI. Trigger keywords - Go, golang, goroutine, channel, go.mod, errgroup, context.Context, pprof, govulncheck, net/http, slog. Use for BOTH building Go services/libraries/CLIs and reviewing or auditing Go codebases.

SOTA Go (2026)

Expert-level rules for producing and auditing production Go. Target a supported Go release: Go supports the two latest majors (1.25 left support when 1.27 shipped, 2026-08) — verify the supported pair at go.dev/doc/devel/release. Feature notes: loop-var scoping from 1.22, `b.Loop`/`os.Root`/tool directives from 1.24, `testing/synctest` and container-aware GOMAXPROCS from 1.25, `errors.AsType` and the default-on Green Tea GC from 1.26, the GA `goroutineleak` profile and `encoding/json` backed by v2 from 1.27 — noted where relevant. Every rule states the *why*; every rules file ends with an audit checklist of grep/vet/lint patterns.

Purpose

Two consumers, one source of truth:

• **BUILD mode** — generating new Go code: follow the rules as defaults, not

suggestions. Deviate only with an explicit comment justifying it.

• **AUDIT mode** — reviewing existing Go code: hunt violations using the audit

checklists, classify by severity, report in the finding format below.

BUILD mode

1. Before writing code, read the rules files relevant to the task (see index). A service touching HTTP + DB + goroutines needs `03`, `04`, `05`. 2. Apply the **top-10 non-negotiables** (below) unconditionally. 3. New modules: `go mod init` with a real module path; since 1.26 it writes the previous minor as the `go` directive (`go 1.(N-1).0` under toolchain 1.N) for ecosystem compatibility — keep that unless you need newer language features; pin the `toolchain` directive to the latest patch release (verify at go.dev/doc/devel/release). Add `golangci-lint` config and a CI step running `go vet`, `golangci-lint run`, `go test -race ./...`, `govulncheck ./...` from day one (see [`rules/07`](rules/07-tooling-ci.md)). 4. Prefer stdlib. Each dependency must earn its place (see [`rules/08`](rules/08-supply-chain.md) §1, supply chain). 5. Write table tests alongside the code, not after. Exported behavior gets a test; concurrency gets a `-race` test; parsers get a fuzz target. 6. When generating code that violates a rule for a legitimate reason (e.g. `sync.Pool` complexity, `unsafe`), leave a `// NOTE(sota):` comment explaining the trade-off so auditors don't flag it blind.

AUDIT mode

**Coverage:** every `rules/` file's Audit checklist applies in AUDIT mode. Mark one *not applicable* only with its reason in the report — never skip a file because the thing it checks for is absent, since that absence may be the finding.

Work through each relevant rules file's audit checklist against the target repo. Run the listed grep/vet/lint commands; confirm each hit manually before reporting (greps are recall-oriented, expect false positives).

Severity conventions

| Severity | Meaning | Examples | |---|---|---| | **CRITICAL** | Exploitable or guaranteed-incorrect in production | SQL built with `fmt.Sprintf`, command injection via `sh -c`, unbounded goroutine leak on hot path, `InsecureSkipVerify: true` on a user-network client or code channel, data race confirmed by `-race` | | **HIGH** | Likely production incident or security weakness | Missing `http.Server` timeouts, no ctx cancellation on blocking goroutine, unchecked integer truncation on attacker input (G115), `resp.Body` never closed, panic for control flow in a server | | **MEDIUM** | Correctness/maintainability hazard, latent bug | Error strings compared with `strings.Contains`, context stored in struct, `time.After` in a hot loop, map writes without lock under suspected concurrency, missing `errors.Is/As` | | **LOW** | Idiom/perf debt, works but wrong shape | Returning interfaces, `util` package dumps, missing preallocation on hot path, non-table tests, no `t.Parallel` | | **INFO** | Style, doc, or hygiene note | Naming, missing doc comments, gofumpt drift |

Finding format

Expands the router's canonical row (`file:line | rule | severity | effort | fix`, which wins on a cross-domain roll-up); evidence block and report order: [`sota` rules/03](../sota/rules/03-audit-findings.md) §2 and §5.

[SEVERITY] file.go:LINE — short title
  Rule: rules/NN-name.md § section
  Evidence: the offending line(s), verbatim
  Impact: one sentence — what goes wrong, under what conditions
  Fix: concrete replacement code or action
  Effort: trivial | small | medium | large

Group findings by severity, CRITICAL first. End the audit with: counts per severity, the three highest-leverage fixes, and which checklists were run.

Rules index

| File | Read this when... | |---|---| | [`rules/01-errors.md`](rules/01-errors.md) | Writing/reviewing any error path: wrapping with `%w`, `errors.Is/As`, sentinel vs typed errors, **in-band sentinels (absence encoded as `-1`/`0`/`""`)** and comma-ok, panic/recover policy, error API design for libraries vs apps | | [`rules/02-design.md`](rules/02-design.md) | Designing packages or APIs: interface placement and size, package layout and `internal/`, naming, zero values, generics restraint, embedding, functional options, `context.Context` discipline, numeric edges (NaN/Inf from `ParseFloat`, integer divide-by-zero, `MinInt` / -1) | | [`rules/03-concurrency.md`](rules/03-concurrency.md) | Anything with `go`, `chan`, `sync`, or `select`: goroutine lifecycle ownership, leak catalog, errgroup fan-out, channels-vs-mutex decision, race patterns, worker pools, semaphores, `time.After` tr