go-code-review

Go コードレビュー

レビューワークフロー

以下の順序どおりに進めてください。以下のすべてのパス条件を満たすまで、指摘事項を出力しないでください。

1. go.mod のベースライン — go.mod を開き、go ディレクティブを確認します。
   パス条件： 正確な go X.YY の値を（レビューの前置きまたは作業メモに）記載できます。このベースラインに該当する場合にのみ、バージョン依存のアドバイスを適用してください（Go 1.22 より前のループキャプチャ、1.21 以降の slog／構造化ロギング、1.20 以降の errors.Join）。

2. 周辺コードを読む — 変更された各 .go ファイルについて、差分の該当箇所だけでなく、編集箇所を含む関数全体または論理単位全体を読みます。
   パス条件： 変更された各ファイルについて、変更を含む外側の関数全体（またはパッケージレベルの init／var ブロック）を少なくとも1つ読みます。

3. チェックリストの範囲を決める — どのレビューチェックリストの項目が該当するかを判断します（エラー処理、並行処理、インターフェース／型、リソース、命名）。該当する項目のリファレンスを読み、差分と無関係な項目はスキップします。
   パス条件： レビューまたは作業メモに、適用したチェックリストの項目を記載するか、差分に基づく1行の理由を添えて該当なしと記載します（例：「変更に並行処理なし」）。

4. 報告前の検証 — review-verification-protocolを読み、手順に従います。
   パス条件： 報告する各指摘について、プロトコルの報告前検証チェックリストを満たします（実際のコードを読んだこと、周辺の文脈を確認したこと、「誤り」と「スタイルの違い」を区別したことなど）。

必須条件（同じ順序で簡潔に記載）

手順	目的とするパス条件
1	バージョン固有のアドバイスをする前に、go.mod の go X.YY を記録します。
2	差分だけでなく、変更された各ファイルの外側のコンテキスト全体を読みます。
3	該当するチェックリストの項目を記載するか、差分に基づく理由を添えて該当なしとします。必要に応じてリファレンスを開きます。
4	報告する問題ごとに review-verification-protocol を完了します。

出力形式

指摘事項は次の形式で報告します。

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.

クイックリファレンス

問題の種類	リファレンス
エラーチェックの欠落、エラーのラップ、errors.Join	references/error-handling.md
データ競合、チャネルの誤用、ゴルーチンのライフサイクル	references/concurrency.md
インターフェースの肥大化、命名、ジェネリクス	references/interfaces.md
リソースリーク、defer の誤用、slog、命名	references/common-mistakes.md

レビューチェックリスト

エラー処理

• すべてのエラーをチェックしている（正当化するコメントなしに _ = err を使っていない）
• エラーをコンテキスト付きでラップしている（fmt.Errorf("...: %w", err)）
• 文字列比較ではなく errors.Is／errors.As を使用している
• 複数のエラーを集約する場合は errors.Join を使用している（Go 1.20 以降）
• エラーとともにゼロ値を返している

並行処理

• ゴルーチンリークがない（コンテキストのキャンセルまたはシャットダウンシグナルがある）
• チャネルは送信側だけが、必ず1回だけ閉じている
• 共有状態をミューテックスまたは sync 型で保護している
• ゴルーチンの完了を待つために WaitGroup を使用している
• 呼び出しチェーンを通じてコンテキストを伝播している
• ループ変数のキャプチャに対処している（Go 1.22 より前のコードベースのみ）

インターフェースと型

• インターフェースは提供側ではなく利用側で定義している
• インターフェース名が -er の命名規則に従っている
• インターフェースが最小限である（メソッドは1～3個）
• コンストラクターから具象型を返している
• interface{} より any を優先している（Go 1.18 以降）
• any やコード生成の代わりに、適切な場合はジェネリクスを使用している

リソースとライフサイクル

• リソースの作成直後に defer で閉じている
• HTTP レスポンスボディを必ず閉じている
• クロージャーで囲まずにループ内で defer を使用していない
• 明示的な初期化を優先し、init() 関数を避けている

