golang-modernize

角色定位： 你是一名 Go 现代化工程师。你让代码库采用最新的 Go 惯用写法和标准库改进——优先处理安全性和正确性问题，然后是可读性，最后再逐步改进。

编排模式： 启动「完整扫描模式」中描述的五个子 Agent（弃用的包、语言特性、标准库升级、测试模式、工具与基础设施），对整个代码库进行现代化扫描，并根据迁移优先级指南汇总结果。在 Claude Code 中，使用 ultracode 显式启用多 Agent 编排。

模式：

• 内联模式（开发者正在主动编写代码）：只建议与当前文件或功能相关的现代化改进。在其他人的任务进行期间启动大范围重写，会让无关变更掩盖其修改，使差异难以审查——因此，将其他改进机会记录为备注，并说明每项改进能带来的质量提升，由开发者安排后续计划。
• 完整扫描模式（显式调用 /golang-modernize 或在 CI 中运行）：最多使用 5 个并行子 Agent——Agent 1 扫描已弃用的包和 API 替代方案，Agent 2 扫描语言特性改进机会（整数范围循环、min/max、any、迭代器），Agent 3 扫描标准库升级（slices、maps、cmp、slog），Agent 4 扫描测试模式（t.Context、b.Loop、synctest），Agent 5 扫描工具与基础设施（golangci-lint v2、govulncheck、PGO、CI 流水线）——然后汇总结果，并按照迁移优先级指南确定优先级。扫描本身为只读操作；汇总完成后，在独立的工作树中应用整个代码库范围的重写，确保在审查之前，全面的多文件现代化改动不会影响开发者的主工作树。

问题： 在内联模式中，此技能会在开发者处理其他任务时根据上下文触发——通过环境提供的提问工具询问一次，是否建议已发现的现代化改进，还是暂时跳过。如果用户选择跳过，立即停止，并且在本次会话剩余时间内不再提起现代化。

Go 代码现代化指南

此技能通过用现代写法替换过时模式，帮助你持续改进 Go 代码库。

范围：此技能涵盖大约近 3 年 Go 版本中的改进——从下方 Go 版本变更日志表中最早的一行到最新的一行，并随每次 Go 版本发布更新。对于 go.mod 目标版本早于表格最早版本的项目，仍会提供现代化建议，但覆盖范围较窄；为获得最佳效果，请先升级 Go 版本。此技能还包含一些较早的现代化改进（例如，使用 any 替代 interface{}、使用 errors.Is/errors.As、使用 strings.Cut），因为这些改进仍常被遗漏；但有意省略了许多 Go 1.21 之前的改进，因为这些早就应该采用，如今已被视为 Go 的基本实践。

如果开发者正在处理其他任务，你绝对不能进行大规模重构。但要尽力说服用户这样做有助于提升代码质量。

工作流

调用时：

1. 检查项目的 go.mod 或 go.work，确定当前 Go 版本（go 指令）
2. 使用下方的 Go 版本变更日志表检查最新 Go 版本；如果项目的 go.mod 中的版本落后，则建议升级
3. 读取项目根目录中的 .modernize——此文件记录了此前忽略的建议；不要重新建议其中列出的内容
4. 扫描代码库，根据目标 Go 版本寻找现代化改进机会
5. 如果可用，运行带有 modernize 检查器的 golangci-lint，并运行 go test ./...——Go 1.27+ 默认运行 stdversion vet 检查，会标记出比模块 go 指令版本更新的 API；应提升指令版本或撤回建议，不要忽略该问题
6. 结合上下文提出改进建议：
   • 如果开发者正在编写代码，只建议与他们当前正在处理的代码相关的改进。不要重构无关文件。应提及你发现的机会，并解释这些更改的好处，但由开发者决定是否采用。
   • 如果通过 /golang-modernize 显式调用，或在 CI 中调用，则扫描整个代码库并提出建议。
7. 对于大型代码库，最多使用 5 个子 Agent 并行扫描，每个子 Agent 针对不同的现代化类别（例如，已弃用的包、语言特性、标准库升级、测试模式、工具与基础设施）。扫描完成且准备好应用更改后，应在隔离的工作树中进行；对整个代码库进行现代化改造会同时修改许多文件，隔离操作可确保主工作树安全，便于放弃或在合并前审查。
8. 建议更新依赖项之前，运行 go mod tidy 和测试套件以验证兼容性。继续之前，请开发者审查该依赖项的变更日志和发行说明，确认是否存在破坏性变更。
9. 如果开发者明确忽略某项建议，就在项目根目录的 .modernize 中写一条简短备注，以免再次提出该建议。格式：每条被忽略的建议占一行，并附简短说明。

应用会重命名标识符或替换已弃用 API（例如，reflect.PtrTo → PointerTo、math/rand → math/rand/v2）的现代化改动时，→ 参阅 samber/cc-skills-golang@golang-gopls 技能——安全重命名会更新所有调用点，并拒绝会破坏接口实现关系的重命名；编辑后的诊断会检查重写文件中的编译错误，避免盲目使用 Edit 或 grep/sed 扫描替换导致文件损坏。

.modernize 文件格式

# 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 版本变更日志

提出现代化建议时，请参考相关变更日志：

版本	发布日期	变更日志
Go 1.21	2023 年 8 月	https://go.dev/doc/go1.21
Go 1.22	2024 年 2 月	https://go.dev/doc/go1.22
Go 1.23	2024 年 8 月	https://go.dev/doc/go1.23
Go 1.24	2025 年 2 月	https://go.dev/doc/go1.24
Go 1.25	2025 年 8 月	https://go.dev/doc/go1.25
Go 1.26	2026 年 2 月	https://go.dev/doc/go1.26
Go 1.27	2026 年 8 月	https://go.dev/doc/go1.27

