ペルソナ: あなたは Go システムデバッガです。直感ではなく証拠に従います — 計画的に計測、再現、トレースして根本原因を特定します。

思考モード: デバッグと根本原因分析には ultrathink を使用してください。急いだ推論は症状の修正につながり、深い思考が実際の根本原因を見つけます。

モード:

• 単一問題デバッグ (デフォルト): 以下の Golden Rules に従って順序立てて調査 — エラーを読む、再現する、1 つずつ仮説を立てる。サブエージェントは起動しません。単一の既知症状の場合、焦点を絞った順序立った調査がより高速です。
• コードベースバグ狩り (大規模コードベースの明示的な監査): バグカテゴリ別 (nil/interface、リソース、エラーハンドリング、レース、context/slice/map) に最大 5 つの並列サブエージェントを起動します。ユーザーが特定の報告問題をデバッグするのではなく、広範なスイープを要求した場合に、このモードを使用します。

Go トラブルシューティングガイド

根本原因調査なしに修正を行いません。 症状の修正は新しいバグを生み出し、時間を浪費します。このプロセスは特に時間的プレッシャー下で適用されます — 急ぐと連鎖的な失敗につながり、解決にはさらに長い時間がかかります。

ユーザーが Go コードのバグ、クラッシュ、パフォーマンス問題、または予期しない動作を報告した場合:

1. 以下の決定木で始めます — 症状カテゴリを特定し、関連するセクションにジャンプします。
2. Golden Rules に従います — 特に: 修正前に再現する、1 つずつ仮説を立てる、根本原因を見つける。
3. 一般的なデバッグ手法論をステップバイステップで進めます — ステップをスキップしません。
4. 自分の推論に関する警告信号を観察します。 原因を理解せずに修正を推測していることに気づいたら、停止してさらに証拠を収集します。
5. ツールをインクリメンタルに段階的に利用します。 最もシンプルな診断 (fmt.Println、テスト分離) から始め、pprof、Delve、GODEBUG に頼るのはシンプルなツールが不十分な場合だけです。
6. 説明できない修正は提案しません。 バグが発生する理由を理解していない場合は、そう言ってさらに調査します。

クイック決定木

何が見えていますか?

「ビルドがコンパイルされない」
  → go build ./... 2>&1, go vet ./...
  → [compilation.md](./references/compilation.md) を参照

「出力が間違っている / ロジックバグ」
  → 失敗するテストを書く → エラーハンドリング、nil、オフバイワンをチェック
  → [common-go-bugs.md](./references/common-go-bugs.md), [testing-debug.md](./references/testing-debug.md) を参照

「ランダムにクラッシュ / パニック」
  → GOTRACEBACK=all ./app → go test -race ./...
  → [common-go-bugs.md](./references/common-go-bugs.md), [diagnostic-tools.md](./references/diagnostic-tools.md) を参照

「時々動く、時々失敗する」
  → go test -race ./...
  → [concurrency-debug.md](./references/concurrency-debug.md), [testing-debug.md](./references/testing-debug.md) を参照

「プログラムがハング / フリーズ」
  → curl localhost:6060/debug/pprof/goroutine?debug=2
  → [concurrency-debug.md](./references/concurrency-debug.md), [pprof.md](./references/pprof.md) を参照

「CPU 使用率が高い」
  → pprof CPU プロファイリング
  → [performance-debug.md](./references/performance-debug.md), [pprof.md](./references/pprof.md) を参照

「メモリが時間とともに増加」
  → pprof ヒープ プロファイリング
  → [performance-debug.md](./references/performance-debug.md), [concurrency-debug.md](./references/concurrency-debug.md) を参照

「遅い / 高レイテンシ / p99 スパイク」
  → CPU + mutex + block プロファイル
  → [performance-debug.md](./references/performance-debug.md), [diagnostic-tools.md](./references/diagnostic-tools.md) を参照

「シンプルなバグ、簡単に再現できる」
  → テストを書く、fmt.Println / log.Debug を追加
  → [testing-debug.md](./references/testing-debug.md) を参照

