golang-dependency-management

ペルソナ： あなたは Go の依存関係を管理する担当者です。新しい依存関係は長期的なメンテナンスの責任を伴うものとして扱い、外部パッケージを導入する前に、標準ライブラリですでに問題を解決できないかを確認します。

依存関係：

• govulncheck：go install golang.org/x/vuln/cmd/govulncheck@latest

Go の依存関係管理

AI エージェントのルール：依存関係を追加する前に確認する

新しい依存関係を追加するために go get を実行する前に、AI エージェントは必ずユーザーに確認を求めてください。 AI エージェントは、メンテナンスされていない、品質が低い、または標準ライブラリが同等の機能を提供しているため不要なパッケージを提案する場合があります。既存の依存関係をアップグレードするために go get -u を使用するのは安全です。

依存関係を提案する前に、以下を評価してください。

• 標準ライブラリでユースケースに対応できますか？
• ライセンスに互換性はありますか？
• よく知られた代替手段はありますか？
• そのパッケージは何を行い、なぜ必要ですか？

samber/cc-skills-golang@golang-popular-libraries スキルには、精査済みの本番環境対応ライブラリのリストがまとめられています。このリストにあるパッケージを優先して提案してください。精査済みの選択肢がない場合は、無名の代替手段よりも、Go チームのよく知られたパッケージ（golang.org/x/...）や確立された組織のパッケージを優先してください。

主なルール

• go.sum は必ずコミットしてください。すべての依存関係のバージョンについて暗号学的チェックサムを記録し、go mod verify によるサプライチェーン改ざんの検出を可能にします。これがないと、侵害されたプロキシが悪意のあるコードを気付かれずに差し替える可能性があります
• リリースの前に govulncheck ./... または go tool govulncheck ./... を実行してください。本番環境に到達する前に、依存関係ツリー内の既知の CVE を検出できます
• 依存関係を追加する前に、メンテナンス状況、ライセンスの互換性、標準ライブラリによる代替手段を考慮することが重要です。依存関係を追加するたびに、攻撃対象領域、メンテナンスの負担、バイナリサイズが増加します
• 依存関係を変更するコミットの前に go mod tidy を実行してください。未使用のモジュールを削除し、不足しているモジュールを追加して、go.mod を実態に即した状態に保ちます

go.mod と go.sum

基本的なコマンド

コマンド	用途
go mod tidy	不足している依存関係を追加し、未使用のものを削除
go mod download	モジュールをローカルキャッシュにダウンロード
go mod verify	キャッシュ内のモジュールが go.sum のチェックサムと一致することを検証
go mod vendor	依存関係を vendor/ ディレクトリにコピー
go mod edit	go.mod をプログラムから編集（スクリプト、CI）
go mod graph	モジュールの依存関係グラフを出力
go mod why	モジュールまたはパッケージが必要な理由を説明

ベンダリング

ネットワークアクセスのないハーメチックビルド、チェックサムを超えた再現性の保証、またはモジュールプロキシにアクセスできない環境へのデプロイが必要な場合は、go mod vendor を使用してください。CI パイプラインや Docker ビルドでは、ベンダリングが役立つことがあります。依存関係を変更した後に go mod vendor を実行し、vendor/ ディレクトリをコミットしてください。

依存関係のインストールとアップグレード

依存関係の追加

go get github.com/google/uuid          # Latest version
go get github.com/google/[email protected]   # Specific version
go get github.com/google/uuid@latest   # Explicitly latest
go get github.com/google/uuid@<commit> # Specific commit (pseudo-version)

バージョンを固定する前に、pkg.go.dev でモジュールの利用可能なバージョン、インポーター、既知の脆弱性を確認してください → samber/cc-skills-golang@golang-pkg-go-dev スキルを参照してください。

アップグレード

go get -u ./...            # Upgrade ALL direct+indirect deps to latest minor/patch
go get -u=patch ./...      # Upgrade to latest patch only (safer)
go get github.com/[email protected] # Upgrade specific package

通常の更新では go get -u=patch を優先してください。 パッチ更新やマイナー更新は通常、メジャーアップグレードよりリスクが低いですが、それでもレビューが必要です。依存関係を更新する際は、次を実行してください。

go get -u=patch ./...
go mod tidy
go test ./...
go vet ./...
govulncheck ./...   # or: go tool govulncheck ./...

永続化、シリアル化、ネットワーク、認証、認可、暗号化、またはパブリック API に影響するライブラリのリリースノートや変更履歴には、互換性を損なう変更に関する重要な情報が含まれている場合があります。

依存関係の削除

go get github.com/google/uuid@none  # Mark for removal
go mod tidy                          # Clean up go.mod and go.sum

CLI ツールのインストール

Go 1.24 以降のモジュールでは、tool ディレクティブを使って実行可能ツールを go.mod に固定します。モジュールが Go 1.24 未満をサポートする必要がある場合を除き、新しい tools.go のブランクインポートファイルは作成しないでください。

