golang-master

Go マスター

あらゆる Go コードベースに適用される、Go 1.21+ 向けの言語レベルの原則です（1.22～1.26 の機能は該当箇所で明記しています）。このスキルは汎用的な最低基準です。プロジェクト独自のガイドラインスキルと内容が競合する場合は、そちらが優先されます。プロジェクトで明記されていない事項は、このスキルが定めます。

具体的な Go の課題については、該当するリファレンスを参照してください。現在のコンテキストを活用し、タスクに Go が登場するというだけで、すべてのリファレンスを読み込まないでください。適用の可否は、プロジェクトの規約とサポート対象の Go バージョンに従います。

最低基準

ブランチにかかわらず、Go のすべての行で守るべき必須事項です。

1. すべてのエラーを処理するか、破棄する箇所にその理由を明記します。何も記述せずに _ に代入してはいけません。
2. エラーは fmt.Errorf("context: %w", err) でラップし、errors.Is／errors.As で判定します。文字列比較で判定してはいけません。
3. I/O を行う、ブロックする、または API 境界をまたぐ関数では、ctx context.Context を最初の引数にし、呼び出し元の ctx を伝播させます。処理の途中で新たに context.Background() を使ってはいけません。
4. すべてのゴルーチンには、所有者、終了経路、待機方法が必要です。
5. panic は到達不可能な状態に限って使用し、想定される失敗はエラーとして返します。
6. 型が不確かな型アサーションはチェックします。書き込みの前にマップを初期化し、契約上適切な場合は nil スライスまたはゼロ値のスライスを使用します。
7. 意図的な実装契約にはコンパイル時のインターフェースアサーションを使用します。アサーションを追加するだけのためにインターフェースを作ってはいけません。
8. テストでは、その対象が担う不変条件を検証します。複数のケースにはテーブルを使い、並行処理がある場合、またはプロジェクトで必要とされる場合は競合をチェックします。
9. gofmt と、プロジェクトが定める該当箇所の lint／テストゲートを実行します。編集のたびにリポジトリ全体の vet を実行するのではなく、現在ある根拠を再利用します。
10. タイムアウト、上限、アドレスなどの運用値は、設定またはオプションから取得します。ハードコードしてはいけません。

分岐

タスクに含まれる内容…	参照先
エラーの生成、ラップ、判定、ログ記録、結合、panic／recover の方針	references/errors.md
ゴルーチン、チャネル、select、同期プリミティブ、errgroup、ワーカープール、競合	references/concurrency.md
キャンセル、タイムアウト、期限、コンテキスト値、切り離されたバックグラウンド処理	references/context.md
nil に関する落とし穴、append によるエイリアス、マップアクセス、数値変換、ループ内の defer、ゼロ値	references/safety.md
構造体、インターフェース、埋め込み、レシーバー、フィールドタグ、ジェネリクスの設計	references/interfaces-generics.md
命名、制御フローの構成、コンストラクター、関数オプション、init()	references/style-naming.md
テスト、ベンチマーク、ファジング、統合テストのビルドタグの作成またはレビュー	references/testing.md
プロファイリング、アロケーションの調査、GC チューニング、ベンチマーク比較	references/performance.md
古い形式のパターン、非推奨 API、Go バージョンのアップグレード	references/modernize.md
新しいモジュール、ディレクトリ構成、cmd／internal／pkg、ワークスペース	references/layout.md

キャンセルを伴う並行処理では、concurrency.md と context.md の両方を読みます。レビューでは、変更された動作を評価するために必要な該当セクションを参照します。

注意すべき兆候

変更されたパスで以下の兆候が見られた場合は調査してください。これらは絶対的な欠陥ではありません。

• ctx.Done()、チャネルのクローズ、または WaitGroup による終了経路がない状態で起動されたゴルーチン。呼び出し元より長く存続します。
• ループ内の time.After。反復ごとにタイマーが割り当てられます。time.NewTimer と Reset を使用してください。
• インターフェースとして返された型付き nil ポインター。結果は != nil になります。
• 元のスライスと並行して保持された append の戻り値。バッキング配列を共有するため、気付かないまま相互に変更されます。
• ループ本体内の defer。関数の終了までリソースが蓄積するため、本体を切り出してください。
• 境界チェックのない整数型の縮小変換。気付かないまま値が折り返されます。
• ログに記録したうえで返されるエラー。上位で重複して報告されるため、どちらか一方だけにしてください。
• コンストラクターから返されるインターフェース、またはその利用側ではなく実装側の隣に定義されたインターフェース。
• 説明のない共有可変状態を含むテスト、またはデータ競合の検出範囲がない並行処理の挙動を含むテスト。
• 型パラメーターまたは具体的な型が分かっているのに使われている any。