netresearch/go-development

Go Development Patterns

Required Workflow

For reviews, invoke related skills: security-audit (OWASP), enterprise-readiness (OpenSSF/SLSA), github-project (branch protection). A review is NOT complete until all are executed.

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

• Errors: lowercase, no punctuation (errors.New("invalid input"))
• Naming: ID, URL, HTTP (not Id, Url, Http)
• 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, config management, middleware chains | | references/logging.md | Structured logging with log/slog, migration from logrus | | references/cron-scheduling.md | go-cron patterns: named jobs, runtime updates, context, resilience | | references/resilience.md | Retry logic, graceful shutdown, context propagation | | references/docker.md | Docker client patterns, buffer pooling | | references/ldap.md | LDAP/Active Directory integration | | references/testing.md | Test strategies, build tags, table-driven tests | | references/linting.md | golangci-lint v2, staticcheck, code quality | | references/api-design.md | Bitmask options, functional options, builders | | 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 1.26 modernizers, go fix, errors.AsType[T], wg.Go() | | references/lefthook-template.md | Ready-to-use lefthook.yml for Go project git hooks | | 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 |

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. Use PR branches for repos with branch protection.

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