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
%wand add context (fmt.Errorf("get user %d: %w", id, err)); compare witherrors.Is/errors.As, never by message. context.Contextis 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). Nofmt.Printlnfor logging. - Table-driven tests for every new function, with named cases.
- No secrets or personal data in logs or error messages.
Workflow
- Know the module. Read
go.mod(module path,godirective), the lint config (.golangci.yml) and.github/workflowsfor the pinned golangci-lint version. A repo with no lint config is the first finding. - Run the mechanical gates before judging anything.
node ${CLAUDE_SKILL_DIR}/scripts/go-check.mjs <module-dir>(add--fastto 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 inassets/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 nogo.mod. - Review the judgment items in
references/review-checklist.md. Never restate lint output; the tool line is the finding. - Write the findings in the format of
references/review-output.md(file:line, why, fix with an effort estimate, source). - Writing new code or tests? Pick the reference from the table, write it, then run the gates again.
Which reference
| Task | Read |
|---|---|
| Error shapes, HTTP client or server, concurrency, shutdown, logging, modern stdlib, performance | references/idioms.md |
Writing or fixing Go tests, fakes, fuzz, benchmarks, the -race run |
references/testing-go.md |
| Review judgment: naming, interfaces, errors, modules, comments, commits | references/review-checklist.md |
| Writing up review findings | references/review-output.md |
Creating, migrating or debugging .golangci.yml; install; CI pin; version drift |
references/golangci-lint-v2.md |
| Redis, HTTP, SQL or other pooled clients; locks, dedup, at-least-once delivery | references/shared-state-and-clients.md |
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,gosimpleortypecheckis a v1 file: rungolangci-lint migrate, then diff it. Install the pinned binary (the official page discouragesgo install); pin the same version locally and in CI. - Fix the code, never the gate: no
//nolintwithout a linter name and a reason, no exclusions outside_test.goforgosecornoctx, no lowered thresholds. go-checkis 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
godirective 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).