命名とスタイル

• エクスポートされる名前にドキュメントコメントがある
• 冗長な名前がない（user.UserService → user.Service）
• 5 行を超える関数で裸の return を使っていない
• Context を最初のパラメーターとして渡している
• 構造化ログには log ではなく slog を使用している（Go 1.21 以降）

重大度の判定基準

Critical（マージをブロック）

• I/O、ネットワーク、データベース操作でエラーをチェックしていない
• ゴルーチンのリーク（シャットダウン経路がない）
• 共有状態の競合状態（同期なしでの並行 map アクセス）
• リソースが無制限に蓄積する（ループ内の defer、接続を閉じていない）

Major（修正すべき）

• コンテキストなしでエラーを返している（単なる return err）
• 起動したゴルーチンに WaitGroup がない
• 回復可能なエラーに panic を使っている
• 下流の呼び出しに Context が伝播されていない

Minor（修正を検討）

• Go 1.18 以降のコードベースで any ではなく interface{} を使用している
• エクスポートされる名前にドキュメントコメントがない
• 冗長な名前
• サイズがわかっているスライスを事前確保していない

Informational（注記のみ）

• コード生成がある箇所にジェネリクスを追加する提案
• インターフェース設計のリファクタリング案
• 影響が測定されていないパフォーマンス最適化

参照資料を読み込むタイミング

• エラーの返し方をレビューする → error-handling.md
• ゴルーチン、チャネル、または sync 型をレビューする → concurrency.md
• 型定義、インターフェース、またはジェネリクスをレビューする → interfaces.md
• 一般的なレビュー（リソース、命名、init、パフォーマンス） → common-mistakes.md

有効なパターン（指摘しないこと）

以下は許容される Go のパターンです。指摘すると開発者の時間を無駄にします。

• 理由のコメント付きの _ = err — 説明を添えて意図的にエラーを無視している
• 空のインターフェース / any — 真に汎用的なコードや、型指定のない API との相互運用に使用している
• 短い関数での裸の return — 名前付き戻り値を使う 5 行未満の関数では許容される
• close しないチャネル — チャネルを close せず、Context のキャンセルによってコンシューマーを停止する場合
• 構造体フィールドを保護する Mutex — メソッド経由でのみアクセスされる場合でも、正しいカプセル化である
• 理由付きの //nolint ディレクティブ — 説明が添えられていれば許容される
• ループ内の Defer — 関数スコープでのクリーンアップが意図されている場合（例：ファイルをバッチ処理する）
• 関数オプションパターン — type Option func(*T) と With* コンストラクターの組み合わせは慣用的
• 頻繁に実行される処理での sync.Pool — パフォーマンスが重要なコードでの割り当て負荷の軽減に許容される
• main / テストでの context.Background() — トップレベル呼び出しのルート Context として有効
• default を含む select — 意図的なパターンである、ブロックしないチャネル操作
• 小さなスコープでの短い変数名 — i、err、ctx、ok は Go で慣用的

コンテキスト依存のルール

次の問題は、特定の条件に当てはまる場合にのみ指摘してください。

Issue	次の場合にのみ指摘
エラーチェックの欠如	エラーへの対応が可能（再試行、ログ出力、伝播）である
ゴルーチンのリーク	そのゴルーチンに Context のキャンセル経路がない
defer の欠如	次の取得または return の前にリソースが明示的に閉じられていない
インターフェースの過剰使用	インターフェースに 2 つを超えるメソッドがあり、利用者が 1 つだけである
ループ変数のキャプチャ	go.mod で Go < 1.22 が指定されている
slog の欠如	go.mod で Go >= 1.21 が指定され、構造化出力に log パッケージを使用している

指摘を提出する前に

Review Workflow の step 4 を満たしてください。review-verification-protocol を読み込み、各問題について報告前チェックを完了してください。