ペルソナ: あなたは Go の依存関係を管理するスチュワードです。新しい依存関係を長期的なメンテナンスコミットメントとして扱い、外部パッケージを使う前に、標準ライブラリが既に問題を解決していないかを問います。

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 ./... を実行 — 本番環境に到達する前に依存関係ツリー内の既知の 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/pkg/errors           # 最新バージョン
go get github.com/pkg/errors@v0.9.1    # 特定のバージョン
go get github.com/pkg/errors@latest    # 明示的に最新
go get github.com/pkg/errors@master    # 特定のブランチ (疑似バージョン)

アップグレード

go get -u ./...            # すべての直接・間接依存関係を最新のマイナー/パッチにアップグレード
go get -u=patch ./...      # パッチのみを最新にアップグレード (より安全)
go get github.com/pkg@v1.5 # 特定のパッケージをアップグレード

ルーチン更新には go get -u=patch を優先してください — パッチバージョンはパブリック API を変更しません (semver の約束)、したがってビルドを破壊する可能性は低いです。マイナーバージョンのアップグレードは新しい API を追加できますが、予期しない動作の廃止または変更も可能です。

依存関係の削除

go get github.com/pkg/errors@none   # 削除対象としてマーク
go mod tidy                          # go.mod と go.sum をクリーンアップ

CLI ツールのインストール

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

go install はバイナリを $GOPATH/bin にビルドおよびインストールします。@latest または特定のバージョンタグを使用してください — 依存するツールには @master を使用しないでください。

tools.go パターン

本番コード内でインポートすることなく、モジュール内のツールバージョンをピン留めします:

//go:build tools

package tools

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

ビルド制約により、このファイルはコンパイルされません。ブランクインポートはツールを go.mod に保持するため、go install はピン留めされたバージョンを使用します。このファイルを作成した後、go mod tidy を実行してください。

詳細解説

• バージョニング & MVS — セマンティックバージョニングルール (major.minor.patch)、各番号をいつインクリメントするか、プレリリースバージョン、最小バージョン選択 (MVS) アルゴリズム (なぜ単に「最新」を選ぶことができないのか)、およびメジャーバージョンサフィックス規約 (破壊的変更のための v0, v1, v2 サフィックス)。

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

• 依存関係の競合と解決 — バージョン競合の診断 (互換性のないバージョンを要求するときに go get が何をするか)、解決戦略 (ローカル開発用の replace ディレクティブ、壊れたバージョン用の exclude、スキップすべき発行済みバージョン用の retract)、依存関係ツリー全体の競合ワークフロー。

• Go ワークスペース — マルチモジュール開発用 go.work ファイル (例: ライブラリ + サンプルアプリケーション)、ワークスペースとモノレポをいつ使用するか、ワークスペースのベストプラクティス。

• 自動依存関係更新 — 自動依存関係更新 PR のための Dependabot または Renovate の設定、自動マージ戦略 (いつ自動的にマージするか対レビュー要求)、セキュリティ更新の処理。

• 依存関係グラフの可視化 — 完全な依存関係ツリーを検査するための go mod graph、可視化するための modgraphviz、どの依存関係チェーンが肥大化の原因かを見つけるインタラクティブツール。

相互参照

• → samber/cc-skills-golang@golang-continuous-integration スキルで Dependabot/Renovate CI セットアップを参照
• → samber/cc-skills-golang@golang-security スキルで govulncheck による脆弱性スキャンを参照
• → samber/cc-skills-golang@golang-popular-libraries スキルで検証されたライブラリ推奨事項を参照

クイックリファレンス

# 新しいモジュールを開始
go mod init github.com/user/project

# 依存関係を追加
go get github.com/pkg/errors@v0.9.1

# すべての依存関係をアップグレード (パッチのみ、より安全)
go get -u=patch ./...

# 未使用の依存関係を削除
go mod tidy

# 脆弱性をチェック
govulncheck ./...

# 古い依存関係をチェック
go list -u -m -json all | go-mod-outdated -update -direct

# 依存関係別にバイナリサイズを分析
goweight

# 依存関係が存在する理由を理解
go mod why -m github.com/some/module

# 依存関係グラフを可視化
go mod graph | modgraphviz | dot -Tpng -o deps.png

# チェックサムを検証
go mod verify