golang-modernize

This skill helps you continuously modernize Go codebases by replacing outdated patterns with their modern equivalents.

Scope: This skill covers roughly the last 3 years of Go releases — from the oldest to the newest row in the Go Version Changelogs table below, updated each Go release. Projects targeting an older go.mod than the table's oldest row still get modernization suggestions, but with narrower coverage; for best results, upgrade the Go version first. Some older modernizations (e.g., any instead of interface{}, errors.Is/errors.As, strings.Cut) are included because they are still commonly missed, but many pre-1.21 improvements are intentionally omitted because they should have been adopted long ago and are considered baseline Go practices by now.

You MUST NEVER conduct large refactoring if the developer is working on a different task. But TRY TO CONVINCE your human it would improve the code quality.

When invoked:

1. Check the project's go.mod or go.work to determine the current Go version (go directive)
2. Check the latest Go version using the Go Version Changelogs table below and suggest upgrading if the project's go.mod is behind
3. Read .modernize in the project root — this file contains previously ignored suggestions; do NOT re-suggest anything listed there
4. Scan the codebase for modernization opportunities based on the target Go version
5. Run golangci-lint with the modernize linter if available, and go test ./... — Go 1.27+ runs the stdversion vet check by default, flagging APIs newer than the module's go directive; bump the directive or revert the suggestion, don't ignore the hit
6. Suggest improvements contextually:
   • If the developer is actively coding, only suggest improvements related to the code they are currently working on. Do not refactor unrelated files. Instead, mention opportunities you noticed and explain why the change would be beneficial — but let the developer decide.
   • If invoked explicitly via /golang-modernize or in CI, scan and suggest across the entire codebase.
7. For large codebases, parallelize the scan using up to 5 sub-agents, each targeting a different modernization category (e.g. deprecated packages, language features, standard library upgrades, testing patterns, tooling and infra). Once scanning is done and changes are ready to apply, do so in an isolated worktree — a codebase-wide modernization sweep touches many files at once, and isolation keeps the main tree safe to abandon or review before merging.
8. Before suggesting a dependency update, run go mod tidy and the test suite to verify compatibility. Ask the developer to review the dependency's changelog and release notes for breaking changes before proceeding.
9. If the developer explicitly ignores a suggestion, write a short memo to .modernize in the project root so it is not suggested again. Format: one line per ignored suggestion, with a short description.

When applying a modernization that renames an identifier or replaces a deprecated API (e.g. reflect.PtrTo → PointerTo, math/rand → math/rand/v2), → See samber/cc-skills-golang@golang-gopls skill — safe rename updates every call site and refuses a rename that would break interface satisfaction, and post-edit diagnostics catch compile errors across the rewritten files that a blind Edit or grep/sed sweep would leave broken.

Reference the relevant changelog when suggesting a modernization:

For versions newer than Go 1.27, consult the official Go release notes.

When the project's go.mod targets an older version, suggest upgrading and explain the benefits they'd unlock.

The modernize linter (available since golangci-lint v2.6.0) automatically detects code that can be rewritten using newer Go features. It originates from golang.org/x/tools/go/analysis/passes/modernize; gopls and go fix (rewritten onto the go/analysis framework in Go 1.26, with fixer coverage still growing in Go 1.27 — see Tooling modernization for the exact fixer list) cover overlapping modernization checks, but exact coverage differs by tool version. See the samber/cc-skills-golang@golang-lint skill for configuration.

For detailed before/after examples for each Go version (1.21–1.27) and general modernizations, see Go version modernizations.

For CI tooling, govulncheck, PGO, golangci-lint v2, and AI-powered modernization pipelines, see Tooling modernization.

Several Go 1.27 changes need verification, not a rewrite, before a go.mod bump ships. Most notably: a godebug line in go.mod (or //go:debug comment) still pinning asynctimerchan, tlsunsafeekm, tlsrsakex, tls3des, tls10server, x509keypairleaf, or gotypesalias to its old value now fails the build. Full checklist in Go version modernizations.

When modernizing a codebase, prioritize changes by impact:

See samber/cc-skills-golang@golang-concurrency, samber/cc-skills-golang@golang-testing, samber/cc-skills-golang@golang-observability, samber/cc-skills-golang@golang-error-handling, samber/cc-skills-golang@golang-lint, samber/cc-skills-golang@golang-continuous-integration skills.

• → See samber/cc-skills-golang@golang-refactoring skill for staging a large modernization sweep as small human-reviewed PRs instead of one big worktree sweep.