Production Go

Production Go

Contract

Inputs

1. The Go task (required): code to write, a diff to review, a bug to diagnose, or a design question.
2. The module root (required when it is not the current directory): supplies go.mod and its go version line.
3. The project type (optional): CLI, service, library, or other; inferred from the layout when omitted.
4. Inherited-reference boundary (note): the references' feature tags [1.N] and library picks come from the research horizon named in each file's verification stamp; they are not blanket-revalidated on load. Before a shipped claim leans on one, check it against the installed toolchain (go version) and current upstream docs.

Procedure

1. Fix the Go baseline. The grounded pin is Go 1.27.1 (current stable, released 2026-09-01). Go maintains only the two newest major releases, so 1.26 is still supported and 1.25 is end of life. The go line in the module's go.mod is the feature ceiling: never emit a feature newer than that line, and remember that bumping it can change runtime behavior through GODEBUG defaults. Done when: the effective Go version is named.
2. Route the task. Match the project type and topic to the reference table below and load every file the task touches in the same turn. For a topic the table does not name, look it up in references/index.md, the alphabetical topic index. Done when: each relevant reference is loaded.
3. Apply the conventions. Done when: the code or review reflects each convention that applies.
   • Philosophy: clarity over cleverness; composition over inheritance; accept interfaces, return structs; make the zero value useful; errors are values; every goroutine gets a shutdown path; stdlib before third-party.
   • Project structure: start flat and add structure only when the project demands it; cmd/ holds thin main() packages, internal/ holds private code the compiler keeps unimportable, pkg/ is optional public library surface; group by domain, never by technical layer; a directory is a package.
   • Naming: packages are short, lowercase, one word; exported identifiers are MixedCaps, unexported are mixedCaps; single-method interfaces take the -er suffix; getters drop the Get prefix; acronyms stay all-caps (URL, HTTP, ID); error variables are ErrXxx, error types are XxxError; ctx context.Context is always the first parameter.
   • Errors: check every error; wrap with fmt.Errorf("doing X: %w", err); keep messages lowercase without punctuation; log.Fatal and panic do not belong in library code; wrap third-party errors with %v so callers are not coupled to the concrete type.
   • Concurrency: every goroutine checks ctx.Done(); prefer errgroup over a raw sync.WaitGroup; size channels unbuffered for synchronization, buffered 1 for signals, buffered N for known-bounded work; a panic in a goroutine kills the whole process.
   • Interfaces and structs: keep interfaces to one to three methods and define them at the use site; verify implementations with var _ Iface = (*Impl)(nil); use functional options for constructors with optional config; keep receiver types consistent within a type.
   • Dependencies: wire constructors in main() by hand; manual DI is the default at every size. Consider a DI generator only on a documented decision, per references/project-patterns.md (compile-time DI): google/wire is archived (2025) and its maintained fork is unproven at scale.
   • Logging: slog is the default; log an error or return it, never both.
   • HTTP: net/http method patterns and path parameters cover most APIs; set ReadTimeout, WriteTimeout, and IdleTimeout on every server; drain and close response bodies.
   • Database: parameterize every query; set pool limits; defer rows.Close() and defer tx.Rollback(ctx).
   • Testing: table-driven tests with subtests; run go test -race -count=1 ./....
   • Generics: use them for data structures and to replace any; prefer a plain interface when the code only calls methods.
4. Run the review checklist. The code is not done until it is gofmt-clean, builds, vets, and passes go test -race and golangci-lint (v2 config schema; migrate a v1 config with golangci-lint migrate). Scan the anti-pattern table below and fix every row that applies. When emitting code without tool access, hold the same bar by hand: gofmt-formatted, with only the imports the code uses. Done when: every gate passes or its failure is reported.
5. Verify by the benchmark method. Grade the change the way the source's companion benchmark measured it: the Go toolchain itself (go build, go vet, go test, golangci-lint) plus a behavioral test the implementation has not seen, inside a bounded number of correction rounds, against an external baseline such as the pre-change code. This states the method, not a result; the source's published score deltas are not asserted here. Done when: the toolchain gates and the behavioral check pass, or the correction budget is spent and the residual is reported.

Anti-patterns

Library defaults

References

Failure and recovery

Output

Go code or review feedback that follows the conventions above, with the toolchain gate results and the behavioral check outcome, or the named blocker.