bug-detective

Bug Detective

コードのエラー、例外、失敗を調査して解決するための体系的なデバッグワークフローです。構造化されたデバッグ手法と、一般的なエラーパターンの認識方法を提供します。

基本理念

デバッグは、次の手順を踏む科学的な問題解決プロセスです。

1. 問題を理解する - 症状と期待される動作を明確に定義します
2. 証拠を集める - エラーメッセージ、ログ、スタックトレースを収集します
3. 仮説を立てる - 証拠に基づいて考えられる原因を推測します
4. 仮説を検証する - 実験を通じて原因を確認するか、除外します
5. 問題を解決する - 修正を適用して検証します

デバッグワークフロー

ステップ 1：問題を理解する

デバッグを始める前に、次の情報を明確にします。

収集が必要な情報：

• エラーメッセージの全文
• エラーの正確な発生場所（ファイル名と行番号）
• 再現手順（エラーを発生させる方法）
• 期待される動作と実際の動作
• 環境情報（OS、バージョン、依存関係）

質問テンプレート：

1. What is the exact error message?
2. Which file and line does the error occur at?
3. How can this issue be reproduced? Provide detailed steps.
4. What was the expected result? What actually happened?
5. What recent changes might have introduced this issue?

ステップ 2：エラーの種類を分析する

エラーの種類に応じてデバッグ戦略を選択します。

エラーの種類	特徴	デバッグ方法
構文エラー	コードを解析できない	構文、括弧の対応、引用符を確認する
インポートエラー	ModuleNotFoundError	モジュールのインストール、パス設定を確認する
型エラー	TypeError	データ型、型変換を確認する
属性エラー	AttributeError	オブジェクトに属性が存在するか確認する
キーエラー	KeyError	辞書にキーが存在するか確認する
インデックスエラー	IndexError	リスト／配列のインデックス範囲を確認する
ヌル参照	NoneType/NullPointerException	変数が None かどうか確認する
ネットワークエラー	ConnectionError/Timeout	ネットワーク接続、URL、タイムアウト設定を確認する
権限エラー	PermissionError	ファイル権限、ユーザー権限を確認する
リソースエラー	FileNotFoundError	ファイルパスが存在するか確認する

ステップ 3：問題の発生源を特定する

次の方法で問題を特定します。

1. 二分探索法

• コードの半分をコメントアウトし、問題が引き続き発生するか確認します
• 問題のあるコードが見つかるまで、対象範囲を段階的に絞り込みます

2. ログトレース

• 重要な箇所に print/logging 文を追加します
• 変数値の変化を追跡します
• コードの実行経路を確認します

3. ブレークポイントデバッグ

• デバッガーのブレークポイント機能を使用します
• コードの実行をステップ実行します
• 変数の状態を調べます

4. スタックトレースの分析

• エラーメッセージ内のスタックトレースから呼び出しチェーンを見つけます
• エラーの直接的な原因を特定します
• 根本原因までさかのぼります

ステップ 4：仮説を立てて検証する

仮説のフレームワーク：

Hypothesis: [problem description] causes [error phenomenon]

Verification steps:
1. [verification method 1]
2. [verification method 2]

Expected results:
- If hypothesis is correct: [expected phenomenon]
- If hypothesis is wrong: [expected phenomenon]

ステップ 5：修正を適用する

修正後、次の点を確認します。

1. 元のエラーが解決されている
2. 新たなエラーが発生していない
3. 関連機能が引き続き正しく動作する
4. 再発防止のためのテストが追加されている

Python の一般的なエラーパターン

1. インデントエラー

2. 可変デフォルト引数

3. ループ内のクロージャの問題

4. 反復処理中のリストの変更

5. 文字列比較での is の使用

6. super().__init__() の呼び出し忘れ

JavaScript/TypeScript の一般的なエラーパターン

1. this のバインドの問題

2. 非同期エラー処理

3. オブジェクト参照の比較

Bash/Zsh の一般的なエラーパターン

1. スペースの問題

# ❌ No spaces allowed in assignment
name = "John"  # Error: tries to run 'name' command

# ✅ Correct assignment
name="John"

# ❌ Missing spaces in conditional test
if[$name -eq 1]; then  # Error

