debug

デバッグ - 根本原因のデバッグワークフロー

根本原因分析を徹底する、完全なデバッグワークフローです。調査 → 理解 → 推論 → 修正の順に進めます。

概要

デバッグでは、複数のデバッグ手法を組み合わせます。

• コードベースの調査 - 関連するコードを検索します
• GitHub のイシュー検索 - 既知の問題や回避策を探します
• 複数のフレームワークを用いた推論 - 体系的な思考を適用します
• 修正案の作成 - コードを含む具体的な推奨事項を提示します

前提条件

# Gemini CLI for AI analysis
pip install google-generativeai
export GEMINI_API_KEY=your_api_key

# gh CLI for GitHub issue search
brew install gh
gh auth login

デバッグワークフロー

フルデバッグ（複雑な問題に推奨）

# Phase 1: Investigate codebase
rg -l "error pattern" --type ts
rg "relevant_function" -A 10 -B 5

# Phase 2: Search GitHub for known issues
gh search issues "error message" --repo owner/repo --limit 10
gh issue view 123 --repo owner/repo

# Phase 3: Reason about root cause
gemini -m pro -o text -e "" "Given this error and code context, what is the root cause?

Error: [error message]

Code:
\$(cat src/file.ts)

Investigation findings:
- [finding 1]
- [finding 2]

Apply first principles, systematic, and critical thinking frameworks."

# Phase 4: Generate fix
gemini -m pro -o text -e "" "Based on root cause: [cause]

Provide:
1. Specific code fix
2. Before/after code
3. How to verify
4. How to prevent"

クイックデバッグ（単純な問題向け）

# Skip deep reasoning, focus on investigation + fix
rg "error pattern" --type ts -A 5 -B 5

gemini -m pro -o text -e "" "Debug this quickly:

Problem: [description]
Error: [message]

Code:
\$(cat src/problematic-file.ts)

Give me the root cause and fix in 3 sentences."

コンテキストを指定したデバッグ（対象ファイルが既知の場合）

# When you already know which files are involved
gemini -m pro -o text -e "" "Debug using these files:

Problem: [description]

File 1:
\$(cat src/file1.ts)

File 2:
\$(cat src/file2.ts)

Provide:
1. Root cause
2. Specific fix with line numbers
3. Verification steps"

包括的な診断（複雑な問題向け）

# Parallel investigation of multiple sources

# Terminal 1: Codebase search
rg "error" --type ts --stats > /tmp/codebase.txt &

# Terminal 2: GitHub issues
gh search issues "error" --limit 20 > /tmp/github.txt &

# Terminal 3: Git history
git log --oneline --all -S "problematic_function" > /tmp/history.txt &

wait

# Synthesize findings
gemini -m pro -o text -e "" "Synthesize these diagnostic findings:

Codebase:
\$(cat /tmp/codebase.txt)

GitHub Issues:
\$(cat /tmp/github.txt)

Git History:
\$(cat /tmp/history.txt)

Provide unified diagnosis with:
1. Most likely root cause
2. Confidence level
3. Key evidence
4. Differential diagnosis
5. Recommended action"

根本原因の特定手順

必ず次の順序で進めてください。

1. 調査 - まず証拠を探します
2. 理解 - 関連するコードを読みます
3. 推論 - 体系的な思考を適用します
4. 修正 - その後にのみ変更を提案します

禁止されている近道

症状	禁止されている修正	必須の修正
Null エラー	if (x) { x.y }	x が null になる理由を特定する
タイムアウト	タイムアウトを延長する	遅い処理を特定する
不安定なテスト	テストをスキップする	競合状態を特定する
型エラー	as any	型の階層を修正する

調査コマンド

コードベースの検索

# Find error patterns
rg "throw.*Error" --type ts -A 3

# Find function definitions
rg "function functionName|const functionName" --type ts

# Find usages
rg "functionName\(" --type ts

# Find recent changes
git log --oneline -20 --all -- src/problematic/
git diff HEAD~5 -- src/problematic/

GitHub イシューの検索

# Search issues
gh search issues "error message" --repo owner/repo --state all

# View issue details
gh issue view 123 --repo owner/repo --comments

# Search across multiple repos
for repo in repo1 repo2 repo3; do
  gh search issues "error" --repo owner/$repo --limit 5
done

ログの分析

# Find logs first
find . -name "*.log" -type f

# Tail recent logs
tail -100 logs/app.log | grep -i error

# Search logs for patterns
grep -n "ERROR\|WARN" logs/*.log | tail -50

フレームワークに基づく推論

第一原理思考

gemini -m pro -o text -e "" "Apply first principles to this bug:

Problem: [description]

Questions:
1. What is this code supposed to do?
2. What is it actually doing?
3. What assumptions are being made?
4. Which assumption is wrong?"

体系的な分析

gemini -m pro -o text -e "" "Systematically analyze:

Problem: [description]

Walk through:
1. Input → What data enters?
2. Processing → What transformations?
3. State → What state changes?
4. Output → What comes out?
5. Where does expected diverge from actual?"

批判的思考

gemini -m pro -o text -e "" "Challenge assumptions:

Problem: [description]

For each potential cause:
- What evidence supports it?
- What evidence contradicts it?
- What would we expect to see if true?
- Can we rule it out?"

出力形式

デバッグセッションでは、次の内容を作成します。

## ROOT CAUSE
Single sentence identifying the actual cause.

## CONFIDENCE
high | medium | low

## FIX
Specific code changes:
- File: src/file.ts
- Line: 42
- Before: `oldCode()`
- After: `newCode()`

## VERIFICATION
How to verify the fix works:
1. Run test: `npm test -- specific.test.ts`
2. Manual check: [steps]

## PREVENTION
How to prevent this in the future:
- Add validation at boundary
- Add regression test

ベストプラクティス

1. まずログを確認する - コードを読む前にログを読みます
2. 証拠を必須とする - 具体的な証拠を示さずに修正しません
3. 原因を一つに絞る - 症状ではなく、根本原因を特定します
4. 仮説を検証する - 修正前に仮説をテストします
5. 再発を防ぐ - 障害が発生した状況を再現するテストを追加します
6. 調査結果を記録する - 得られた知見を記録します