debugging-strategies

デバッグ戦略

実証済みの戦略、強力なツール、体系的なアプローチを活用して、いら立ちを伴う当てずっぽうのデバッグを、体系的な問題解決へと変えます。

このスキルを使う場面

• 見つけにくいバグを追跡する
• パフォーマンスの問題を調査する
• 不慣れなコードベースを理解する
• 本番環境の問題をデバッグする
• クラッシュダンプやスタックトレースを分析する
• アプリケーションのパフォーマンスをプロファイリングする
• メモリリークを調査する
• 分散システムをデバッグする

基本原則

1. 科学的手法

1. 観察する：実際にどのような動作をしていますか？ 2. 仮説を立てる：何が原因として考えられますか？ 3. 実験する：仮説を検証します 4. 分析する：仮説は証明されましたか、それとも否定されましたか？ 5. 繰り返す：根本原因が見つかるまで続けます

2. デバッグの心構え

決めつけないこと：

• 「Xのはずがない」——いえ、あり得ます
• 「Yは変更していない」——それでも確認します
• 「自分のマシンでは動く」——その理由を調べます

実践すること：

• 一貫して再現できるようにする
• 問題を切り分ける
• 詳細なメモを取る
• 何事も疑問を持って確認する
• 行き詰まったら休憩する

3. ラバーダック・デバッグ

コードと問題を声に出して説明します（ラバーダック、同僚、または自分自身に向けて）。そうすることで問題が見つかることがよくあります。

体系的なデバッグの手順

フェーズ 1：再現する

## Reproduction Checklist

1. **Can you reproduce it?**
   - Always? Sometimes? Randomly?
   - Specific conditions needed?
   - Can others reproduce it?

2. **Create minimal reproduction**
   - Simplify to smallest example
   - Remove unrelated code
   - Isolate the problem

3. **Document steps**
   - Write down exact steps
   - Note environment details
   - Capture error messages

フェーズ 2：情報を収集する

## Information Collection

1. **Error Messages**
   - Full stack trace
   - Error codes
   - Console/log output

2. **Environment**
   - OS version
   - Language/runtime version
   - Dependencies versions
   - Environment variables

3. **Recent Changes**
   - Git history
   - Deployment timeline
   - Configuration changes

4. **Scope**
   - Affects all users or specific ones?
   - All browsers or specific ones?
   - Production only or also dev?

フェーズ 3：仮説を立てる

## Hypothesis Formation

Based on gathered info, ask:

1. **What changed?**
   - Recent code changes
   - Dependency updates
   - Infrastructure changes

2. **What's different?**
   - Working vs broken environment
   - Working vs broken user
   - Before vs after

3. **Where could this fail?**
   - Input validation
   - Business logic
   - Data layer
   - External services

フェーズ 4：テストして検証する

## Testing Strategies

1. **Binary Search**
   - Comment out half the code
   - Narrow down problematic section
   - Repeat until found

2. **Add Logging**
   - Strategic console.log/print
   - Track variable values
   - Trace execution flow

3. **Isolate Components**
   - Test each piece separately
   - Mock dependencies
   - Remove complexity

4. **Compare Working vs Broken**
   - Diff configurations
   - Diff environments
   - Diff data

デバッグツールを選ぶ前、または二分探索、差分分析、トレース分析、メモリ分析を実施する前に、references/tools-and-techniques.mdを読んでください。

問題の種類別デバッグパターン

パターン 1：断続的に発生するバグ

## Strategies for Flaky Bugs

1. **Add extensive logging**
   - Log timing information
   - Log all state transitions
   - Log external interactions

2. **Look for race conditions**
   - Concurrent access to shared state
   - Async operations completing out of order
   - Missing synchronization

3. **Check timing dependencies**
   - setTimeout/setInterval
   - Promise resolution order
   - Animation frame timing

4. **Stress test**
   - Run many times
   - Vary timing
   - Simulate load

パターン 2：パフォーマンスの問題

## Performance Debugging

1. **Profile first**
   - Don't optimize blindly
   - Measure before and after
   - Find bottlenecks

2. **Common culprits**
   - N+1 queries
   - Unnecessary re-renders
   - Large data processing
   - Synchronous I/O

3. **Tools**
   - Browser DevTools Performance tab
   - Lighthouse
   - Python: cProfile, line_profiler
   - Node: clinic.js, 0x

パターン 3：本番環境のバグ

## Production Debugging

1. **Gather evidence**
   - Error tracking (Sentry, Bugsnag)
   - Application logs
   - User reports
   - Metrics/monitoring

2. **Reproduce locally**
   - Use production data (anonymized)
   - Match environment
   - Follow exact steps

3. **Safe investigation**
   - Don't change production
   - Use feature flags
   - Add monitoring/logging
   - Test fixes in staging

ベストプラクティス

1. まず再現する：再現できなければ修正できません
2. 問題を切り分ける：最小限のケースになるまで複雑さを取り除きます
3. エラーメッセージを読む：たいてい役に立ちます
4. 最近の変更を確認する：バグの多くは最近の変更が原因です
5. バージョン管理を使う：Gitのbisect、blame、履歴を活用します
6. 休憩する：新たな視点で見ると、よりよく気づけます
7. 調査結果を記録する：未来の自分の役に立ちます
8. 根本原因を修正する：症状だけでなく、根本原因を修正します

よくあるデバッグの間違い

• 複数の変更を同時に行う：一度に一つだけ変更します
• エラーメッセージを読まない：スタックトレース全体を読みます
• 複雑な問題だと思い込む：実際は単純なことがよくあります
• 本番環境でデバッグログを使う：リリース前に削除します
• デバッガーを使わない：console.logが常に最善とは限りません
• すぐに諦める：粘り強く取り組めば成果が得られます
• 修正をテストしない：実際に機能することを確認します

デバッグのクイックチェックリスト

## When Stuck, Check:

- [ ] Spelling errors (typos in variable names)
- [ ] Case sensitivity (fileName vs filename)
- [ ] Null/undefined values
- [ ] Array index off-by-one
- [ ] Async timing (race conditions)
- [ ] Scope issues (closure, hoisting)
- [ ] Type mismatches
- [ ] Missing dependencies
- [ ] Environment variables
- [ ] File paths (absolute vs relative)
- [ ] Cache issues (clear cache)
- [ ] Stale data (refresh database)