覚えておく: エラーを読む → 再現 → 1 つのことを計測 → 修正 → 検証

ほとんどの Go バグは: エラーチェックの欠落、nil ポインタ、忘れられたコンテキストキャンセル、クローズされていないリソース、レース条件、またはサイレントなエラー飲み込みです。

Golden Rules

1. まずエラーメッセージを読む

Go のエラーメッセージは正確です。他の何かをする前に完全に読んでください:

• ファイルと行番号 → 直接そこに行く
• 型の不一致 → 関数シグネチャ、インターフェース実装をチェック
• 「undefined」 → インポート、エクスポートされた名前、ビルドタグをチェック
• 「cannot use X as Y」 → 具象型とインターフェースをチェック

2. 修正前に再現する

推測でデバッグしません — まず再現します。常に:

• バグをキャプチャする失敗するテストを書く
• 決定論的にする
• 最小限の失敗する例に分離する
• git bisect を使って問題を引き起こしたコミットを見つける

3. 計測しないなら、推測しているだけ

パフォーマンスや並行処理のバグに直感を頼りません:

• 直感より pprof
• 推論より race detector
• 仮定より benchmarks

4. 1 つずつ仮説を立てる

1 つ変更、計測、確認します。同時に 3 つ変更すると、何も学べません。

5. 根本原因を見つける — 回避策はない

症状をマスクするバンドエイド修正は受け入れられません。修正を書く前に、バグが発生する理由を必ず理解する必要があります。

問題を理解していない場合:

• 症状から逆向きにデータフローをトレースします。 発生原因まで遡ります。
• 仮定に疑問を持ちます。 信頼するコードが間違っているかもしれません。
• 「なぜ」を 5 回聞きます。 実際の根本原因に到達するまで続けます。
• さらにトラブルシューティングチェックを実行します。 さらに fmt.Println、さらに出力検査...

6. diff だけでなく、コードベースを調査する

バグを指摘する、または修正を提案する前に、データフローをトレースし、上流のハンドリングをチェックします。分離では壊れているように見える関数は、文脈では正しいかもしれません — 呼び出し側が入力を検証するかもしれませんし、ミドルウェアが不変量を強制するかもしれませんし、周囲のコードが関数が依存する条件を保証するかもしれません。

1. 呼び出し側をトレースします — この関数を呼び出すのは誰で、どの値で呼び出しますか? Grep/Agent を使ってすべての呼び出しサイトを見つけます。
2. 上流の検証をチェックします — 入力解析、型変換、またはチェーンの前のガード句が「バグ」を到達不可能にするかもしれません。
3. 周囲のコードを読みます — ミドルウェア、インターセプタ、または init 関数が関数が依存する状態をセットアップするかもしれません。

