go-version-manager

Go バージョンマネージャー

依存関係を変更する前に、プロジェクトに対応した Go ツールチェーンを選択してください。バージョンを実際に切り替える場合は、マシンに既存の goenv インストールを優先してください。対応するバージョンマネージャーがない場合は、明示的なバイナリパスに切り替えてください。

ワークフロー

1. go.mod を確認し、go、toolchain、replace ディレクティブを特定してください。
2. .agents/skills/go-version-manager/scripts/go-version-manager.sh requirement <project-dir>、manager、list を実行してください。
3. .agents/skills/go-version-manager/scripts/go-version-manager.sh select <project-dir> を実行し、インストール済みのバイナリを選択してください。
4. <go-binary> version と <go-binary> env GOROOT GOTOOLCHAIN GOPATH GOMODCACHE GOCACHE で、選択したバイナリを確認してください。
5. 切り替えの適用範囲を選択してください。
   • 1 つのコマンドだけに適用する場合は、スクリプトの exec コマンドを使用してください。goenv の場合、GOENV_VERSION はそのコマンドにのみ設定されます。
   • 現在のターミナルに適用する場合は、shell-command が出力するコマンド（通常は goenv shell <version>）を実行してください。
   • リポジトリに永続する選択にする場合は、switch-local を使用してください。これは goenv local <version> を実行して .go-version を書き込むため、ユーザーがリポジトリの変更を許可した場合にのみ実行してください。
   • goenv global の変更は、ユーザーがマシン全体のデフォルト変更を明示的に要求した場合に限ってください。
6. モジュール関連のコマンドを実行した後は、git diff -- go.mod go.sum を確認してください。
7. 選択したバージョン、実行したコマンド、依存関係の変更、検証結果を報告してください。

選択ルール

• toolchain goX.Y.Z と完全に一致するバージョンがインストールされている場合は、それを優先してください。
• そうでない場合は、go X.Y のマイナーバージョン系列で、インストール済みのパッチバージョンのうち最も新しいものを優先してください。
• go ディレクティブは言語／ツールチェーンの最低要件として扱い、モジュールのディレクティブをアップグレードする許可とは見なさないでください。
• 同じマイナーバージョン系列に対応するインストール済みバージョンがない場合に限り、より新しいマイナーバージョンを使用してください。モジュールを変更する前にリスクを説明してください。
• 通常の Go インストールでは GOROOT を設定しないでください。選択した go バイナリが GOROOT を決定します。
• ユーザーから明示的に要求されない限り、/usr/local/go、システムのシンボリックリンク、シェルプロファイル、グローバルな PATH を書き換えないでください。
• インストール済みの goenv とそのインストール済みバージョンを優先してください。リポジトリで別のバージョンマネージャー（mise、asdf、g、gvm、Homebrew）がすでに設定されている場合は、それに従ってください。承認を得ずに 2 つ目のマネージャーを導入しないでください。
• 不足している Go バージョンを自動でインストールしないでください。不足しているバージョンを報告し、ツールのダウンロードまたはインストールの前に確認を求めてください。

モジュールの安全性

• チェックサムの不足エラーを解消するために、go.sum を手動で編集しないでください。
• go mod tidy は、選択したプロジェクト対応ツールチェーンで、かつタスクで依存関係ファイルの変更が許可されている場合にのみ実行してください。
• 既存の依存関係グラフを取得するだけでよい場合は、go mod download、またはエラーで示された対象に絞った go get module@version を優先してください。変更差分を確認してください。
• ローカルの Go バージョンを誤って使用したことを補うために、パッケージをアップグレードしないでください。
• ユーザーがプロジェクトのツールチェーンのアップグレードを要求しない限り、go または toolchain ディレクティブを変更しないでください。
• go.mod と go.sum にある、無関係なユーザーの変更を保持してください。

よくある問題の診断

• package slices is not in GOROOT：有効な Go バイナリが Go 1.21 より古い状態です。依存関係に触れる前にツールチェーンを切り替えてください。
• missing go.sum entry：正しいツールチェーンを使用したうえで、モジュールグラフを取得または整理してください。チェックサムを手動で書き込まないでください。
• キャッシュの operation not permitted：選択したツールチェーンはそのまま使い、書き込み可能なキャッシュだけを、たとえば GOCACHE=<writable-temp-dir> のように変更してください。GOMODCACHE の変更は、依存関係全体のダウンロードが発生する可能性があるため、必要な場合に限ってください。
• モック／テストバイナリに特別なフラグや外部サービスが必要：コンパイルと実行を区別してください。パッケージの初期化によりローカルで実行できない場合は、コンパイルのみの検証に go test -c -o <temp-file> <package> を使用してください。
• コマンドによって依存関係が予期せず多数変更された：作業を中断し、先に進む前に go version、go env GOTOOLCHAIN、モジュールのディレクティブ、変更差分を確認してください。

検証の段階

十分なレベルから開始し、リスクに応じて段階を上げてください。

1. <go> version と <go> env ...
2. <go> mod verify
3. 対象を絞った <go> test ./path/to/changed/package
4. コンパイルのみの <go> test -c -o <temp-file> ./package
5. より広範な go test ./... またはプロジェクトのビルドコマンド

依存関係のダウンロードやワークスペース外への書き込みに承認が必要な場合は、サンドボックスやネットワークの制御を回避せず、承認を求めてください。

スクリプト

.agents/skills/go-version-manager/scripts/go-version-manager.sh を使用してください。

# Show go/toolchain requirements
.agents/skills/go-version-manager/scripts/go-version-manager.sh requirement /path/to/project

# List discovered Go binaries
.agents/skills/go-version-manager/scripts/go-version-manager.sh list

# Show which switching backend is available
.agents/skills/go-version-manager/scripts/go-version-manager.sh manager

# Print the selected Go binary
.agents/skills/go-version-manager/scripts/go-version-manager.sh select /path/to/project

# Execute with the selected binary
.agents/skills/go-version-manager/scripts/go-version-manager.sh exec /path/to/project -- test ./...

# Print the command that switches the current terminal
.agents/skills/go-version-manager/scripts/go-version-manager.sh shell-command /path/to/project

# Persist the selection for this repository (writes .go-version)
.agents/skills/go-version-manager/scripts/go-version-manager.sh switch-local /path/to/project

このスクリプトは、.go-version に書き込む switch-local と、exec に渡された Go サブコマンドによる影響を除き、読み取り専用です。