# ✅ Correct
if [ $name -eq 1 ]; then

2. 引用符の問題

# ❌ Variables not expanded inside single quotes
echo 'The value is $var'  # Output: The value is $var

# ✅ Use double quotes
echo "The value is $var"  # Output: The value is actual_value

# ❌ Using backticks for command substitution (confusing)
result=`command`

# ✅ Use $()
result=$(command)

3. 引用符で囲まれていない変数

# ❌ Unquoted variable, empty value causes errors
rm -rf $dir/*  # If dir is empty, deletes all files in current directory

# ✅ Always quote variables
[ -n "$dir" ] && rm -rf "$dir"/*

# Or use set -u to prevent undefined variables
set -u  # or set -o nounset

4. ループ内の変数スコープ

# ❌ Pipe creates subshell, outer variable unchanged
cat file.txt | while read line; do
    count=$((count + 1))  # Outer count won't change
done
echo "Total: $count"  # Outputs 0

# ✅ Use process substitution or redirection
while read line; do
    count=$((count + 1))
done < file.txt
echo "Total: $count"  # Correct output

5. 配列操作

# ❌ Incorrect array access
arr=(1 2 3)
echo $arr[1]  # Outputs 1[1]

# ✅ Correct array access
echo ${arr[1]}  # Outputs 2
echo ${arr[@]}  # Outputs all elements
echo ${#arr[@]} # Outputs array length

6. 文字列比較

# ✅ Use `=` inside POSIX `[` tests and `==` inside Bash `[[ ]]` tests
if [ "$name" = "John" ]; then
if [[ "$name" == "John" ]]; then

# ❌ Using -eq for numeric comparison instead of =
if [ $age = 18 ]; then  # Wrong

# ✅ Use arithmetic operators for numeric comparison
if [ $age -eq 18 ]; then
if (( age == 18 )); then

7. コマンド失敗後も実行が続く

# ❌ Execution continues after command failure
cd /nonexistent
rm file.txt  # Deletes file.txt in current directory

# ✅ Use set -e to exit on error
set -e  # or set -o errexit
cd /nonexistent  # Script exits here
rm file.txt

# Or check if command succeeded
cd /nonexistent || exit 1

一般的なデバッグコマンド

Python pdb デバッガー

python -m pdb script.py
pytest -x -vv tests/test_target.py

Node.js インスペクター

node --inspect-brk app.js
node --trace-warnings app.js

Git Bisect

git bisect start
git bisect bad
git bisect good <known-good-commit>

Bash のデバッグ

# Run script in debug mode
bash -x script.sh  # Print each command
bash -v script.sh  # Print command source
bash -n script.sh  # Syntax check, no execution

# Enable debugging within a script
set -x  # Enable command tracing
set -v  # Enable verbose mode
set -e  # Exit on error
set -u  # Error on undefined variables
set -o pipefail  # Fail if any command in pipe fails

デバッグの予防策

1. 型チェックを使用する

2. 入力を検証する

3. 防御的プログラミング

4. ロギング

デバッグチェックリスト

開始前

• エラーメッセージ全文を取得します
• エラーのスタックトレースを記録します
• 再現手順を確認します
• 期待される動作を把握します

デバッグ中

• 最近のコード変更を確認します
• 二分探索を使って問題箇所を特定します
• ログを追加して変数を追跡します
• 仮説を検証します

解決後

• 元のエラーが修正されたことを確認します
• 関連する機能をテストします
• 回帰を防ぐテストを追加します
• 問題と解決策を記録します

追加リソース

参考ファイル

詳細なデバッグ手法とパターンについては、以下を参照してください。

• references/python-errors.md - Python のエラーの詳細
• references/javascript-errors.md - JavaScript/TypeScript のエラーの詳細
• references/shell-errors.md - Bash/Zsh スクリプトのエラーの詳細
• references/debugging-tools.md - デバッグツールの使用ガイド
• references/common-patterns.md - よくあるエラーパターン

サンプルファイル

動作するデバッグのサンプル：

• examples/debugging-workflow.py - デバッグワークフローの完全なサンプル
• examples/error-handling-patterns.py - エラー処理パターン
• examples/debugging-workflow.sh - シェルスクリプトのデバッグ例