Expert-level rules for producing and auditing production Go. Baseline language\nversion: Go 1.25+, the oldest release still in security support (Go fixes the\nlast two majors; 1.24 left support with 1.26's release, 2026-02). Feature\nnotes: loop-var scoping from 1.22, b.Loop/os.Root/tool directives from\n1.24, testing/synctest and container-aware GOMAXPROCS from 1.25,\nerrors.AsType and the default-on Green Tea GC from 1.26 — noted where\nrelevant. Every rule states the why; every rules file\nends with an audit checklist of grep/vet/lint patterns.
Two consumers, one source of truth:
\n03, 04, 05.go mod init with a real module path; since 1.26 it writes\nthe previous minor as the go directive (e.g. go 1.25.0) for ecosystem\ncompatibility — keep that unless you need newer language features; pin the\ntoolchain directive to the current patch release. Add golangci-lint\nconfig and a CI step\nrunning go vet, golangci-lint run, go test -race ./...,\ngovulncheck ./... from day one (see rules/07).rules/05 supply\nchain section).-race test; parsers get a fuzz target.sync.Pool complexity, unsafe), leave a // NOTE(sota): comment\nexplaining the trade-off so auditors don't flag it blind.Work through each relevant rules file's audit checklist against the target\nrepo. Run the listed grep/vet/lint commands; confirm each hit manually before\nreporting (greps are recall-oriented, expect false positives).
\n| Severity | \nMeaning | \nExamples | \n
|---|---|---|
| CRITICAL | \nExploitable or guaranteed-incorrect in production | \nSQL built with fmt.Sprintf, command injection via sh -c, unbounded goroutine leak on hot path, InsecureSkipVerify: true, data race confirmed by -race | \n
| HIGH | \nLikely production incident or security weakness | \nMissing 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 | \n
| MEDIUM | \nCorrectness/maintainability hazard, latent bug | \nError strings compared with strings.Contains, context stored in struct, time.After in a loop, map writes without lock under suspected concurrency, missing errors.Is/As | \n
| LOW | \nIdiom/perf debt, works but wrong shape | \nReturning interfaces, util package dumps, missing preallocation on hot path, non-table tests, no t.Parallel | \n
| INFO | \nStyle, doc, or hygiene note | \nNaming, missing doc comments, gofumpt drift | \n
[SEVERITY] file.go:LINE — short title\n Rule: rules/NN-name.md § section\n Evidence: the offending line(s), verbatim\n Impact: one sentence — what goes wrong, under what conditions\n Fix: concrete replacement code or action\n Effort: trivial | small | medium | large\nGroup findings by severity, CRITICAL first. End the audit with: counts per\nseverity, the three highest-leverage fixes, and which checklists were run.
\n| File | \nRead this when... | \n
|---|---|
rules/01-errors.md | \nWriting/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 | \n
rules/02-design.md | \nDesigning packages or APIs: interface placement and size, package layout and internal/, naming, zero values, generics restraint, embedding, functional options, context.Context discipline | \n
rules/03-concurrency.md | \nAnything 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 traps | \n
rules/04-http-services.md | \nBuilding or auditing HTTP servers/clients: all five server timeouts, client timeouts and body hygiene, connection reuse, graceful shutdown, middleware, slog structured logging, request-scoped values | \n
rules/05-security.md | \nAny input crossing a trust boundary: SQL parameterization, os/exec safety, path traversal and os.Root, integer overflow (G115), output encoding (html/template), CSPRNG (crypto/rand vs math/rand), TLS config, unsafe/cgo policy, govulncheck, supply chain and go.sum | \n
rules/06-performance.md | \nLatency/memory work: pprof workflow, testing.B + b.Loop, allocation reduction, strings.Builder, sync.Pool criteria, escape analysis, GOGC/GOMEMLIMIT, PGO | \n
rules/07-tooling-ci.md | \nSetting up or auditing CI and tests: golangci-lint curated config, staticcheck/gofumpt/vet, table tests, t.Parallel correctness, testcontainers, golden files, fuzzing, go.mod hygiene and tool directives. Test strategy — suite shape, TDD, doubles, test data, flake policy — lives in sota-testing; load it for any build that writes logic. This file owns Go runner mechanics only. | \n
%w and context — never\ndiscarded with _, never logged-and-ignored on a path that must abort.\nCompare with errors.Is/errors.As, never string matching. (rules/01)panic is for unreachable programmer\nerrors only; servers recover at goroutine boundaries and log. (rules/01)context.Context, a closed channel, or a WaitGroup/errgroup join. If\nyou can't say how it stops, don't start it. (rules/03)go test -race ./... in CI, always. A race detector failure is a\nCRITICAL finding, not flaky-test noise. (rules/03, rules/07)http.Server sets ReadHeaderTimeout, ReadTimeout, WriteTimeout,\nIdleTimeout; clients set timeouts and defer resp.Body.Close() with\ndrain. Default zero timeouts are a DoS. (rules/04)database/sql placeholders, pgx,\nor sqlc-generated code). String-built SQL is CRITICAL, no exceptions for\n\"internal\" values. (rules/05)os/exec with argv lists, never sh -c with interpolated input;\nfile paths validated against a root (os.Root on 1.24+, else\nfilepath.Clean + prefix check after resolving symlinks). (rules/05)context.Context is the first parameter, flows down, is never stored in\na struct, and carries only request-scoped metadata — never dependencies.\n(rules/02)rules/02)govulncheck ./... and golangci-lint gate CI; go.sum committed;\ndependencies minimal and justified. (rules/05, rules/07)