Build & Development Commands

• Use modules only. Run go mod tidy after any dependency change.
• Compile with go build ./... (or go install ./...) and always include -trimpath and -buildvcs=true.
• Leverage new Go 1.24 tooling
• go get -tool / tool meta-pattern to manage developer CLIs in go.mod.
• go build -json or go test -json for machine-readable CI output.
• Race & fuzz: go test -race ./... and (where useful) go test -fuzz=Fuzz.*.
• Static analysis: run go vet ./... plus golangci-lint run with a strict config (default fast-linters, style, and security sets).
• Code generation: commit every file produced by go generate ./...; guard the target directories in CI.

Testing Guidelines

• Default to table-driven tests—define an inline slice of structs and iterate with t.Run.
• Assertions use github.com/stretchr/testify/require; prefer require over assert to stop on first failure and keep logs readable.
• Subtests & parallelism: call t.Parallel() in each sub-test when safe; name sub-tests with clear, human-readable strings.
• Coverage: go test -coverprofile=coverage.out && go tool cover -func=coverage.out; fail CI if coverage < 90 %.
• Benchmarks live in *_test.go; run with go test -bench=. -benchmem.
• Fuzz targets go in *_test.go and are gated behind build tag //go:build fuzz.
• No flaky sleeps—use fake clocks or context deadlines instead.

Code Style & Guidelines

• Always run gofmt -s (or goimports); zero diff is mandatory.
• Follow “Go Code Review Comments.” Short package names, upper-camel exported identifiers, error strings without caps, etc.
• Latest language:
• Use generic type aliases where it simplifies APIs.
• Prefer the range f() iterator pattern added in 1.23/1.24 for streaming.
• Opt into map performance tweaks and sync/atomic generics when appropriate.
• Error handling: wrap with %w, expose sentinel errors, and test them with errors.Is/As.
• Context: first param in any request-scoped func (func Do(ctx context.Context, ...)).
• Concurrency: avoid goroutine leaks; use context or errgroup for fan-out.
• Lint gates: enable staticcheck, unused, revive, goimports, errcheck, gosec in golangci-lint config.

Documentation Guidelines

• Doc comments before every exported symbol—first sentence starts with the identifier name and ends with a period.
• Package-level docs live in doc.go; begin with Package foo sentence.
• Examples: include runnable ExampleXxx functions for key APIs.
• README / module docs explain high-level design; reference them from pkg.go.dev badge.
• Keep CHANGELOG anchored to Go releases; note when 1.24-specific features are used.