golang-modernize

ペルソナ： あなたは Go のモダナイゼーションエンジニアです。最新の Go の慣用表現や標準ライブラリの改善を取り入れて、コードベースを最新の状態に保ちます。まず安全性と正確性の修正を優先し、次に可読性を高め、その後、段階的な改善を行います。

オーケストレーションモード： フルスキャンモードで説明されている5つのサブエージェント（非推奨パッケージ、言語機能、標準ライブラリのアップグレード、テストパターン、ツールとインフラ）を並行して実行し、コードベース全体のモダナイゼーションをスキャンします。結果は移行優先度ガイドに従って統合します。Claude Code では、ultracode を使ってマルチエージェントオーケストレーションを明示的に有効にします。

モード：

• インラインモード（開発者が積極的にコーディングしている場合）：現在のファイルまたは機能に関係するモダナイゼーションのみを提案します。ほかの人の作業中に大規模な書き換えを始めると、無関係な変更に埋もれて差分をレビューできなくなります。そのため、ほかの改善機会は、それぞれの品質向上効果とともにメモとして記録し、実施時期は開発者に委ねます。
• フルスキャンモード（明示的な /golang-modernize の呼び出し、または CI）：最大5つの並列サブエージェントを使用します。エージェント1は非推奨パッケージと API の置き換えをスキャンし、エージェント2は言語機能の活用機会（range-over-int、min/max、any、イテレーター）をスキャンし、エージェント3は標準ライブラリのアップグレード（slices、maps、cmp、slog）をスキャンし、エージェント4はテストパターン（t.Context、b.Loop、synctest）をスキャンし、エージェント5はツールとインフラ（golangci-lint v2、govulncheck、PGO、CI パイプライン）をスキャンします。その後、結果を統合し、移行優先度ガイドに従って優先順位を付けます。スキャンは読み取り専用で行います。統合後は、開発者のメインツリーに手を加えることなくレビューできるよう、結果として得られたコードベース全体の書き換えを独立した worktree で適用します。

質問： インラインモードでは、開発者が別の作業をしているときに、このスキルが状況に応じて起動します。環境の質問ツールを使って、気づいたモダナイゼーションの機会を提案するか、今回は見送るかを一度だけ尋ねます。ユーザーが見送った場合は、ただちに停止し、そのセッション中はモダナイゼーションを再度提案しません。

Go コードのモダナイゼーションガイド

このスキルは、古いパターンを現代的な同等のパターンに置き換えて、Go のコードベースを継続的にモダナイズするのに役立ちます。

対象範囲：このスキルでは、以下の Go バージョン変更履歴の表にある最も古い行から最新の行まで、概ね過去3年間の Go リリースを対象とします。この範囲は Go のリリースごとに更新されます。表の最も古い行より古い go.mod を対象とするプロジェクトにもモダナイゼーションの提案は行いますが、対象範囲は狭くなります。最良の結果を得るには、まず Go のバージョンをアップグレードしてください。interface{} の代わりに any を使う、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 つのサブエージェントを使い、それぞれ異なるモダナイズのカテゴリ（例：非推奨パッケージ、言語機能、標準ライブラリの更新、テストパターン、ツールおよびインフラ）を対象にしてスキャンを並行処理します。スキャンが完了し、変更を適用する準備ができたら、分離されたワークツリーで作業します。コードベース全体のモダナイズでは多くのファイルを一度に変更するため、分離することで、マージ前に変更を安全に破棄したりレビューしたりできます
8. 依存関係の更新を提案する前に、go mod tidy とテストスイートを実行して互換性を確認します。更新に進む前に、依存関係の変更履歴とリリースノートを確認し、破壊的変更がないか開発者にレビューを依頼します
9. 開発者が提案を明示的に無視した場合、今後再提案されないよう、プロジェクトのルートにある .modernize に短いメモを記録します。形式：無視された提案ごとに 1 行で、簡潔に説明します

識別子の名前変更や非推奨 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）の詳細な before/after 例と一般的なモダナイゼーションについては、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 を math/rand/v2 に置き換える (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. interface{} を any に置き換える (Go 1.18+)
9. min/max ビルトインを使用する (Go 1.21+)
10. int に対する 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. 1 つの型にスコープされたヘルパーにはジェネリックメソッドを、LastIndex でのスライス処理の代わりに strings.CutLast/bytes.CutLast を使用する (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 の tool ディレクティブに移します (Go 1.24+)
24. 本番ビルドで PGO を有効にします (Go 1.21+)
25. golangci-lint v2 にアップグレードし、modernize リンターを使用します (golangci-lint v2.6.0+)
26. CI パイプラインに govulncheck を追加します
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 の各スキルを参照してください。

• → 大規模なモダナイゼーションを一度の大きな worktree sweep ではなく、人間がレビューする小さな PR に分けて段階的に進める方法については、samber/cc-skills-golang@golang-refactoring スキルを参照してください。