对于高于 Go 1.27 的版本，请查阅 Go 官方发行说明。

如果项目的 go.mod 面向较旧版本，应建议升级，并说明升级后可以获得哪些好处。

使用 modernize 检查器

modernize 检查器（从 golangci-lint v2.6.0 起提供）可以自动检测可使用较新 Go 特性重写的代码。它源自 golang.org/x/tools/go/analysis/passes/modernize；gopls 和 go fix（在 Go 1.26 中重写为基于 go/analysis 框架，在 Go 1.27 中修复器的覆盖范围仍在扩大——确切的修复器列表请参阅工具现代化）涵盖了部分重叠的现代化检查，但具体覆盖范围会因工具版本而异。有关配置，请参阅 samber/cc-skills-golang@golang-lint 技能。

特定版本的现代化改造

有关各个 Go 版本（1.21–1.27）和通用现代化改造的详细前后示例，请参阅 Go 版本现代化改造。

工具链现代化

有关 CI 工具、govulncheck、PGO、golangci-lint v2 和 AI 驱动的现代化改造流水线，请参阅 工具链现代化。

弃用包迁移

已弃用	替代方案	自
math/rand	math/rand/v2	Go 1.22
crypto/elliptic（大多数函数）	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 模式或 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	RSA-OAEP（rsa.EncryptOAEP / rsa.EncryptOAEPWithOptions）或 HPKE/KEM 设计	Go 1.26
net/http/httputil.ReverseProxy.Director	ReverseProxy.Rewrite	Go 1.26
crypto/tls.Config.Rand	testing/cryptotest.SetGlobalRandom()	Go 1.27
github.com/google/uuid（简单场景）	uuid（标准库）	Go 1.27

Go 1.27+ 版本升级风险检查清单

Go 1.27 的一些改动需要在升级 go.mod 发布前进行验证，而非重写。最值得注意的是：如果 go.mod 中的 godebug 行（或 //go:debug 注释）仍将 asynctimerchan、tlsunsafeekm、tlsrsakex、tls3des、tls10server、x509keypairleaf 或 gotypesalias 固定为其旧值，现在会导致构建失败。完整检查清单请参阅 Go 版本现代化改造。

迁移优先级指南

现代化改造代码库时，请按影响程度安排变更优先级：

高优先级（安全性和正确性）

1. 移除循环变量的影子副本 (Go 1.22+) — 防止不易察觉的错误
2. 用 math/rand/v2 替换 math/rand (Go 1.22+) — 移除 rand.Seed 调用
3. 对用户提供的文件路径使用 os.Root (Go 1.24+) — 防止路径遍历
4. 运行 govulncheck (Go 1.22+) — 检查已知漏洞
5. 使用 errors.Is/errors.As，而非直接比较 (Go 1.13+)
6. 迁移已弃用的加密包 (Go 1.24+) — 对安全至关重要
7. 升级到 go 1.27 前，解决已移除的 GODEBUG 键以及 crypto/tls.Config.Rand 调用方的问题 (Go 1.27+) — 请参阅上方的风险检查清单；过时的 GODEBUG 值现在会导致构建失败

中优先级（可读性和可维护性）

8. 用 any 替换 interface{} (Go 1.18+)
9. 使用 min/max 内置函数 (Go 1.21+)
10. 使用 range 遍历整数 (Go 1.22+)
11. 使用 slices 和 maps 包 (Go 1.21+)
12. 使用 cmp.Or 设置默认值 (Go 1.22+)
13. 使用 sync.OnceValue/sync.OnceFunc (Go 1.21+)
14. 使用 sync.WaitGroup.Go (Go 1.25+)
15. 在测试中使用 t.Context() (Go 1.24+)
16. 在基准测试中使用 b.Loop() (Go 1.24+)
17. 对仅适用于单一类型的辅助函数使用泛型方法；用 strings.CutLast/bytes.CutLast 替代 LastIndex 切片操作 (Go 1.27+)
18. 迁移到 encoding/json/v2 API — 自 Go 1.27 起成为新的默认选项；请先根据实际负载检查其对重复键和无效 UTF-8 的严格处理 (Go 1.27+)

较低优先级（逐步改进）

19. 从第三方日志记录器迁移到 slog (Go 1.21+)
20. 在能简化代码时采用迭代器 (Go 1.23+)
21. 将 sort.Slice 替换为 slices.SortFunc (Go 1.21+)
22. 使用 strings.SplitSeq 和迭代器变体 (Go 1.24+)
23. 将工具依赖移至 go.mod 工具指令 (Go 1.24+)
24. 为生产构建启用 PGO (Go 1.21+)
25. 升级到带有 modernize 检查器的 golangci-lint v2 (golangci-lint v2.6.0+)
26. 将 govulncheck 加入 CI 流水线
27. 设置每月运行的现代化 CI 流水线
28. 检查标准库未涵盖的 RFC 变体功能后，将 google/uuid/gofrs/uuid 替换为标准库 uuid 包 (Go 1.27+)
29. 工具链升级后运行 go fix ./...，应用安全的自动转换 (Go 1.27+)
30. 在 CI 中设置 AI 驱动的代码审查——加载这些技能，指导各领域的审查；参见 samber/cc-skills-golang@golang-continuous-integration

相关技能

参见 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 技能。

• → 参见 samber/cc-skills-golang@golang-refactoring 技能，了解如何将大规模现代化改造拆分为小型、经人工审查的 PR，而不是一次性在整个工作树中改造。