sota-golang

SOTA Go (2026)

Expert-level rules for producing and auditing production Go. Baseline language version: Go 1.25+, the oldest release still in security support (Go fixes the last two majors; 1.24 left support with 1.26's release, 2026-02). 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 — 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 (e.g. go 1.25.0) for ecosystem compatibility — keep that unless you need newer language features; pin the toolchain directive to the current patch 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).
4. Prefer stdlib. Each dependency must earn its place (see rules/05 supply chain section).
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

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

Finding format

[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

Top-10 non-negotiables

1. Every error is handled or wrapped with %w and context — never discarded with _, never logged-and-ignored on a path that must abort. Compare with errors.Is/errors.As, never string matching. (rules/01)
2. No panics for control flow. panic is for unreachable programmer errors only; servers recover at goroutine boundaries and log. (rules/01)
3. Every goroutine has an owner and a guaranteed exit path — tied to a context.Context, a closed channel, or a WaitGroup/errgroup join. If you can't say how it stops, don't start it. (rules/03)
4. go test -race ./... in CI, always. A race detector failure is a CRITICAL finding, not flaky-test noise. (rules/03, rules/07)
5. http.Server sets ReadHeaderTimeout, ReadTimeout, WriteTimeout, IdleTimeout; clients set timeouts and defer resp.Body.Close() with drain. Default zero timeouts are a DoS. (rules/04)
6. SQL only via parameterized queries (database/sql placeholders, pgx, or sqlc-generated code). String-built SQL is CRITICAL, no exceptions for "internal" values. (rules/05)
7. os/exec with argv lists, never sh -c with interpolated input; file paths validated against a root (os.Root on 1.24+, else filepath.Clean + prefix check after resolving symlinks). (rules/05)
8. context.Context is the first parameter, flows down, is never stored in a struct, and carries only request-scoped metadata — never dependencies. (rules/02)
9. Accept interfaces, return structs; define interfaces at the consumer, keep them small. No premature interfaces "for mocking". (rules/02)
10. govulncheck ./... and golangci-lint gate CI; go.sum committed; dependencies minimal and justified. (rules/05, rules/07)