go-development

Go Development Patterns

Core Principles

Type Safety

Avoid: interface{} (use any), sync.Map, scattered type assertions, reflection
Prefer: Generics [T any], errors.AsType[T] (Go 1.26), concrete types
Run go fix ./... after upgrades

Consistency

One pattern per problem domain
Match existing codebase patterns
Refactor holistically or not at all
Config precedence: defaults < config file < env vars < flags

Testing

Build tags isolate test tiers: unit (default), integration, e2e
Always use t.Parallel(), t.Helper(), table-driven subtests
Use log/slog directly -- never wrap it in custom Logger interfaces

Conventions

Naming: ID, URL, HTTP (not Id, Url, Http) — not tool-enforced (ST1003 is off by default)
Error wrapping: fmt.Errorf("failed to process: %w", err)

References

Git hooks: ls lefthook.yml 2>/dev/null && lefthook install || echo "Add lefthook — see references/lefthook-template.md"

Load as needed:

Reference	Purpose
`references/architecture.md`	Package structure, state mutation completeness
`references/logging.md`	Structured logging with log/slog, migration from logrus
`references/cron-scheduling.md`	go-cron patterns: named jobs, runtime updates, resilience
`references/resilience.md`	Pointer to go-cron's built-in retry/circuit-breaker/timeout wrappers
`references/docker.md`	Docker client patterns, buffer pooling
`references/ldap.md`	LDAP/Active Directory integration
`references/testing.md`	Build tags, resource isolation, race gotchas
`references/linting.md`	golangci-lint v2, staticcheck
`references/api-design.md`	Enum/status defensive handling
`references/fuzz-testing.md`	Go fuzzing patterns, security seeds
`references/contracts-and-invariants.md`	Contracts, invariants, property tests
`references/mutation-testing.md`	Gremlins configuration, test quality measurement
`references/makefile.md`	Standard Makefile interface for CI/CD
`references/modernization.md`	`go fix` modernizers and their build-tag trap, `errors.AsType[T]`, `b.Loop`
`references/dependencies.md`	Upgrades: `go get -u all`, majors, build-set scoping
`references/lefthook-template.md`	Ready-to-use lefthook.yml for Go project git hooks
`references/branch-protection.md`	Ruleset watermark: three-ruleset gate, bypass modes
`references/reusable-workflows.md`	Reusable Actions workflow callers, permission propagation, release-gate outputs
`references/single-build-release.md`	Single-build release: cross-compile once, reuse for release+container
`references/awesome-go-submission.md`	awesome-go submission: CI-parsed PR body, name collisions

Quality Gates

Run before completing any review:

golangci-lint run --timeout 5m    # Linting
go vet ./...                       # Static analysis
staticcheck ./...                  # Additional checks
govulncheck ./...                  # Vulnerability scan
go test -race ./...                # Race detection

Stdlib Vulnerability Fixes

When govulncheck reports stdlib vulnerabilities: check fix version via vuln.go.dev, update go X.Y.Z in go.mod, run go mod tidy.

Contributing: Submit improvements to https://github.com/netresearch/go-development-skill