go-conventions

name	go-conventions
description	Apply Go project conventions — Go 1.25.x toolchain pinned via toolchain directive and GOTOOLCHAIN=local, vendored deps via go mod vendor, golangci-lint v2 strict (~50 enabled linters), gofmt + goimports, gosec + semgrep + govulncheck + CodeQL static analysis, race-detector + fuzz-capable testing, reproducible-build flags (-trimpath, -buildid=) for TEE-attested binaries, cmd/ + internal/ + pkg/ layout, stdlib-first dependencies (log/slog, net/http, google/uuid, google.golang.org/protobuf). Use when starting a Go project, writing or reviewing Go code, configuring Go tooling, doing TEE-attested or reproducible builds, or evaluating compliance with these defaults. Co-activates with running-tdd-cycles, reviewing-changes, and engineering-philosophy.
allowed-tools	Read, Edit, Write, Grep, Glob, Bash(go *), Bash(golangci-lint *), Bash(gofmt *), Bash(goimports *), Bash(gosec *), Bash(govulncheck *), Bash(semgrep *), Bash(make *)
globs	**/*.go
paths	**/*.go

Default Stack

If the repo doesn't define its own tooling, use:

• Go — latest stable minor (1.25.x floor). Pin with toolchain go1.25.X in go.mod, set GOTOOLCHAIN=local in CI so the declared toolchain is used verbatim.
• go mod vendor — vendor deps committed to repo. Enables reproducible + airgapped builds; CI runs go build -mod=vendor.
• GitHub Actions — CI/CD. Pin every action by commit SHA, not tag.
• golangci-lint v2 — linting. Strict preset (see below). Run via golangci-lint run -c .golangci.yml.
• gofmt + goimports — formatting. goimports is enabled as a formatter in .golangci.yml.
• gosec — security static analysis. Runs in CI (SARIF upload to GitHub code scanning).
• semgrep — additional SAST with r/default r/go r/dgryski r/trailofbits rulesets.
• govulncheck — official Go vulnerability database scan. Preferred over Nancy (no external account).
• CodeQL — GitHub's SAST for Go.
• modernize — golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize checks for outdated idioms.

Build Discipline

• CGo policy. Default CGO_ENABLED=0 for pure-Go packages. Enable only when a specific package needs it; tag those files with //go:build cgo so pure-Go builds still work.
• Build tags for runtime variants. Use explicit tags (e.g. //go:build tdx, //go:build sevsnp) when the same binary has multiple platform-specific implementations. Exactly one implementation per build.
• Reproducible builds. Default build flags:

  go build -trimpath -buildvcs=false -ldflags "-s -w -buildid=" ./...
  

  -trimpath strips local paths; -buildid= zeros the linker build ID. For any binary whose hash is measured (TEE attestation), a build-reproducible Make target must build twice and diff sha256sum.
• go mod tidy — run in CI; fail if it produces a diff.

Linter Rules (golangci-lint v2)

Default is the strictest reasonable preset. Config (.golangci.yml):

• linters.default: none — enable explicitly, no surprises from upstream additions
• Enabled (~50): asasalint asciicheck bidichk bodyclose copyloopvar cyclop dupl durationcheck errcheck errname errorlint exhaustive forbidigo funlen gocheckcompilerdirectives gochecknoglobals gochecknoinits gocognit goconst gocritic gocyclo godot gomoddirectives gomodguard goprintffuncname gosec govet ineffassign lll loggercheck makezero mirror mnd musttag nakedret nestif nilerr nilnil noctx nolintlint nonamedreturns nosprintfhostport predeclared promlinter reassign revive rowserrcheck sqlclosecheck staticcheck testableexamples testpackage tparallel unconvert unparam unused usestdlibvars usetesting wastedassign whitespace sloglint
• formatters.enable: [goimports]
• settings.cyclop.max-complexity: 30, settings.funlen.lines: 100, settings.gocognit.min-complexity: 20, settings.lll.line-length: 140
• settings.govet.enable-all: true, govet.settings.shadow.strict: true, disable fieldalignment
• settings.errcheck.check-type-assertions: true
• settings.exhaustive.check: [switch, map]
• settings.nolintlint.require-explanation: true, require-specific: true
• settings.gomodguard.blocked.modules — at minimum block github.com/golang/protobuf (use google.golang.org/protobuf), github.com/satori/go.uuid + github.com/gofrs/uuid (use github.com/google/uuid)
• Test-file exclusions: bodyclose dupl funlen goconst gosec noctx wrapcheck disabled in _test.go
• Relax per-file only after hitting a real conflict — never preemptively

Warnings block CI. No //nolint without a rule-specific target and an explanation comment.

Testing

• go test ./... -race -covermode=atomic -coverprofile=coverage.out — race detector mandatory. Fail on uncovered races.
• Table-driven tests — default pattern for unit tests.
• Test files — *_test.go next to the code. External test packages (package foo_test) for black-box tests; testpackage linter enforces this where applicable.
• Integration tests — gate behind build tags (//go:build integration), run in separate CI step.
• Fuzz — go test -fuzz=Fuzz... for parsers and security-relevant decoders. Commit seed corpus under testdata/fuzz/.
• Benchmarks — go test -bench=. -benchmem when performance matters; capture baseline with benchstat.
• Coverage floor — project-defined, enforced in CI (go tool cover -func=coverage.out).

Scratch Testing

ALWAYS use a test.go file with //go:build scratch tag in project root for ad-hoc exploration:

//go:build scratch

package main

func main() {
    // ...
}

Run with go run -tags=scratch ./test.go. Comment out previous code to keep history. Gitignored — never commit; move to a real package if the code should persist.

NEVER use inline Go via go run - or heredocs.

Project Layout

Follow the standard layout:

• cmd/<binary>/main.go — entrypoints, thin main only
• internal/ — private packages, not importable by other modules
• pkg/ — exported packages (only if actually consumed externally; otherwise keep in internal/)
• testdata/ — test fixtures (never compiled)
• vendor/ — committed, regenerated by go mod vendor

main functions delegate to a testable Run(ctx, args, stdout, stderr) int in a sibling package.

Dependencies

• Prefer stdlib. log/slog not logrus; net/http not gin unless routing complexity justifies it.
• google.golang.org/protobuf not github.com/golang/protobuf (enforced by gomodguard).
• github.com/google/uuid not satori/gofrs (enforced).
• Dependabot — enable for gomod, github-actions, docker; daily schedule.

Makefile Targets

Canonical targets every Go project should expose:

vendor               go mod vendor
tidy                 go mod tidy && git diff --exit-code go.mod go.sum
fmt                  goimports -w $(SOURCE_DIRS)
fmt-check            gofmt -l -s $(SOURCE_DIRS) | tee /dev/stderr | ifne false
lint                 go vet ./... && golangci-lint run -c .golangci.yml
modernize            go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest ./...
test                 go test -race -covermode=atomic -coverprofile=coverage.out ./...
build                go build -trimpath -ldflags "-s -w -buildid=" -o build/<name> ./cmd/<name>
build-reproducible   build twice, diff sha256sum, fail on mismatch
vuln                 govulncheck ./...
all                  vendor tidy fmt-check lint test build