go-style-guide
Use when writing, reviewing, or committing ANY Go code in this project — enforces the three Google Go Style Guides (guide, decisions, best-practices) item by item.
SKILL.md.claude/skills/go-style-guide/SKILL.md
GitHubGoogle Go Style Guide
This project follows the three Google Go style documents. This skill enforces them item by item, in two layers:
- Deterministic layer —
golangci-lint+gofmt, run by the gitpre-commithook (.githooks/pre-commit→scripts/lint.sh). Covers objective items. - AI-review layer — when you (Claude) are about to
git commit, the PreToolUse hook injectsscripts/style-checklist.mdand you MUST confront the staged diff against EVERY item before committing. Covers subjective items (naming quality, comment usefulness, simplicity).
The five principles (priority order)
From references/guide.md. When principles conflict, earlier wins:
- Clarity — the code's purpose and rationale are clear to the reader.
- Simplicity — simplest way to accomplish the goal; least mechanism.
- Concision — high signal-to-noise ratio; no repetition or noise.
- Maintainability — code is edited far more than written; design for change.
- Consistency — looks/behaves like the surrounding codebase (tie-breaker).
How to use this skill
- Writing code → keep the principles above in mind; consult the relevant
references/*.mdwhen unsure about a specific decision (naming, errors, tests…). - Reviewing a diff / before committing → walk
scripts/style-checklist.mdtop to bottom against the diff. It is the single source of truth for the AI layer.
Reference files (load on demand)
references/guide.md— core principles & formatting rules (the "why").references/decisions.md— itemized normative decisions: naming, commentary, imports, errors, language constructs, common libraries, test failures.references/best-practices.md— itemized patterns: naming, errors (%wvs%v, structured/sentinel errors), documentation, variable declarations, option patterns, and testing.
Most-checked items (quick reference)
MixedCaps, neverunder_scores; initialisms keep case (URL,ID,userID).- Exported symbols have doc comments starting with the symbol name, full sentences ending in a period.
- GoDoc / pkg.go.dev: write exported docs to render well on pkg.go.dev, not just
to exist. Document every exported struct field / interface method / const-var
individually; give the package doc a real overview (what + approach + how to use,
with a usage snippet); state contracts (zero-value/default behavior, channel/resource
ownership, nil handling, which error when); add a runnable
Example(inpkg_test) for public packages so usage shows on pkg.go.dev. Sanity-check withgo doc ./<pkg>. - Error strings: lowercase, no trailing punctuation. Wrap with
%w(at the end) when callers neederrors.Is/errors.As;%vat system boundaries. - Handle errors immediately; indent the error path, keep the happy path un-indented;
avoid
elseafter a returningif. - No
Getprefix on getters. Receiver names are 1–2 letters, consistent per type. - No
util/helper/commonpackage names. Don't shadow stdlib package names. - Tests:
gotbeforewant; identify function + inputs in failures;t.Errorto keep going,t.Fatalonly when continuing is meaningless; field names in table-driven struct literals; nevert.Fatalfrom a spawned goroutine.