golang-modernize

$27

Workflow

When invoked:

• **Check the project's go.mod or go.work** to determine the current Go version (go directive)

• Check the latest Go version using the Go Version Changelogs table below and suggest upgrading if the project's go.mod is behind

• **Read .modernize** in the project root — this file contains previously ignored suggestions; do NOT re-suggest anything listed there

• Scan the codebase for modernization opportunities based on the target Go version

• **Run golangci-lint** with the modernize linter if available

• 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.

• For large codebases, parallelize the scan using up to 5 sub-agents (via the Agent tool), each targeting a different modernization category (e.g. deprecated packages, language features, standard library upgrades, testing patterns, tooling and infra)

• 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.

• 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.

.modernize file format

# Ignored modernization suggestions

# Format: <date> <category> <description>

2026-01-15 slog-migration Team decided to keep zap for now

2026-02-01 math-rand-v2 Legacy module requires math/rand compatibility

Go Version Changelogs

Reference the relevant changelog when suggesting a modernization:

Version

Release

Changelog

Go 1.21

August 2023

https://go.dev/doc/go1.21

Go 1.22

February 2024

https://go.dev/doc/go1.22

Go 1.23

August 2024

https://go.dev/doc/go1.23

Go 1.24

February 2025

https://go.dev/doc/go1.24

Go 1.25

August 2025

https://go.dev/doc/go1.25

Go 1.26

February 2026

https://go.dev/doc/go1.26

For versions newer than Go 1.26, 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.

Using the modernize linter

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 1.26's rewritten go fix cover overlapping modernization checks, but exact coverage differs by tool version. See the samber/cc-skills-golang@golang-lint skill for configuration.

Version-specific modernizations

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

Tooling modernization

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

Deprecated Packages Migration

Deprecated

Replacement

Since

math/rand

math/rand/v2

Go 1.22

crypto/elliptic (most functions)

crypto/ecdh

Go 1.21

reflect.SliceHeader, StringHeader

unsafe.Slice, unsafe.String

Go 1.21

reflect.PtrTo

reflect.PointerTo

Go 1.22

runtime.GOROOT()

go env GOROOT

Go 1.24

runtime.SetFinalizer

runtime.AddCleanup

Go 1.24

crypto/cipher.NewOFB, NewCFB*

AEAD modes or NewCTR

Go 1.24

golang.org/x/crypto/sha3

crypto/sha3

Go 1.24

golang.org/x/crypto/hkdf

crypto/hkdf

Go 1.24

golang.org/x/crypto/pbkdf2

crypto/pbkdf2

Go 1.24

testing/synctest.Run

testing/synctest.Test

Go 1.25

crypto/rsa.EncryptPKCS1v15 for new encryption use

RSA-OAEP (rsa.EncryptOAEP / rsa.EncryptOAEPWithOptions) or HPKE/KEM design

Go 1.26

net/http/httputil.ReverseProxy.Director

ReverseProxy.Rewrite

Go 1.26

Migration Priority Guide

When modernizing a codebase, prioritize changes by impact:

High priority (safety and correctness)

• Remove loop variable shadow copies (Go 1.22+) — prevents subtle bugs

• Replace math/rand with math/rand/v2 (Go 1.22+) — remove rand.Seed calls

• Use os.Root for user-supplied file paths (Go 1.24+) — prevents path traversal

• Run govulncheck (Go 1.22+) — catch known vulnerabilities

• Use errors.Is/errors.As instead of direct comparison (Go 1.13+)

• Migrate deprecated crypto packages (Go 1.24+) — security critical

Medium priority (readability and maintainability)

• Replace interface{} with any (Go 1.18+)

• Use min/max builtins (Go 1.21+)

• Use range over int (Go 1.22+)

• Use slices and maps packages (Go 1.21+)

• Use cmp.Or for default values (Go 1.22+)

• Use sync.OnceValue/sync.OnceFunc (Go 1.21+)

• Use sync.WaitGroup.Go (Go 1.25+)

• Use t.Context() in tests (Go 1.24+)

• Use b.Loop() in benchmarks (Go 1.24+)

Lower priority (gradual improvement)

• Migrate to slog from third-party loggers (Go 1.21+)

• Adopt iterators where they simplify code (Go 1.23+)

• Replace sort.Slice with slices.SortFunc (Go 1.21+)

• Use strings.SplitSeq and iterator variants (Go 1.24+)

• Move tool deps to go.mod tool directives (Go 1.24+)

• Enable PGO for production builds (Go 1.21+)

• Upgrade to golangci-lint v2 with modernize linter (golangci-lint v2.6.0+)

• Add govulncheck to CI pipeline

• Set up monthly modernization CI pipeline

• Evaluate encoding/json/v2 only when the project explicitly opts into GOEXPERIMENT=jsonv2 (Go 1.25+, experimental)

• Set up AI-driven code review in CI — loads these skills to guide review per area; see samber/cc-skills-golang@golang-continuous-integration

Related Skills

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.