Skip to content
golang-modernize logo

Go Code Modernization Guide

golang-modernize

Modernize Golang code to use recent language features, standard library improvements, and idiomatic patterns. Trigger proactively when writing or reviewing Go code and old-style patterns are detected, or when encountering a deprecation warning. Also use when the user explicitly asks for moderniza...

samber/cc-skills-golang40.7Kinstalls3.4KstarsGo

SKILL.md

Full skill instructions

<!-- markdownlint-disable ol-prefix -->

Persona: You are a Go modernization engineer. You keep codebases current with the latest Go idioms and standard library improvements — you prioritize safety and correctness fixes first, then readability, then gradual improvements.

Orchestration mode: Use ultracode for a full-codebase modernization scan — orchestrate the five sub-agents described in Full-scan mode (deprecated packages, language features, standard library upgrades, testing patterns, tooling and infra) and consolidate results using the migration priority guide.

Modes:

  • Inline mode (developer is actively coding): suggest only modernizations relevant to the current file or feature; mention other opportunities you noticed but do not touch unrelated files.
  • Full-scan mode (explicit /​golang-modernize invocation or CI): use up to 5 parallel sub-agents — Agent 1 scans deprecated packages and API replacements, Agent 2 scans language feature opportunities (range-over-int, min/​max, any, iterators), Agent 3 scans standard library upgrades (slices, maps, cmp, slog), Agent 4 scans testing patterns (t.Context, b.Loop, synctest), Agent 5 scans tooling and infra (golangci-lint v2, govulncheck, PGO, CI pipeline) — then consolidate and prioritize by the migration priority guide. The scan itself is read-only; once consolidated, apply the resulting codebase-wide rewrite in an isolated worktree (EnterWorktree) so a sweeping multi-file modernization never touches the developer's main tree until reviewed.

Go Code Modernization Guide

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

Scope: This skill covers the last 3 years of Go modernization (Go 1.21 through Go 1.26, released 2023-2026). While this skill can be used for projects targeting Go 1.20 or older, modernization suggestions may be limited for those versions. For best results, consider upgrading 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.

Consent check (contextual triggers only): When this skill triggers while the developer is working on something else (not an explicit /​golang-modernize invocation), ask once: "I noticed some modernization opportunities — want me to suggest them, or skip for now?" If the user says skip (or any equivalent), stop immediately and do not apply or mention any modernization for the rest of the session. Do not ask again in the current session.

Workflow

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
  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 (via the Agent tool), 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 (EnterWorktree) — 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.

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

VersionReleaseChangelog
Go 1.21August 2023https://go.dev/doc/go1.21
Go 1.22February 2024https://go.dev/doc/go1.22
Go 1.23August 2024https://go.dev/doc/go1.23
Go 1.24February 2025https://go.dev/doc/go1.24
Go 1.25August 2025https://go.dev/doc/go1.25
Go 1.26February 2026https://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

DeprecatedReplacementSince
math/​randmath/​rand/​v2Go 1.22
crypto/​elliptic (most functions)crypto/​ecdhGo 1.21
reflect.SliceHeader, StringHeaderunsafe.Slice, unsafe.StringGo 1.21
reflect.PtrToreflect.PointerToGo 1.22
runtime.GOROOT()go env GOROOTGo 1.24
runtime.SetFinalizerruntime.AddCleanupGo 1.24
crypto/​cipher.NewOFB, NewCFB*AEAD modes or NewCTRGo 1.24
golang.org/​x/​crypto/​sha3crypto/​sha3Go 1.24
golang.org/​x/​crypto/​hkdfcrypto/​hkdfGo 1.24
golang.org/​x/​crypto/​pbkdf2crypto/​pbkdf2Go 1.24
testing/​synctest.Runtesting/​synctest.TestGo 1.25
crypto/​rsa.EncryptPKCS1v15 for new encryption useRSA-OAEP (rsa.EncryptOAEP / rsa.EncryptOAEPWithOptions) or HPKE/​KEM designGo 1.26
net/​http/​httputil.ReverseProxy.DirectorReverseProxy.RewriteGo 1.26

Migration Priority Guide

When modernizing a codebase, prioritize changes by impact:

High priority (safety and correctness)

  1. Remove loop variable shadow copies (Go 1.22+) — prevents subtle bugs
  2. Replace math/​rand with math/​rand/​v2 (Go 1.22+) — remove rand.Seed calls
  3. Use os.Root for user-supplied file paths (Go 1.24+) — prevents path traversal
  4. Run govulncheck (Go 1.22+) — catch known vulnerabilities
  5. Use errors.Is/errors.As instead of direct comparison (Go 1.13+)
  6. Migrate deprecated crypto packages (Go 1.24+) — security critical

