bug-hunter

バグハンター

実証済みのデバッグ手法を使って、体系的にバグを探し、修正します。推測はせず、証拠に従ってください。

このスキルを使う場面

• ユーザーからバグやエラーの報告があったとき
• 期待どおりに動作しないとき
• ユーザーが「バグを修正して」や「デバッグして」と言ったとき
• 断続的な失敗や奇妙な動作があるとき
• 本番環境の問題を調査する必要があるとき

デバッグのプロセス

1. バグを再現する

まず、問題を一貫して発生させます。

1. Get exact steps to reproduce
2. Try to reproduce locally
3. Note what triggers it
4. Document the error message/behavior
5. Check if it happens every time or randomly

再現できない場合は、さらに情報を集めます。

• どの環境ですか？（開発、ステージング、本番）
• どのブラウザー／デバイスですか？
• その前にユーザーはどのような操作をしましたか？
• エラーログはありますか？

2. 証拠を集める

入手可能な情報をすべて集めます。

ログを確認する：

# Application logs
tail -f logs/app.log

# System logs
journalctl -u myapp -f

# Browser console
# Open DevTools → Console tab

エラーメッセージを確認する：

• スタックトレース全体
• エラーの種類とメッセージ
• 行番号
• タイムスタンプ

状態を確認する：

• どのデータが処理されていましたか？
• ユーザーは何をしようとしていましたか？
• データベースには何がありますか？
• ローカルストレージ／Cookieには何がありますか？

3. 仮説を立てる

証拠に基づいて、何が問題なのか推測します。

"The login times out because the session cookie 
expires before the auth check completes"

"The form fails because email validation regex 
doesn't handle plus signs"

"The API returns 500 because the database query 
has a syntax error with special characters"

4. 仮説を検証する

推測が正しいかどうかを証明します。

ログを追加する：

console.log('Before API call:', userData);
const response = await api.login(userData);
console.log('After API call:', response);

デバッガーを使う：

debugger; // Execution pauses here
const result = processData(input);

問題を切り分ける：

// Comment out code to narrow down
// const result = complexFunction();
const result = { mock: 'data' }; // Use mock data

5. 根本原因を見つける

実際の問題までさかのぼって追跡します。

よくある根本原因：

• Null／undefined の値
• 誤ったデータ型
• 競合状態
• エラーハンドリングの不足
• 不正なロジック
• 1 つずれたエラー
• 非同期処理／await の問題
• バリデーションの不足

追跡の例：

Symptom: "Cannot read property 'name' of undefined"
↓
Where: user.profile.name
↓
Why: user.profile is undefined
↓
Why: API didn't return profile
↓
Why: User ID was null
↓
Root cause: Login didn't set user ID in session

6. 修正を実装する

症状ではなく、根本原因を修正します。

悪い修正（症状への対処）：

// Just hide the error
const name = user?.profile?.name || 'Unknown';

良い修正（根本原因への対処）：

// Ensure user ID is set on login
const login = async (credentials) => {
  const user = await authenticate(credentials);
  if (user) {
    session.userId = user.id; // Fix: Set user ID
    return user;
  }
  throw new Error('Invalid credentials');
};

7. 修正をテストする

実際に動作することを確認します。

1. Reproduce the original bug
2. Apply the fix
3. Try to reproduce again (should fail)
4. Test edge cases
5. Test related functionality
6. Run existing tests

8. 再発を防ぐ

問題が再発しないようにテストを追加します。

test('login sets user ID in session', async () => {
  const user = await login({ email: '[email protected]', password: 'pass' });
  
  expect(session.userId).toBe(user.id);
  expect(session.userId).not.toBeNull();
});

デバッグ手法

二分探索

問題の範囲を繰り返し半分に絞り込みます。

// Does the bug happen before or after this line?
console.log('CHECKPOINT 1');
// ... code ...
console.log('CHECKPOINT 2');
// ... code ...
console.log('CHECKPOINT 3');

ラバーダックデバッグ

コードを一行ずつ声に出して説明します。説明しているうちに問題に気づくことがよくあります。

