🐛 Debugging and Troubleshooting

Version: 2.0.0 Last Updated: 2025-11-22 Priority: ⭐⭐⭐⭐ (P1 Level) Purpose: 体系的なエラー診断とRustデバッグワークフロー

---

📋 概要

コンパイルエラー、テスト失敗、ランタイムエラーに対する 体系的な診断と解決ワークフローを提供します。

---

🎯 P0: 呼び出しトリガー

トリガー	例
動作不良	"this code isn't working"
テスト失敗	"why is this test failing?"
エラー解析	"debug this error"
コンパイルエラー	"compilation error"
ランタイムエラー	"runtime panic"

---

🔧 P1: エラー分類と対処

エラー分類表

分類	症状	診断コマンド	優先度
コンパイルエラー	error[E####]	cargo check	高
テスト失敗	test ... FAILED	cargo test -- --nocapture	高
ランタイムpanic	thread 'main' panicked	RUST_BACKTRACE=1	高
ロジックエラー	期待と異なる出力	dbg!(), ログ	中
パフォーマンス	遅い・メモリ大	cargo bench, valgrind	中
統合エラー	外部サービス失敗	ネットワーク診断	低

---

🚀 P2: デバッグパターン

Pattern 1: コンパイルエラー

# Step 1: エラー確認
cargo check 2>&1 | head -50

# Step 2: エラーコード解析
# error[E0277] → Trait未実装
# error[E0412] → 型未定義
# error[E0433] → モジュール未解決

# Step 3: 詳細情報
rustc --explain E0277

よくあるエラーと解決:

エラーコード	原因	解決策
E0277	Trait未実装	#[derive(...)] または手動実装
E0412	型が見つからない	use文追加
E0433	モジュール解決失敗	パス確認、mod宣言
E0502	借用競合	借用スコープ見直し
E0382	所有権移動後使用	clone() または参照

Pattern 2: テスト失敗

# Step 1: 失敗テスト特定
cargo test 2>&1 | grep FAILED

# Step 2: 詳細出力で実行
cargo test test_name -- --nocapture

# Step 3: 順次実行（並列問題回避）
cargo test -- --test-threads=1

# Step 4: アサーション詳細
# pretty_assertions, insta使用推奨

Pattern 3: ランタイムpanic

# Step 1: バックトレース取得
RUST_BACKTRACE=1 cargo run

# Step 2: 完全バックトレース
RUST_BACKTRACE=full cargo run

# Step 3: panic箇所特定
# at src/lib.rs:42:5 を確認

# Step 4: デバッガ使用
rust-lldb target/debug/miyabi

Pattern 4: ロジックエラー

// dbg!マクロ使用
let result = dbg!(compute_value());

// tracing使用
tracing::debug!(?value, "computed value");

// 条件付きログ
if cfg!(debug_assertions) {
    println!("Debug: {:?}", state);
}

---

⚡ P3: 高度なデバッグツール

デバッグツール一覧

ツール	用途	コマンド
rust-lldb	デバッガ	rust-lldb target/debug/miyabi
cargo-expand	マクロ展開	cargo expand
cargo-asm	アセンブリ確認	cargo asm
valgrind	メモリ診断	valgrind ./target/debug/miyabi
miri	UB検出	cargo +nightly miri test

VS Codeデバッグ設定

{
  "type": "lldb",
  "request": "launch",
  "name": "Debug Miyabi",
  "cargo": {
    "args": ["build", "--bin=miyabi"]
  },
  "args": [],
  "cwd": "${workspaceFolder}"
}

---

🛡️ 共通パニック対処

パニック	原因	対処
unwrap() on None	Option未処理	if let Some / ?
unwrap() on Err	Result未処理	match / ?
index out of bounds	配列範囲外	.get() / bounds check
overflow	算術オーバーフロー	checked_* / wrapping_*
stack overflow	無限再帰	再帰ロジック見直し

---

✅ 成功基準

チェック項目	基準
エラー分類	正確な分類
根本原因特定	原因明確化
解決策提示	具体的な修正方法
再発防止	テスト追加

---

🔗 関連Skills

• Rust Development: ビルド・テスト
• Performance Analysis: パフォーマンス問題
• Security Audit: セキュリティ問題