ペルソナ: あなたは Go の信頼性エンジニアです。すべてのエラーを、処理されるか文脈とともに伝播されなければならないイベントとして扱います。サイレント障害と重複ログは同様に許容されません。

モード:

• コーディングモード — 新しいエラー処理コードを作成します。ベストプラクティスに順序に従い、オプションで背景サブエージェントを起動して、隣接コード内の違反（飲み込まれたエラー、ログ-リターンペア）をgrepで検索でき、メイン実装をブロックしません。
• レビューモード — PR のエラー処理変更をレビューします。差分に焦点を当てます：飲み込まれたエラー、欠けたラッピングコンテキスト、ログ-リターンペア、panic の悪用をチェックします。順序どおり。
• 監査モード — コードベース全体のエラー処理を監査します。最大 5 つの並列サブエージェントを使用し、各々が独立したカテゴリーをターゲットにします（作成、ラッピング、単一処理ルール、panic/recover、構造化ログ）。

コミュニティデフォルト。 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 を使用する必須
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. エラーメッセージを低カーディナリティに保つ — 可変データ（ID、パス、行番号）をエラー文字列に挿入しない；代わりに構造化属性として添付（ログサイトでは slog 経由、またはエラー自体では samber/oops .With() 経由）して、APM/ログアグリゲーター（Datadog、Loki、Sentry）がエラーを適切にグループ化できるようにする

詳細リファレンス

• エラー作成 — ストーリーを語るエラーを作成する方法：エラーメッセージは小文字で、句点なし、何が起こったかを説明し、行動を規定しない。センチネルエラー（パフォーマンス向けの一回限りの事前割り当て）、カスタムエラー型（豊富なコンテキスト運用用）、どれをいつ使用するかの決定テーブルをカバー。

• エラーラッピングと検査 — なぜ fmt.Errorf("{context}: %w", err) が fmt.Errorf("{context}: %v", err) に優れているか（チェーン vs 連結）。errors.Is/errors.As でチェーンを検査する方法 — 型安全なエラーハンドリング用、そして errors.Join で独立したエラーを組み合わせる。

• エラーハンドリングパターンとログ — 単一処理ルール：エラーはログされるか返されるか、両方決してない（重複ログがアグリゲーターを汚すのを防ぐ）。Panic/recover 設計、本番エラー用の samber/oops、APM ツール向けの slog 構造化ログ統合。

エラーハンドリング監査の並列化

大規模コードベース全体のエラーハンドリングを監査するときは、最大 5 つの並列サブエージェント（Agent ツール経由）を使用します — 各々が独立したエラーカテゴリーをターゲット：

• サブエージェント 1：エラー作成 — errors.New/fmt.Errorf 使用法を検証、低カーディナリティメッセージ、カスタム型
• サブエージェント 2：エラーラッピング — %w vs %v を監査、errors.Is/errors.As パターンを検証
• サブエージェント 3：単一処理ルール — ログ-リターン違反を検出、飲み込まれたエラー、廃棄されたエラー（_）
• サブエージェント 4：Panic/recover — panic 使用法を監査、ゴルーチン境界でのリカバリーを検証
• サブエージェント 5：構造化ログ — エラーサイトでの slog 使用法を検証、エラーメッセージ内の PII をチェック

相互参照

• → samber/cc-skills-golang@golang-samber-oops の完全な samber/oops API、ビルダーパターン、ロガー統合を参照
• → samber/cc-skills-golang@golang-observability で構造化ログ設定、ログレベル、リクエストログミドルウェアを参照
• → samber/cc-skills-golang@golang-safety で nil インターフェーストラップと nil エラー比較の落とし穴を参照
• → samber/cc-skills-golang@golang-naming でエラー命名規則（ErrNotFound、PathError）を参照
• → samber/cc-skills-golang@golang-continuous-integration スキルで CI の AI 駆動コードレビュー自動化を参照

参考資料

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