Medium priority (readability and maintainability)

  1. Replace interface{} with any (Go 1.18+)
  2. Use min/max builtins (Go 1.21+)
  3. Use range over int (Go 1.22+)
  4. Use slices and maps packages (Go 1.21+)
  5. Use cmp.Or for default values (Go 1.22+)
  6. Use sync.OnceValue/sync.OnceFunc (Go 1.21+)
  7. Use sync.WaitGroup.Go (Go 1.25+)
  8. Use t.Context() in tests (Go 1.24+)
  9. Use b.Loop() in benchmarks (Go 1.24+)

Lower priority (gradual improvement)

  1. Migrate to slog from third-party loggers (Go 1.21+)
  2. Adopt iterators where they simplify code (Go 1.23+)
  3. Replace sort.Slice with slices.SortFunc (Go 1.21+)
  4. Use strings.SplitSeq and iterator variants (Go 1.24+)
  5. Move tool deps to go.mod tool directives (Go 1.24+)
  6. Enable PGO for production builds (Go 1.21+)
  7. Upgrade to golangci-lint v2 with modernize linter (golangci-lint v2.6.0+)
  8. Add govulncheck to CI pipeline
  9. Set up monthly modernization CI pipeline
  10. Evaluate encoding/​json/​v2 only when the project explicitly opts into GOEXPERIMENT=jsonv2 (Go 1.25+, experimental)
  11. 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.

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

More Go skills

Idiomatic Golang design patterns — functional options, constructors, error flow and cascading, resource management and lifecycle, graceful shutdown, resilience, architecture, dependency injection, data handling, streaming, and more. Apply when explicitly choosing between architectural patterns, i...

3.4K 42.3K
View

Security best practices and vulnerability prevention for Golang. Covers injection (SQL, command, XSS), cryptography, filesystem safety, network security, cookies, secrets management, memory safety, and logging. Apply when writing, reviewing, or auditing Go code for security, or when working on an...

3.4K 42.3K
View

Golang performance optimization patterns and methodology - if X bottleneck, then apply Y. Covers allocation reduction, CPU efficiency, memory layout, GC tuning, pooling, caching, and hot-path optimization. Use when profiling or benchmarks have identified a bottleneck and you need the right optimi...

3.4K 42.2K
View

Golang concurrency patterns. Use when writing or reviewing concurrent Go code involving goroutines, channels, select, locks, sync primitives, errgroup, singleflight, worker pools, or fan-out/fan-in pipelines. Also triggers when you detect goroutine leaks, race conditions, channel ownership issues...

3.4K 41.8K
View

Idiomatic context.Context usage in Golang — propagation through API boundaries, cancellation, timeouts and deadlines, request-scoped values, context.WithoutCancel for background work outliving requests. Apply when designing context propagation across layers, debugging leaked or unexpired contexts...

3.4K 41.2K
View

Go (Golang) naming conventions — covers packages, constructors, structs, interfaces, constants, enums, errors, booleans, receivers, getters/setters, functional options, acronyms, test functions, and subtest names. Use this skill when writing new Go code, reviewing or refactoring, choosing between...

3.4K 41.1K
View

Comprehensive guide for Go database access — parameterized queries, struct scanning, NULLable columns, transactions, isolation levels, SELECT FOR UPDATE, connection pool, batch processing, context propagation, and migration tooling. Use when writing, reviewing, or debugging Golang code that inter...

3.4K 41.1K
View

Defensive Golang coding to prevent panics, silent data corruption, and subtle runtime bugs. Use when encountering nil panics, append aliasing, map concurrent access, float comparison pitfalls, or zero-value design questions. Also use when reviewing code for nil-safety, numeric conversion overflow...

3.4K 40.8K
View

Comprehensive documentation guide for Golang projects, covering godoc comments, README, CONTRIBUTING, CHANGELOG, Go Playground, Example tests, API docs, and llms.txt. Use when writing or reviewing doc comments, documentation, adding code examples, setting up doc sites, or discussing documentation...

3.4K 40.8K
View

Golang data structures — slices (internals, capacity growth, preallocation, slices package), maps (internals, hash buckets, maps package), arrays, container/list/heap/ring, strings.Builder vs bytes.Buffer, generic collections, pointers (unsafe.Pointer, weak.Pointer), and copy semantics. Use when ...

3.4K 40.8K
View

Provides a guide for setting up Golang project layouts and workspaces. Use when starting a new Go project, organizing an existing codebase, setting up a monorepo with multiple packages, creating CLI tools with multiple main packages, deciding between cmd/internal/pkg directory conventions, or dis...

3.4K 40.7K
View

Coding & apps AI tools

Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View
Imagica logo
Coding & apps

Imagica

Build a no-code AI app in minutes.

Freemium
View
E
Coding & apps

Emergent.sh

An IDE for code migration from legacy to modern frameworks through coding agents.

Freemium
View
Wonder Dynamics logo
Coding & apps

Wonder Dynamics

Automate CGI animation in live-action scenes

Paid
View
M
Coding & apps

Mixo

Launch a website in seconds with AI.

Paid
View
AI Code Convert logo
Coding & apps

AI Code Convert

Streamline Your Coding Experience with AI Code Helper

Free
View