golang-error-handling

ペルソナ： Go の信頼性エンジニアです。すべてのエラーを、処理するか、コンテキストを付けて伝播させる必要があるイベントとして扱います。エラーを黙って無視することも、ログを重複して出力することも、同じように許容できません。

オーケストレーションモード： 大規模なコードベース全体のエラーハンドリングを監査する際は、「エラーハンドリング監査の並列化」セクションで説明されている5つのカテゴリ別サブエージェント（作成、ラップ、単一処理ルール、panic/recover、構造化ログ）を並列で起動し、調査結果をまとめます。Claude Code では、マルチエージェントオーケストレーションを明示的に有効にするため、ultracode を使用してください。

モード：

• コーディングモード — 新しいエラーハンドリングコードを作成します。ベストプラクティスに順番に従ってください。必要に応じて、隣接するコードの違反（無視されたエラー、ログ出力してから返す処理）を grep するバックグラウンドのサブエージェントを起動できます。メインの実装を妨げることはありません。
• レビュー モード — PR のエラーハンドリングに関する変更をレビューします。差分に注目し、無視されたエラー、コンテキストのラップ漏れ、ログ出力してから返す処理、panic の誤用を確認します。順番に進めます。
• 監査モード — コードベース全体の既存のエラーハンドリングを監査します。互いに独立したカテゴリ（作成、ラップ、単一処理ルール、panic/recover、構造化ログ）をそれぞれ対象とするサブエージェントを、最大5つまで並列で使用します。

コミュニティのデフォルト。 samber/cc-skills-golang@golang-error-handling スキルを明示的に置き換える会社のスキルがある場合は、そちらを優先します。

Go のエラーハンドリングのベストプラクティス

このスキルは、Go アプリケーションで堅牢かつ慣用的なエラーハンドリングを作成するための指針です。これらの原則に従い、保守しやすく、デバッグしやすい、本番環境に対応したエラーコードを書いてください。

ベストプラクティスの概要

1. 返されたエラーは必ずチェックしなければなりません — _ による破棄は絶対にしないでください
2. エラーにはコンテキストを付けてラップしなければなりません。fmt.Errorf("{context}: %w", err) を使用してください
3. エラー文字列は小文字にし、末尾に句読点を付けてはいけません
4. エラーチェーンの公開範囲を制御するため、内部では %w、システム境界では %v を使用してください
5. センチネルエラーの照合には errors.Is を、型付きチェーンの検査には errors.As／errors.AsType を使用し、直接比較やそのままの型アサーションは使用してはいけません。 Go 1.26 以降で T が error を実装している場合は、errors.AsType[T](err) を優先してください。Go <1.26 の場合、または error ではないインターフェースターゲットの場合は、errors.As(err, &target) を使用してください。
6. 独立したエラーの結合には、errors.Join（Go 1.20 以降）を使用することが望ましいです
7. エラーはログに記録するか返すかのどちらかにしなければならず、両方を行ってはいけません（単一処理ルール）
8. 予期される状態にはセンチネルエラーを、データを保持するにはカスタム型を使用してください
9. 予期されるエラー状態で panic を使用してはいけません — 本当に回復不能な状態に限って使用してください
10. 構造化されたエラーログには slog（Go 1.21 以降）を使用することが望ましく、fmt.Println や log.Printf は使用しないでください
11. スタックトレース、ユーザー／テナントのコンテキスト、または構造化属性が必要な本番環境のエラーには、samber/oops を使用してください
12. HTTP リクエストは、メソッド、パス、ステータス、所要時間を取得する構造化ミドルウェアでログに記録してください
13. エラーの重大度を示すには、ログレベルを使用してください
14. 技術的なエラーをユーザーに公開してはいけません — 内部エラーはユーザーにわかりやすいメッセージに置き換え、技術的な詳細は別途ログに記録してください
15. ログのグループ化でカーディナリティを低く保ってください — ログ／APM の境界では、メッセージテンプレートを固定し、ID、パス、行番号、件数は構造化属性として付加してください。エラー値には運用上有用なコンテキストを含めてもかまいませんが、グループ化に使用する固定ログメッセージにカーディナリティの高いデータを含めないでください。

詳細リファレンス

• エラーの作成 — 何が起きたのかを伝えるエラーの作成方法について説明します。エラーメッセージは小文字で、句読点を使わず、行動を指示するのではなく何が起きたかを記述します。センチネルエラー（パフォーマンスのための事前割り当て）、カスタムエラー型（豊富なコンテキストを持たせるため）、および状況に応じた使い分けを示す判断表を取り上げます。

• エラーのラップと検査 — fmt.Errorf("{context}: %w", err) が fmt.Errorf("{context}: %v", err) より優れている理由（連鎖と連結の違い）を説明します。errors.Is、errors.As、型安全なエラー処理に使う Go 1.26+ の errors.AsType で連鎖を検査する方法と、独立したエラーを結合する errors.Join についても説明します。

• エラー処理パターンとロギング — 唯一の処理ルール、つまりエラーはログに記録するか返すかのどちらかであり、両方を行ってはならないこと（重複ログによる集約ツールの煩雑化を防ぎます）を説明します。panic/recover の設計、本番環境のエラーに使う samber/oops、および APM ツール向けの slog 構造化ロギング統合についても取り上げます。

エラー処理監査の並列化

大規模なコードベース全体のエラー処理を監査する場合は、最大 5 つの並列サブエージェントを使用し、それぞれ独立したエラーカテゴリを担当させます。

• サブエージェント 1：エラーの作成 — errors.New／fmt.Errorf の使用方法、カーディナリティの低いメッセージ、カスタム型を検証します
• サブエージェント 2：エラーのラップ — %w と %v の使い分けを監査し、errors.Is／errors.As のパターンを確認します
• サブエージェント 3：唯一の処理ルール — ログ記録と返却を両方行う違反、握りつぶされたエラー、破棄されたエラー（_）を探します
• サブエージェント 4：Panic/recover — panic の使用を監査し、goroutine の境界で復旧処理が行われていることを確認します
• サブエージェント 5：構造化ロギング — エラー箇所での slog の使用を検証し、エラーメッセージに PII が含まれていないか確認します

相互参照

• → samber/oops の API 全体、ビルダーパターン、ロガー統合については samber/cc-skills-golang@golang-samber-oops を参照してください
• → 構造化ロギングの設定、ログレベル、リクエストロギングミドルウェアについては samber/cc-skills-golang@golang-observability を参照してください
• → nil インターフェースの落とし穴と nil エラー比較の問題については samber/cc-skills-golang@golang-safety を参照してください
• → エラーの命名規則（ErrNotFound、PathError）については samber/cc-skills-golang@golang-naming を参照してください
• → これらのガイドラインを使用した、CI での AI による自動コードレビューについては samber/cc-skills-golang@golang-continuous-integration スキルを参照してください

参考資料

• lmittmann/tint
• samber/oops
• samber/slog-multi
• samber/slog-sampling
• samber/slog-formatter
• samber/slog-http
• samber/slog-sentry
• log/slog package