Go Development

Session Init

At the start of any Go session, detect the project's Go version:

1. Read go.mod and extract the go directive (e.g., go 1.26)
2. This version controls which language features and stdlib APIs are available
3. If you are about to suggest a feature gated behind a newer version, stop and note the incompatibility

Version Feature Table

Toolchain-First Workflow

This is the core of this skill. Go ships a powerful toolchain - use it instead of guessing.

Before Writing Code

When about to use a stdlib or third-party API you are not certain about, verify the signature first:

go doc <package>.<Symbol>          # exact function/type/method
go doc -all <package>.<Type>       # full type with all methods
go doc -src <package>.<Symbol>     # source code when implementation matters

Token efficiency matters: go doc fmt.Fprintf returns 5 lines. go doc fmt returns hundreds. Always use the most specific query that answers your question.

For third-party packages, they must be importable (in go.mod) before go doc works. For stdlib, it always works.

After Writing or Modifying Code

Pick the verification level that matches the scope of the change:

Full - new files, unfamiliar APIs, concurrency code, public interface changes:

gofmt -d .                              # format check (should produce no output)
go vet ./...                            # static analysis
go build ./...                          # compilation check
go test -race -count=1 ./...            # tests with race detector, cache bypassed

Or use the bundled script: ${CLAUDE_SKILL_DIR}/scripts/go-quality-check.sh ./...

Standard - modifying existing code in patterns the project already uses:

go vet ./...
go test -count=1 -run TestRelevant ./path/to/pkg/...

Light - formatting, comments, documentation, renaming:

gofmt -d <changed-file>

When Modernizing Code

Go 1.26 introduced go fix, which applies automated improvements:

go fix -diff ./...     # preview changes as unified diff
go fix ./...           # apply all fixes

This replaces patterns like interface{} with any, sort.Slice with slices.Sort, manual wg.Add/Done with wg.Go, and many more. Always preview with -diff first.

When Debugging Test Failures

go test -v -run TestName -count=1 ./pkg/...    # verbose, cache-bypassed
go test -race -count=1 ./...                    # if concurrency is involved
go test -coverprofile=c.out ./... && go tool cover -func=c.out  # coverage gaps

When Adding Dependencies

1. Prefer stdlib when the stdlib solution is adequate
2. Run go doc on the candidate package to verify its API before committing to it
3. go get <module>@latest && go mod tidy
4. go mod why <module> to verify it is actually used

Tool Command Reference

go doc

go vet analyzers (37 total)

(Run go tool vet help for the full list of all 37.)

go fix fixers (21 total, Go 1.26+)

(Run go tool fix help for the full list.)

go test key flags

go build key flags

go mod subcommands

gofmt flags

External tools

Check availability before use. These are not part of the Go toolchain:

If unavailable, go vet covers the most critical checks. Do not block on missing external tools.

Common Diagnostics

Proactive Behaviors

These are the rules for when to use tools without being asked:

• Verify before asserting: run go doc <pkg>.<Symbol> before claiming any API signature you have not used in this session. This is the single most important behavior - wrong signatures waste the user's time.
• Vet after structural changes: run go vet ./... after creating new files, adding exported functions, or modifying concurrency code.
• Format check before done: run gofmt -d <file> before presenting code as complete. If it produces output, the code has formatting issues.
• Race detection for concurrency: run go test -race -count=1 ./... after modifying code involving goroutines, channels, shared state, or sync primitives.
• Version gate features: check the go directive in go.mod before suggesting features from newer versions. Use the version feature table above.
• Modernize with go fix: when reviewing existing code, run go fix -diff ./... to identify modernization opportunities. Present the diff to the user before applying.
• Never suggest deprecated APIs: ioutil (deprecated 1.16), math/rand.Seed (unnecessary since 1.20), // +build (replaced by //go:build).
• Prefer errors.Is/As/AsType: over type assertions or string matching on errors. Use errors.AsType[T] on Go 1.26+.
• Limit HTTP request bodies: when writing HTTP handlers that decode request bodies, always use http.MaxBytesReader to prevent denial-of-service via unbounded uploads. This is easy to forget and hard to catch in code review.
• Set HTTP server timeouts: when creating http.Server, always set ReadTimeout, WriteTimeout, and IdleTimeout. A server without timeouts is vulnerable to slowloris attacks.

When NOT to run tools:

• Do not run go test when only editing comments or documentation
• Do not run go vet when the user is just asking a question, not writing code
• Do not run go doc for universally known functions (fmt.Println, len, append, etc.)

Idiomatic Go Principles

These are the philosophical foundations. When reviewing or writing Go code, apply these as judgment calls, not rigid rules:

• Clear is better than clever. Readable code is maintainable code. Prefer explicit control flow over clever one-liners.
• Accept interfaces, return structs. Functions should accept the smallest interface that satisfies their needs and return concrete types. This maximizes flexibility for callers and clarity for the API.
• Define interfaces at the consumer, not the provider. The package that uses an interface should define it, keeping it as small as needed.
• Errors are values. Handle them, don't ignore them. Wrap with context using fmt.Errorf("doing X: %w", err). See references/error-handling.md.
• Make the zero value useful. Design types so their zero value is valid and usable (e.g., sync.Mutex, bytes.Buffer).
• Composition over inheritance. Use struct embedding for reuse, not deep hierarchies.
• Keep packages focused. Organize by domain, not by layer. A user package, not a models package.
• defer for cleanup. Place defer immediately after acquiring a resource. It communicates cleanup intent right where the resource is opened.
• Unexported by default. Export only what is part of the public API. Unexported symbols can be changed freely.
• Pointer vs value receivers. Be consistent per type. Use value receivers for small, immutable types. Use pointer receivers for mutation or large structs. A type with any pointer receiver should use pointer receivers everywhere.

Reference Router

Open the reference file that matches the question. Load only one at a time.

Foundations

• Error handling (wrapping, sentinel errors, error types, errors.Is/As/AsType, errors.Join) -> references/error-handling.md
• Concurrency (goroutines, channels, sync primitives, context, patterns, pitfalls) -> references/concurrency.md
• Testing (table tests, subtests, benchmarks, fuzzing, golden files, coverage, helpers) -> references/testing.md

Modern Go

• Version-gated features (1.21-1.26 features, deprecated patterns, go fix guide) -> references/modern-go.md

Applied Topics

• Performance (profiling, pprof, PGO, escape analysis, benchstat, allocation reduction) -> references/performance.md
• Interface and API design (small interfaces, composition, functional options, generics) -> references/interfaces-and-design.md
• Modules and dependencies (go.mod, versioning, workspace mode, vendoring) -> references/modules-and-deps.md
• Security (input validation, SQL injection, path traversal, TLS, crypto, govulncheck) -> references/security.md

For a problem-based router ("I need to..."), see references/_index.md.

Verification Checklist

Before declaring work done on Go code:

1. gofmt -d . produces no output
2. go vet ./... produces no diagnostics
3. go build ./... succeeds
4. go test -race -count=1 ./... passes
5. No deprecated patterns (ioutil, math/rand.Seed, // +build)
6. Error values wrapped with %w where callers need errors.Is/errors.As
7. Exported functions and types have doc comments
8. context.Context is threaded through where cancellation matters
9. HTTP handlers use http.MaxBytesReader for request body limits
10. HTTP servers have ReadTimeout, WriteTimeout, IdleTimeout set
11. go mod tidy has been run if dependencies changed