debug

デバッグ

エラー、テストの失敗、予期しない動作、本番環境の問題を体系的にデバッグします。

使用方法

/debug [issue] [--logs] [--correlate] [--trace] [--type bug|build|perf|deploy]

オプション

フラグ	目的
--logs	ログパターン分析を有効にします（エラーの急増、頻度、種類）
--correlate	構造化ログに対して SQL 相関クエリを実行します
--trace	コンテキストを含めた詳細なスタックトレース分析を行います
--type	問題のカテゴリ：bug、build、perf(ormance)、deploy(ment)

使用するタイミング

• エラーメッセージやスタックトレースが表示される
• テストが失敗する
• コードが予期しない動作をする
• ユーザーが「壊れています」や「動きません」と言う
• 本番環境のエラーを調査する必要がある（--logs）
• システム間でエラーの相関を調べる必要がある（--correlate）
• 詳細なスタック分析が必要である（--trace）

デバッグプロセス

1. 取得 - エラーメッセージ、スタックトレース、再現手順を取得します
2. 切り分け - 失敗箇所を絞り込みます
3. 仮説 - 原因について仮説を立てます
4. 検証 - 証拠を用いて仮説を検証します
5. 修正 - 最小限の修正を実装します
6. 確認 - 解決策が機能することを確認します

調査手順

# Check recent changes that might have caused the issue
git log --oneline -10
git diff HEAD~3

# Find error patterns in logs
grep -r "error\|Error\|ERROR" logs/ 2>/dev/null | tail -20

# Check test output
npm test 2>&1 | tail -50  # or pytest, cargo test, etc.

ログ分析（--logs）

エラーを見つける

# Recent errors with context
grep -B 5 -A 10 "ERROR" /var/log/app.log

# Count by error type
grep -oE "Error: [^:]*" app.log | sort | uniq -c | sort -rn

# Errors in time range
awk '/2024-01-15 14:/ && /ERROR/' app.log

# Find repeated errors
grep "ERROR" app.log | cut -d']' -f2 | sort | uniq -c | sort -rn | head -20

# Find error spikes
grep "ERROR" app.log | cut -d' ' -f1-2 | uniq -c | sort -rn

よくあるパターン

パターン	示す内容	対処
NullPointer	null チェックの不足	バリデーションを追加します
Timeout	依存先の遅延	タイムアウトとリトライを追加します
Connection refused	サービス停止	ヘルス状態を確認し、リトライします
OOM	メモリリーク	プロファイリングを行い、上限を引き上げます
Rate limit	リクエスト過多	バックオフとキューを追加します

相関クエリ（--correlate）

-- Errors by endpoint
SELECT endpoint, count(*) as errors
FROM logs
WHERE level = 'ERROR' AND time > NOW() - INTERVAL '1 hour'
GROUP BY endpoint ORDER BY errors DESC;

-- Error rate over time
SELECT
  date_trunc('minute', time) as minute,
  count(*) filter (where level = 'ERROR') as errors,
  count(*) as total
FROM logs
WHERE time > NOW() - INTERVAL '1 hour'
GROUP BY minute ORDER BY minute;

-- Correlate request IDs across services
SELECT service, message, time
FROM logs
WHERE request_id = 'req-12345'
ORDER BY time;

スタックトレース分析（--trace）

スタックトレースを解析する

import re

def parse_stack_trace(log_content: str) -> list[dict]:
    pattern = r'(?P<exception>\w+Error|\w+Exception): (?P<message>.*?)\n(?P<trace>(?:\s+at .+\n)+)'
    traces = []
    for match in re.finditer(pattern, log_content):
        traces.append({
            'type': match.group('exception'),
            'message': match.group('message'),
            'trace': match.group('trace').strip().split('\n')
        })
    return traces

調査チェックリスト

1. 取得 - エラーメッセージとスタックトレース全体を取得します
2. タイムスタンプ - いつ始まりましたか？
3. 頻度 - どのくらいの頻度ですか？増加していますか？
4. 範囲 - すべてのユーザーですか、それとも特定のユーザーですか？
5. 変更 - 最近デプロイしましたか？
6. 依存関係 - 外部サービスに影響していますか？

出力形式

## Debug Report

**Issue:** [Brief description]
**Root Cause:** [What's actually wrong]

### Evidence

- [Finding 1]
- [Finding 2]

### Fix

[Code or configuration change]

### Verification

[How to confirm the fix works]

### Prevention

[How to prevent this in the future]

例

入力: 「TypeError: Cannot read property 'map' of undefined」 アクション: undefined の値を追跡し、データを初期化すべき場所を特定して、原因箇所を修正します

入力: 「テストが失敗しています」 アクション: テストを実行して失敗を取得し、それぞれの失敗を分析して、根本的な問題を修正します

入力: /debug --logs "API returning 500 errors" アクション: ログから 500 ステータスを検索し、スタックトレースを見つけ、根本原因を特定して、エラーの頻度を確認します

入力: /debug --correlate "intermittent failures" アクション: 相関クエリを実行してパターンを見つけ、影響を受けたエンドポイントを特定し、イベントとの相関を調べます