Golang Modernize

Go Modernization

Modernize toward the project's intended compatibility target, not automatically toward the newest syntax. Preserve behavior unless the user explicitly includes a behavioral change.

Establish the Target

Before proposing changes:

1. Read go.mod, any go.work, CI configuration, release files, and supported-platform documentation.
2. Distinguish the module's go directive from the locally selected toolchain. Do not assume either one expresses the user's desired support policy.
3. If changing the supported Go version is in scope, confirm the target and compatibility consequences. Otherwise, stay within the existing directive.
4. Read the official release notes for every version crossed by the upgrade. Use references/versions.md to evaluate candidates without relying on a stale feature catalog.
5. Inspect nearby conventions and existing migration decisions before introducing a new idiom.

If the target version or downstream compatibility requirement is materially ambiguous, report the ambiguity before editing version-sensitive code.

Choose Changes by Evidence

Prioritize candidates in this order:

1. Removed, deprecated, or behavior-changing APIs that affect correctness or supportability.
2. Security and resource-safety improvements supported by the target version.
3. Standard-library replacements that remove a dependency or a meaningful amount of custom code.
4. Language and testing features that materially simplify the implementation.
5. Cosmetic rewrites only when they improve consistency in the touched scope.

Do not replace a mature dependency merely because a standard-library alternative exists. Compare required behavior, migration cost, performance, operational integrations, and supported Go versions.

Work in Reviewable Units

• Keep modernization separate from unrelated features and broad structural refactors.
• For a focused request, change only the requested package or files.
• For a repository-wide review, inventory candidates first, grouped by prerequisite and risk. Apply independent mechanical changes separately from semantic migrations.
• Prefer type-aware tooling for identifier or API rewrites. Inspect every generated diff; reflection, templates, generated files, build tags, and serialized names may not be visible to a type-aware rename.
• Keep ignore files, agent configuration, tool installation, and unrelated dependency upgrades outside a focused code modernization.

Validate Each Migration

Use the project's own commands when present. A typical Go validation sequence is:

gofmt -w <changed-go-files>
go test ./...
go vet ./...

Also run relevant checks when the change warrants them:

• go test -race ./... for concurrency semantics.
• Existing integration tests for I/O, database, protocol, or serialization changes.
• Before/after benchmarks for performance-sensitive rewrites.
• Cross-platform or build-tag checks when platform-specific files changed.
• go mod tidy only when module contents should change; review its diff separately.

A passing build is not enough for migrations that affect wire formats, random sequences, logging contracts, database behavior, or public APIs. Preserve those contracts explicitly or document an intentional break.

Tooling and Infrastructure

Read references/tooling.md only when the request includes module tooling, CI, compiler diagnostics, vulnerability scanning, or build optimization.

Deliverable

Summarize:

• the target Go version and compatibility assumptions;
• which migrations were applied or proposed, with rationale;
• behavior or API risks that required special verification;
• commands run and any checks that remain unavailable.