Go ツールチェーン
適用義務
AI 支援開発のデフォルト言語は TypeScript と Python である。Go はデフォルトではなく、次の要件が実際に必要な場合に限って選ぶ。
- 性能が重視されるネットワークサービス
- 単一バイナリとして配布するコマンドラインツール
- 静的な単一バイナリでデプロイする対象
- 並行性の高いワークロード
Go の採用には明確な根拠とユーザーの承認が必要であり、その内容をプロジェクトの ADR に記録する。
Go に慣れていること自体は、採用の根拠にならない。
適用範囲
本文書は Go プロジェクトのベースライン標準であり、プロジェクト単位の評価に代わるものではない。Go を採用する前に、要件が上記のいずれかに当てはまり、かつ TypeScript や Python では妥当なコストで満たせないことを確認する。
バージョン方針
最新の安定版 Go リリースを mise で管理する。
go.mod の toolchain ディレクティブは、mise で管理する Go のバージョンと一致させる。
記録された理由がない限り、旧バージョンの Go に固定しない。
利用ルール
リント
リンターとして golangci-lint を使う。
mise タスクとして利用できるようにし、ローカル開発と CI で同じ設定を使う。
設定は .golangci.yml としてコミットし、プロジェクトで重視する項目に合わせて調整する。enable-all は使わない。すべてを有効にすると、実行が遅く、特定のスタイルを要求するチェックまで有効になり、重要な指摘を見つけにくくなる。
常に有効にするベースライン:
govet— 疑わしい構造を検出し、go vetのチェックをおおむね含むstaticcheck— 正確性、簡略化、スタイルのチェック。エラー文字列の形式も含む(ST1005)。エラーメッセージは小文字で始め、末尾に句読点を付けないunused— 未使用の定数、変数、関数、型ineffassign— 効果のない代入misspell— よくある英単語のスペルミス
ベースラインに加えて、プロジェクトの性質に応じたグループを追加する:
- context を多用するサービス:
contextcheck、containedctx、fatcontext、noctx - エラー処理を重視するプロジェクト:
errcheckに加えてerrorlintとwrapcheck
フォーマット
フォーマッターには gofumpt を使う。
フォーマットのチェックをプリコミット設定と CI に含める。
エラー処理
エラーにコンテキストを付加するときは、%w でラップする:
return fmt.Errorf("loading config: %w", err)
ラップされたエラーは errors.Is と errors.As で検査する。
エラーメッセージ文字列を比較してエラーを判定してはならない。
コンテキスト
ブロックする関数やリクエスト単位の関数では、最初のパラメーターに context.Context を渡す。
呼び出し元のコンテキストを伝播させ、ライブラリコード内で新たな context.Background を生成してはならない。
並行処理
各 goroutine には所有者を一つだけ割り当て、その所有者がライフサイクルに責任を持つことを明示する。
キャンセルはコンテキストの伝播によって明示する。
goroutine をリークさせない。
テスト
複数の入力に対する振る舞いを、テーブル駆動テストでカバーする。
CI では go test -race を実行する。
_test.go ファイルには、.golangci.yml のパス単位の除外を使って、緩和したリントルールを適用する。テストでは本番コードほどリントを厳格にせず、可読性と意図の明確さを優先する。エラーラップと重複コードのスタイルチェックは、テストでは無効にする:
version: "2"
linters:
exclusions:
rules:
- path: _test\.go
linters:
- wrapcheck
- errorlint
- dupl
panic
ライブラリコードでは panic を使わず、エラーを返す。
panic は cmd/ のエントリーポイントにおける回復不能な起動時エラーに限って使う。
プロジェクト構成
Go には公式に定められた標準プロジェクト構成がない。golang-standards/project-layout リポジトリはコミュニティによる参考資料であり、公式標準ではない。公式ガイド Organizing a Go module も、モジュールのルートに基本パッケージを置く構成から説明を始めている。
- 小さなライブラリはルートをフラットに保ってよい。
go.modとパッケージのファイルで足りる。 - 複雑なサービスは、ビジネスのレイヤー構造に合う構成を設計し、テンプレートをそのままコピーしない。
cmd/(バイナリごとにエントリーポイントを置く)と internal/(インポート制限をコンパイラーが強制する)は、今も有用な慣習である。設計に役立つ場合に採用し、テンプレートに従う義務として扱わない。
連携
- mise — バージョン管理:Go と golangci-lint を mise で管理し、mise タスクとして利用できるようにする。
- Go API スタック — HTTP サービス向けの Web フレームワークと検証スタック。
- 品質ゲート — 同じチェック:prek と CI で同じリント・フォーマット設定を使う。
- Git ワークフロー — コミット規律:Go の変更も標準のコミットとプルリクエストのルールに従う。
- テスト戦略 — テストの焦点:何をどのレベルで検証するか。
採用しない代替案
単独の gofmt や goimports をプロジェクトのフォーマッターとして使わない。
gofumpt は gofmt の厳密な上位集合であり、import の並べ替えは gofumpt と golangci-lint の gci または goimports ルールで処理する。