debugging

name	debugging
description	フロントエンド・バックエンド両対応のデバッグガイド（フレームワーク非依存）。デバッグワークフロー（再現→切り分け→原因特定→修正→検証）、問題の切り分け手法、フロントエンドデバッグ（レンダリング/状態/イベント/通信）、バックエンドデバッグ（ログ解析/リクエストトレース/データフロー）、よくあるエラーパターン、パフォーマンスデバッグをカバー。原因不明のバグ調査、パフォーマンス問題、エラー解析時に使用。

デバッグガイド

フロントエンド・バックエンド両対応のフレームワーク非依存なデバッグガイド。

デバッグワークフロー

1. 再現      → 問題を確実に再現する条件を特定
2. 切り分け  → 問題の発生箇所を絞り込む
3. 原因特定  → 根本原因を特定する
4. 修正      → 最小限の変更で修正する
5. 検証      → 修正の確認 + 回帰テスト作成

再現のコツ

- 最小再現ケースを作る（関係ない要素を排除）
- 再現条件を明確化: ブラウザ、OS、データ、タイミング
- 再現率が低い場合: ログ追加 → 再発を待つ
- 「自分の環境では再現しない」→ 環境差異をリストアップ

問題の切り分け

発生箇所の特定

ユーザーから見える問題
├→ 画面に表示されない / 表示がおかしい
│   └→ フロントエンド問題の可能性大
├→ データが保存されない / 取得できない
│   └→ バックエンド or DB 問題の可能性大
├→ 動作が遅い
│   └→ パフォーマンス問題 → 計測で特定
└→ 特定の条件でのみ発生
    └→ エッジケース → 条件の切り分け

レイヤー別切り分け

フロントエンド → ネットワーク → バックエンド → DB

確認手順:
1. ブラウザの開発者ツールでネットワークを確認
   → リクエストは送信されているか？
   → レスポンスは正しいか？
2. 正しいリクエストが送信されている場合
   → バックエンドのログを確認
3. バックエンドのレスポンスが正しい場合
   → フロントエンドの描画/状態管理を確認

フロントエンドデバッグ

レンダリング問題

症状: 表示されない、レイアウト崩れ、更新されない

確認ポイント:
  - コンポーネントは描画されているか（DOM を確認）
  - CSS が意図通りか（計算済みスタイルを確認）
  - 条件付きレンダリングの条件は正しいか
  - キー属性は適切か（リスト描画時）

状態管理問題

症状: データが反映されない、古い値が表示される

確認ポイント:
  - 状態の更新は行われているか
  - 不変性は保たれているか（ミュータブルな更新をしていないか）
  - 非同期更新のタイミングは正しいか
  - 状態のスコープは適切か（ローカル vs グローバル）

イベント問題

症状: クリックが反応しない、二重送信、意図しない動作

確認ポイント:
  - イベントハンドラは登録されているか
  - イベントの伝播（バブリング）が問題ではないか
  - デバウンス/スロットルは適切か
  - フォーム送信のデフォルト動作は制御されているか

通信問題

症状: API からデータが取得できない、エラーレスポンス

確認ポイント:
  - リクエスト URL・メソッド・ヘッダーは正しいか
  - CORS エラーが出ていないか
  - 認証トークンは送信されているか
  - レスポンスのパース処理は正しいか
  - エラーハンドリングは適切か

詳細: references/frontend-debugging.md

バックエンドデバッグ

ログ解析

手順:
1. エラーログからスタックトレースを確認
2. リクエスト ID でログを絞り込む
3. タイムスタンプで時系列を追う
4. エラー直前の正常ログを確認（何が変わったか）

注意:
  - ログレベルが適切か確認（DEBUG に切り替え）
  - 構造化ログを活用してフィルタリング
  - 大量のログは grep/検索で効率的に

リクエストトレース

確認ポイント:
  - リクエストは到達しているか（アクセスログ）
  - ミドルウェアの処理順序
  - 認証/認可チェックの結果
  - ルーティングは正しいか
  - レスポンスの構築過程

データフロー

確認ポイント:
  - 入力データのバリデーション結果
  - データ変換（DTO → Entity）は正しいか
  - DB クエリは意図通りか（実行 SQL を確認）
  - 外部 API のレスポンスは期待通りか
  - トランザクション境界は適切か

詳細: references/backend-debugging.md

よくあるエラーパターン

一般的なエラー

エラー	よくある原因	対処
null/undefined 参照	データ未取得、非同期タイミング	Optional chaining、ガード節
型エラー	API レスポンスの型不一致	型定義の確認、バリデーション
タイムアウト	遅い外部 API、DB ロック	タイムアウト設定、非同期化
メモリリーク	解放忘れ、無限成長するキャッシュ	プロファイリング、クリーンアップ
競合状態	並行処理の制御不足	ロック、楽観的ロック、キュー

HTTP エラー別の原因

コード	よくある原因
400	リクエストボディの形式不正、バリデーションエラー
401	トークン期限切れ、認証ヘッダー未送信
403	権限不足、CORS の preflight 失敗
404	パス間違い、リソース未作成、ルーティング設定ミス
422	ビジネスロジック上のバリデーションエラー
500	未処理例外、DB 接続失敗、外部 API 障害
502/503	サーバーダウン、デプロイ中、リソース不足

詳細: references/common-errors.md

パフォーマンスデバッグ

フロントエンド

確認ポイント:
  - 初期表示時間（FCP, LCP）
  - 不要な再レンダリング
  - バンドルサイズ（大きなライブラリの読み込み）
  - 画像の最適化（サイズ、フォーマット、遅延読み込み）
  - メモリリーク（長時間使用での劣化）

バックエンド

確認ポイント:
  - レスポンス時間の遅いエンドポイント特定
  - N+1 クエリ問題
  - インデックス未設定のクエリ
  - 不要なデータの取得（SELECT *）
  - 外部 API 呼び出しの遅延
  - コネクションプールの枯渇

計測の原則

1. 推測するな、計測せよ
2. ボトルネックを特定してから最適化
3. 最適化前後で必ず計測・比較
4. ユーザー体感に影響する箇所を優先

デバッグのアンチパターン

❌ 推測だけで修正する（計測・確認なし）
❌ 一度に多くの変更を加える（どの変更が効いたか不明）
❌ 本番環境で直接デバッグする
❌ ログを追加せずに再現を試みる
❌ 症状を修正して根本原因を放置する
❌ デバッグコードをコミットする

レビューチェックリスト

• 問題の根本原因が特定されている
• 修正は最小限の変更に留まっている
• 回帰テストが追加されている
• デバッグ用のコード（console.log 等）が残っていない
• 同様の問題が他の箇所にないか確認した
• エラーハンドリングが改善されている

リファレンス

• references/frontend-debugging.md - フロントエンドデバッグ詳細
• references/backend-debugging.md - バックエンドデバッグ詳細
• references/common-errors.md - よくあるエラーパターンと解決策