プリントデバッグ

console.log を戦略的に使います。

console.log('Input:', input);
console.log('After transform:', transformed);
console.log('Before save:', data);
console.log('Result:', result);

差分デバッグ

正常な状態と壊れた状態を比較します。

• 最近、何が変わりましたか？
• 環境間で何が異なりますか？
• データにどのような違いがありますか？

タイムトラベルデバッグ

git を使って、いつ問題が発生したかを特定します。

git bisect start
git bisect bad  # Current commit is broken
git bisect good abc123  # This old commit worked
# Git will check out commits for you to test

よくあるバグのパターン

Null／Undefined

// Bug
const name = user.profile.name;

// Fix
const name = user?.profile?.name || 'Unknown';

// Better fix
if (!user || !user.profile) {
  throw new Error('User profile required');
}
const name = user.profile.name;

競合状態

// Bug
let data = null;
fetchData().then(result => data = result);
console.log(data); // null - not loaded yet

// Fix
const data = await fetchData();
console.log(data); // correct value

1 つずれたエラー

// Bug
for (let i = 0; i <= array.length; i++) {
  console.log(array[i]); // undefined on last iteration
}

// Fix
for (let i = 0; i < array.length; i++) {
  console.log(array[i]);
}

型強制

// Bug
if (count == 0) { // true for "" and []; false for null
  
// Fix
if (count === 0) { // only true for 0

Await を使わない非同期処理

// Bug
const result = asyncFunction(); // Returns Promise
console.log(result.data); // undefined

// Fix
const result = await asyncFunction();
console.log(result.data); // correct value

デバッグツール

ブラウザーの DevTools

Console: View logs and errors
Sources: Set breakpoints, step through code
Network: Check API calls and responses
Application: View cookies, storage, cache
Performance: Find slow operations

Node.js のデバッグ

// Built-in debugger
node --inspect app.js

// Then open chrome://inspect in Chrome

VS Code でのデバッグ

// .vscode/launch.json
{
  "type": "node",
  "request": "launch",
  "name": "Debug App",
  "program": "${workspaceFolder}/app.js"
}

行き詰まったとき

1. 休憩する（本当に、10 分間その場を離れてください）
2. 誰か（またはラバーダック）に説明する
3. エラーメッセージをそのまま検索する
4. 既知の問題かどうか確認する（GitHub の issue、Stack Overflow）
5. 単純化する：最小限の再現ケースを作成する
6. 最初からやり直す：問題のあるコードを削除して書き直す
7. 助けを求める（背景と試したことを伝える）

ドキュメントのテンプレート

修正した後に記録します。

## Bug: Login timeout after 30 seconds

**Symptom:** Users get logged out immediately after login

**Root Cause:** Session cookie expires before auth check completes

**Fix:** Increased session timeout from 30s to 3600s in config

**Files Changed:**
- config/session.js (line 12)

**Testing:** Verified login persists for 1 hour

**Prevention:** Added test for session persistence

主な原則

• まず再現し、その後で修正する
• 推測せず、証拠に従う
• 症状ではなく根本原因を修正する
• 修正を十分にテストする
• 再発を防ぐテストを追加する
• 学んだことを記録する

関連スキル

• @systematic-debugging - 高度なデバッグ
• @test-driven-development - テスト
• @codebase-audit-pre-push - コードレビュー

制限事項

• タスクが上記の対象範囲に明確に一致する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。

許可リストに含まれる、秘密情報ではない診断情報のみを記録してください。userData、認証ペイロード、完全なレスポンスには、トークンやプライベートな記録が含まれる可能性があります。ログを追加する前に、権限を得た隔離環境で再現してください。git bisect には使い捨てのクリーンなチェックアウトを使用し、実際の良好なリビジョンと不良なリビジョンを記録したうえで、最後に git bisect reset を実行してください。ユーザーの変更は保持してください。包括的な削除や書き換えではなく、証拠に裏付けられた最小限の修正を優先し、テスト出力の例と実際に観測された結果を区別してください。