# Add tools to the current module.
go get -tool github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
go get -tool golang.org/x/vuln/cmd/govulncheck@latest
go get -tool golang.org/x/perf/cmd/benchstat@latest

# Run pinned tools reproducibly.
go tool golangci-lint run ./...
go tool govulncheck ./...
go tool benchstat old.txt new.txt

# Install all module-pinned tools into GOBIN/PATH when needed.
go install tool

# Update pinned tools deliberately, then review go.mod/go.sum.
go get -u tool
go mod tidy

Go 1.27 以降を対象とするモジュールの go.mod の形式です。これは対象バージョンの例であり、上限ではありません。ツールを追加するためだけに変更せず、プロジェクトで実際に指定されている go ディレクティブを維持してください。

module example.com/project

go 1.27

tool (
    github.com/golangci/golangci-lint/v2/cmd/golangci-lint
    golang.org/x/vuln/cmd/govulncheck
    golang.org/x/perf/cmd/benchstat
)

go 1.27 以降では、go mod tidy が重複する require ブロックを自動的に統合し、既存のコメントを保持しながら、2 ブロック構成（直接依存関係、その後に間接依存関係）を適用します。2 つ目の require ブロックが生じる統合の後に、手動で整理する必要はありません。

Go 1.24 未満の場合に限り、従来の tools.go ブランクインポートの回避策を使用します。

//go:build tools

package tools

import (
    _ "github.com/golangci/golangci-lint/v2/cmd/golangci-lint"
    _ "golang.org/x/vuln/cmd/govulncheck"
)

ルール：Go 1.24 以降では tool ディレクティブを使用します。Go 1.24 未満では tools.go を代替手段として使用します。

モジュールの対象バージョンに関する注意

新しいツールチェーンを使用していても、go mod init によって古い既定の go ディレクティブを持つモジュールが作成される場合があります。プロジェクトが意図的に新しいツールチェーンの API を対象としている場合は、ディレクティブを明示的に更新してください。

go mod edit -go=1.27
go mod tidy

今後の Go バージョンについては、プロジェクトで意図している対象バージョンを使用してください。プロジェクトでアップグレードが明示的に承認されるまでは、モジュールの go ディレクティブより新しい API を使用しないでください。

詳細解説

• バージョン管理と MVS — セマンティックバージョニングのルール（major.minor.patch）、各番号を増やすタイミング、プレリリースバージョン、Minimal Version Selection（MVS）アルゴリズム（単に「最新」を選べない理由）、メジャーバージョンのサフィックス規則（破壊的変更に対する v0、v1、v2 のサフィックス）。

• 依存関係の監査 — govulncheck による脆弱性スキャン、古くなった依存関係の追跡、どの依存関係がバイナリのサイズを大きくしているかの分析（goweight）、go.mod をすっきり保つためのテスト専用依存関係とバイナリ依存関係の区別。

• 依存関係の競合と解決 — バージョン競合の診断（互換性のないバージョンを要求した際に go get が行う処理）、解決方法（ローカル開発向けの replace ディレクティブ、問題のあるバージョン向けの exclude、公開済みでスキップすべきバージョン向けの retract）、依存関係ツリー全体にまたがる競合への対処ワークフロー。

• Go ワークスペース — 複数モジュールの開発（例：ライブラリとサンプルアプリケーション）に使う go.work ファイル、ワークスペースとモノレポの使い分け、ワークスペースのベストプラクティス。

• 依存関係の自動更新 — Dependabot または Renovate を設定して依存関係更新の PR を自動作成する方法、自動マージ戦略（自動マージする場合とレビューを必須にする場合）、セキュリティ更新への対応。

• 依存関係グラフの可視化 — 完全な依存関係ツリーを調べる go mod graph、可視化する modgraphviz、肥大化の原因となる依存関係チェーンを特定するインタラクティブツール。

相互参照

• → Dependabot/Renovate の CI 設定については、samber/cc-skills-golang@golang-continuous-integration スキルを参照してください
• → govulncheck による脆弱性スキャンについては、samber/cc-skills-golang@golang-security スキルを参照してください
• → 検証済みのライブラリの推奨については、samber/cc-skills-golang@golang-popular-libraries スキルを参照してください

クイックリファレンス

# Start a new module
go mod init github.com/user/project

# Add a dependency
go get github.com/google/[email protected]

# Upgrade all deps (patch only, safer)
go get -u=patch ./...

# Remove unused deps
go mod tidy

# Check for vulnerabilities
govulncheck ./...   # or: go tool govulncheck ./...

# Check for outdated deps
go list -u -m -json all | go-mod-outdated -update -direct

# Analyze binary size by dependency
goweight

# Understand why a dep exists
go mod why -m github.com/some/module

# Visualize dependency graph
go mod graph | modgraphviz | dot -Tpng -o deps.png

# Verify checksums
go mod verify