Go development and review

Scope: anything in .go files or go.mod. This skill adds the how-to and the review method on top of a short baseline of Go conventions. If the project already has its own written Go conventions, they win over the baseline below.

Baseline conventions

• Handle every error; never discard one with _ unless a comment says why that is safe.
• Wrap with %w and add context (fmt.Errorf("get user %d: %w", id, err)); compare with errors.Is / errors.As, never by message.
• context.Context is the first parameter of anything that does I/O, and is never stored in a struct.
• One structured logger per module (log/slog, zerolog or zap, whichever the module already uses). No fmt.Println for logging.
• Table-driven tests for every new function, with named cases.
• No secrets or personal data in logs or error messages.

Workflow

1. Know the module. Read go.mod (module path, go directive), the lint config (.golangci.yml) and .github/workflows for the pinned golangci-lint version. A repo with no lint config is the first finding.
2. Run the mechanical gates before judging anything. node ${CLAUDE_SKILL_DIR}/scripts/go-check.mjs <module-dir> (add --fast to skip govulncheck and the test run). It prints one PASS, FAIL, MISS or WARN line per gate: format, golangci-lint run, go vet, go mod tidy -diff, govulncheck, go test -race. It uses the repo's own lint config, else the baseline in assets/golangci.yml, and says which. A MISS line means a tool is not installed: report it and install the pinned version; do not skip the gate. Exit 2 means the directory has no go.mod.
3. Review the judgment items in references/review-checklist.md. Never restate lint output; the tool line is the finding.
4. Write the findings in the format of references/review-output.md (file:line, why, fix with an effort estimate, source).
5. Writing new code or tests? Pick the reference from the table, write it, then run the gates again.

Which reference

Related skills: testing covers TypeScript and JavaScript tests, ci-cd-pipelines covers wiring the gates into CI, security-review covers a deeper security pass than gosec and govulncheck give.

Rules that bite

• golangci-lint is v2. A config with enable-all, disable-all, linters-settings, skip-dirs, issues.exclude-rules, gosimple or typecheck is a v1 file: run golangci-lint migrate, then diff it. Install the pinned binary (the official page discourages go install); pin the same version locally and in CI.
• Fix the code, never the gate: no //nolint without a linter name and a reason, no exclusions outside _test.go for gosec or noctx, no lowered thresholds.
• go-check is only as good as the installed tools. Say which gates did not run (MISS, skipped race) in the review, so "green" is not claimed on a partial run.
• Verify a version-gated language or library feature against the release notes (go.dev/doc/go1.N) and the module's go directive before using or recommending it.
• A problem found outside the change under review is still a finding: put it in the plan or an issue that names the layer which fixes it.

Evidence

Cite file:line for every claim about the code. Quote the failing go-check line for every claim that a gate fails. Do not call a change safe to merge without a green go-check (or a stated list of the gates that could not run).