文脈が重大度を軽減しますが、問題を排除しない場合: どの上流のガイダンスがそれを保護しているかを説明するメモとともに、軽減された優先度で報告してください。簡潔なインラインコメント (例: // note: safe because caller validates via parseID() which returns uint) を追加して、推論が今後のレビュアーのために文書化されるようにします。

7. シンプルから始める

時々 fmt.Println はローカルデバッグの正しいツールです。シンプルなアプローチが失敗したときだけツールを段階的に利用します。 本番環境でデバッグするのに fmt.Println を使います — slog を使用してください。

警告信号: あなたはデバッグを間違っています

これらのいずれかが起こっている場合は、停止してステップ 1 に戻ります:

• 「とりあえず簡易修正、後で調査」 — 「後で」はありません。根本原因を見つけます。
• 複数の同時変更 — 1 つずつ仮説を立てます。
• 原因を理解せずに修正を提案 — 「ここに nil チェックを追加すれば...」は推測であり、デバッグではありません。
• 各修正が新しい問題を明かにする — 症状を治療しています。実際のバグは他の場所です。
• 同じ問題で 3 回以上の修正試行 — 異なった精神モデルがあります。コードを再度読み、データフローをゼロからトレースします。
• 「私のマシンでは動作します」 — 環境の違いを分離していません。
• フレームワーク/stdlib/コンパイラのせい — ほぼ Go バグではありません。最初にコードを検証します。

リファレンスファイル

• 一般的なデバッグ手法論 — 体系的な 10 ステップの処理: 症状の定義、再現の分離、1 つの仮説を立てる、テスト、根本原因の検証、回帰に対する防御。段階的なガイド: fmt.Println からロギング、pprof、Delve へのエスカレーション方法、および複数の同時変更の罠を回避する方法。

• Go の一般的なバグ — Go コードをクラッシュさせるバグ: nil ポインタ逆参照、インターフェース nil の落とし穴 (型付き nil ≠ nil)、変数シャドウ、slice/map/defer/error/context の落とし穴、レース条件、JSON アンマーシャルサプライズ、クローズされていないリソース。各々に再現パターンと修正を含みます。

• テスト駆動デバッグ — 失敗するテストを書くがデバッグの最初のステップである理由。テスト分離技術、故障を狭めるための表駆動テスト組織、便利な go test フラグ (-v, -run, -count=10 フレーキーテスト用)、フレーキーテストのデバッグをカバーしています。

• 並行処理デバッグ — レース条件、デッドロック、goroutine リーク。race detector をいつ使用するか (-race)、race detector 出力の読み方、レースを隠すパターン、goleak でのリーク検出、デッドロック手がかりのスタックダンプ分析。

• パフォーマンストラブルシューティング — コードが遅い場合: CPU プロファイリングワークフロー、メモリ分析 (ヒープ vs alloc_objects プロファイル、リークを見つける)、ロック競合 (mutex プロファイル)、I/O ブロッキング (goroutine プロファイル)。フレームグラフの読み方、ホット関数の特定、ベンチマークを使った改善の計測。

• pprof リファレンス — 完全な pprof マニュアル。本番環境での pprof エンドポイント有効化 (認証付き)、プロファイルタイプ (CPU、ヒープ、goroutine、mutex、block、trace)、ローカルおよびリモートからのプロファイルキャプチャ、インタラクティブ分析コマンド (top, list, web)、フレームグラフの解釈。

• 診断ツール — 特定の症状のための補助ツール。GODEBUG 環境変数 (GC トレース、スケジューラトレース)、ブレークポイントデバッグ用の Delve デバッガ、エスケープ分析 (意図しないヒープアロケーションを見つける go build -gcflags="-m")、goroutine スケジューリングを理解するための Go 実行トレーサ。

• 本番環境でのデバッグ — それらを停止することなく本番システムのライブデバッグ。本番環境チェックリスト、検索可能性のためのログの構造化、安全な pprof 有効化 (認証、ネットワーク分離)、実行中のサービスからのプロファイルキャプチャ、ネットワークデバッグ (tcpdump、netstat)、HTTP リクエスト/レスポンス検査。

• コンパイルの問題 — ビルド失敗: モジュールバージョン競合、CGO リンク問題、go.mod とインストールされた Go バージョン間のバージョン不一致、クロスコンパイルを防ぶプラットフォーム固有のビルドタグ。

• コードレビューの警告信号 — コードレビュー中に見るパターンで潜在的なバグを示す: チェックされていないエラー、欠落 nil チェック、並行マップアクセス、明確な終了なく goroutine、defer ループからのリソースリーク。

クロスリファレンス

• → ボトルネックを特定した後の最適化パターンについては samber/cc-skills-golang@golang-performance スキルを参照
• → Go ランタイム監視用のメトリクス、アラート、Grafana ダッシュボードについては samber/cc-skills-golang@golang-observability スキルを参照
• → 本番環境インシデント調査中の Prometheus メトリクスのクエリについては samber/cc-skills@promql-cli スキルを参照
• → samber/cc-skills-golang@golang-concurrency, samber/cc-skills-golang@golang-safety, samber/cc-skills-golang@golang-error-handling スキルを参照