shared-bug-investigation

バグ調査 - 科学的手法

科学的な方法論を適用し、ソフトウェアのバグを体系的に調査して解決します。

科学的手法のプロセス

1. 観察 - 問題に関するデータを収集します
2. 仮説 - 検証可能な説明を可能性の高い順に立てます
3. 実験 - 制御された変更を加えて仮説を検証します
4. 分析 - 結果を客観的に解釈します
5. 結論 - 根本原因を特定し、修正を検証します

基本原則

• まずコンテキストを把握 - 調査の前にプロジェクトを理解します
• 仮説に基づいて進める - 検証可能な仮説を立てずに解決策へ飛びついてはいけません
• 変数を切り分ける - 一度に1つのことだけを変更します
• 確実に再現する - 再現できない問題は修正できません
• 症状より根本原因を重視 - 表面的な修正で済ませず、深く掘り下げます
• 厳密に検証する - 修正によって問題が解決し、リグレッションが発生しないことを確認します

調査ワークフロー

フェーズ1：プロジェクトのコンテキスト（2～5分）

調査の前に把握すること：

• 言語とバージョン（Python 3.11、Java 17、Go 1.21 など）
• ビルドシステム（Gradle、npm、Cargo、Make など）
• 主要な依存関係とフレームワーク
• アーキテクチャパターン（MVC、マイクロサービスなど）
• テスト環境

手早く把握する：

# Find package managers
view package.json / requirements.txt / Cargo.toml / pom.xml

# Check config files  
view .env / config.yml / settings.py

# Identify entry points
view main.* / index.* / app.*

出力：コンテキストを1行でまとめる

Python 3.11, Flask API, PostgreSQL, pytest, Docker

フェーズ2：問題の定義

収集する情報：

• エラーメッセージ（全文、コード）
• スタックトレース／ログ
• 再現手順
• 期待される動作と実際の動作
• 環境（OS、バージョン、設定）
• 再現性（常に／ときどき／まれ）

記録する：

Bug: [Short description]
Reproduces: [Always/Sometimes/Unable]
Error: [Key error message]
Steps:
1. [Action 1]
2. [Action 2]
3. [Failure occurs]
Expected: [What should happen]
Actual: [What happens]

フェーズ3：仮説（可能性の高い順）

フェーズ3：仮説（可能性の高い順）

検証可能な仮説を2～4個、可能性の高い順に立てます。

H1：[最も可能性の高い原因]

• 根拠：［可能性が高い理由］
• テスト：［立証または反証する方法］
• 正しい場合：［予想される結果］
• 誤りの場合：［予想される結果］

H2：[別の原因]

• 根拠：［裏付けとなる観察結果］
• テスト：［反証可能な実験］

よくあるカテゴリ：

• ロジックエラー（オフバイワン、演算子の誤り、不適切な条件）
• 状態の問題（競合状態、未初期化、古いデータ）
• 型／データ（null／nil、型の不一致、解析エラー）
• 並行処理（データ競合、デッドロック、スレッドセーフティ）
• 統合（API の不一致、バージョン非互換）
• 環境（設定、プラットフォーム固有の問題、リソース制限）

フェーズ4：実験

各仮説について：

H1 をテスト：[仮説名]

• 変更：［変更する変数を1つ］
• 測定：［観察する内容］
• 方法：［具体的な手順］
• 結果：［実際の結果］
• 結論：［検証済み／棄却］

手法：

• 重要な箇所にログを追加する
• デバッガーのブレークポイントを使う
• 二分探索する（コードの半分を取り除く）
• 最小限の再現ケースを作る（本質的な部分だけに絞る）
• 動作する状態と壊れた状態の差分を確認する
• コンポーネントを切り分ける

フェーズ5：根本原因

特定された原因： ［実際の原因を明確に記述］

根拠： ［観察 → 仮説 → 検証の流れ］

発生した理由：

• 直接的な原因：［技術的な理由］
• 寄与要因：［何がこの状況を可能にしたか］
• 構造的な原因：［より根深い問題があれば記述］

フェーズ6：解決と検証

修正： ［実施する具体的な変更］

この修正で解決する理由： ［因果関係を説明］

検証：

1. バグを再現する（失敗を確認）
2. 修正を適用する
3. 再テストする（成功を確認）
4. エッジケースをテストする
5. テストスイートを実行する（リグレッションがないことを確認）
6. このバグのテストを追加する

再発防止：

• ［追加するテスト］
• ［追加するアサーション］
• ［避けるパターン］

調査手法

二分探索： コードの半分を取り除き、バグが残るかテストします。問題が残る半分に対して繰り返し、原因を特定します。

最小限の再現ケース： 問題を再現する50行未満のコードに絞り込みます。余分な要素を取り除けます。

差分テスト： 動作する状態と壊れた状態（コミット、バージョン、設定）を比較します。

戦略的なログ出力： 重要な判断箇所に出力を追加し、実行フローを追跡します。

ラバーダックデバッグ： コードを1行ずつ声に出して説明します。ロジックエラーが見つかることがよくあります。

よくあるバグのパターン（言語に依存しない）

ロジックエラー：

• オフバイワン：i < n と i <= n の違い
• 演算子の誤り：&& と ||、== と =
• 否定の誤り：!condition のロジックが反転している

状態の問題：

• 競合状態：同期せずに並行アクセスしている
• 初期化漏れ：値を設定する前に変数を使用している
• 古い状態：キャッシュされた古いデータを使用している

型／データ：

• Null／nil のデリファレンス
• 型変換のエラー
• 整数オーバーフロー
• 浮動小数点数の精度

並行処理：

• デッドロック：ロックを相互に待ち続けている
• データ競合：共有データに同期せずアクセスしている
• スレッドセーフティ：複数スレッドでスレッドセーフでないコードを実行している

統合：

• API コントラクトの不一致
• バージョンの非互換性
• 依存関係の不足
• 設定の誤り

出力形式

# Bug Investigation: [Name]

## Context
[One-line: Language, framework, architecture]

## Problem
Error: [Message]
Reproduces: [Always/Sometimes]
Steps: [1,2,3]

## Hypotheses
H1: [Most likely] - Test by [method]
H2: [Alternative] - Test by [method]

## Investigation
Tested H1: [Result - validated/invalidated]
[If needed] Tested H2: [Result]

## Root Cause
[One sentence explanation]
Evidence: [What confirmed it]

## Solution
Fix: [Specific change]
Why it works: [Explanation]
Validated: [Tested successfully]

## Prevention
- Test added: [Description]
- Warning signs: [What to watch for]

すばやく判断するためのフローチャート

症状 → 考えられるカテゴリ：

• 断続的に失敗する → 並行処理／状態
• 常に同じように失敗する → ロジックエラー
• Null／nil によるクラッシュ → 型／データ
• 特定の環境でのみ発生する → 設定
• パフォーマンスの低下 → リソース／アルゴリズム
• 依存関係の更新後に発生する → 統合

重要な注意事項

• まずコンテキストの把握から始めます
• コードを書く前に仮説を立てます
• 一度に変更する変数は1つだけにします
• 修正前に再現します
• 修正を厳密に検証します
• リグレッションテストを追加します
• 根本原因を記録します