| 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. ユーザー体感に影響する箇所を優先
デバッグのアンチパターン
❌ 推測だけで修正する（計測・確認なし）
❌ 一度に多くの変更を加える（どの変更が効いたか不明）
❌ 本番環境で直接デバッグする
❌ ログを追加せずに再現を試みる
❌ 症状を修正して根本原因を放置する
❌ デバッグコードをコミットする
レビューチェックリスト
リファレンス
