debug

dot-skills デバッグのベストプラクティス

ソフトウェアエンジニア向けの包括的なデバッグ手法ガイドです。影響度の高い順に優先順位付けされた、10 カテゴリーにわたる 54 のルールを収録しています。Andreas Zeller 著『Why Programs Fail』の研究と、学術的なデバッグカリキュラムに基づいています。

適用する場面

以下の場合に、これらのガイドラインを参照してください。

• バグや予期しない動作を調査するとき
• 開発中にコードをデバッグするとき
• コードが誤った結果を出したり、クラッシュしたりするとき
• パフォーマンスの問題について根本原因を分析するとき
• 寄せられたバグ報告をトリアージし、修正の優先順位を決めるとき
• インシデントの根本原因分析を実施するとき
• デバッグの進め方や、よくあるバグパターンに関するコードをレビューするとき

優先順位別のルールカテゴリー

優先度	カテゴリー	影響度	プレフィックス
1	問題の定義	CRITICAL	prob-
2	仮説主導の調査	CRITICAL	hypo-
3	観察手法	HIGH	obs-
4	根本原因分析	HIGH	rca-
5	ツールの習熟	MEDIUM-HIGH	tool-
6	バグのトリアージと分類	MEDIUM	triage-
7	よくあるバグパターン	MEDIUM	pattern-
8	修正の検証	MEDIUM	verify-
9	アンチパターン	MEDIUM	anti-
10	防止と学習	LOW-MEDIUM	prev-

クイックリファレンス

1. 問題の定義（CRITICAL）

• prob-reproduce-before-debug - 調査する前にバグを再現する
• prob-minimal-reproduction - 最小限の再現ケースを作成する
• prob-document-symptoms - 症状を正確に記録する
• prob-separate-symptoms-causes - 症状と原因を切り分ける
• prob-state-expected-actual - 期待される動作と実際の動作を明示する
• prob-recent-changes - 最初に最近の変更を確認する

2. 仮説主導の調査（CRITICAL）

• hypo-scientific-method - 科学的手法を適用する
• hypo-binary-search - 二分探索を使ってバグの位置を特定する
• hypo-one-change-at-time - 一度に 1 つの仮説を検証する
• hypo-where-not-what - WHAT（何が起きたか）を問う前に、WHERE（どこで起きたか）を特定する
• hypo-rule-out-obvious - まず明白な原因を除外する
• hypo-rubber-duck - 問題を声に出して説明する

3. 観察手法（HIGH）

• obs-strategic-logging - ログを戦略的に活用する
• obs-log-inputs-outputs - 関数の入力と出力を記録する
• obs-breakpoint-strategy - ブレークポイントを戦略的に使う
• obs-stack-trace-reading - スタックトレースを下から上へ読む
• obs-watch-expressions - 状態の確認にウォッチ式を使う
• obs-trace-data-flow - システム内のデータフローを追跡する

4. 根本原因分析（HIGH）

• rca-five-whys - 「なぜ」を 5 回問う手法を使う
• rca-fault-propagation - 障害の伝播経路を追跡する
• rca-last-known-good - 最後に正常だった状態を特定する
• rca-question-assumptions - 自分の前提を問い直す
• rca-examine-boundaries - システムの境界を調べる

5. ツールの習熟（MEDIUM-HIGH）

• tool-conditional-breakpoints - 条件付きブレークポイントを使う
• tool-logpoints - コードを変更せずにログポイントを使う
• tool-step-commands - ステップオーバー／ステップイン／ステップアウトを使いこなす
• tool-call-stack-navigation - コールスタックをたどる
• tool-memory-inspection - メモリとオブジェクトの状態を調べる
• tool-exception-breakpoints - 例外ブレークポイントを使う

6. バグのトリアージと分類（MEDIUM）

• triage-severity-vs-priority - 深刻度と優先度を区別する
• triage-user-impact-assessment - 優先順位を決める前にユーザーへの影響を評価する
• triage-reproducibility-matters - トリアージで再現性を考慮する
• triage-quick-wins-first - すぐに対応できる改善を特定し、優先してリリースする
• triage-duplicate-detection - 重複するバグ報告を検出し、相互にリンクする

7. よくあるバグのパターン（中）

• pattern-null-pointer - ヌルポインタのパターンを認識する
• pattern-off-by-one - 1つずれるエラーを見つける
• pattern-race-condition - 競合状態の兆候を特定する
• pattern-memory-leak - メモリリークのパターンを検出する
• pattern-type-coercion - 型変換に関するバグに注意する
• pattern-async-await-errors - async/await のエラーハンドリングの誤りを見つける
• pattern-timezone-issues - タイムゾーンや日付に関するバグを認識する

8. 修正の検証（中）

• verify-reproduce-fix - 元の再現手順で検証する
• verify-regression-check - リグレッションがないか確認する
• verify-understand-why-fix-works - なぜ修正が機能するのかを理解する
• verify-add-test - 再発を防ぐテストを追加する

9. アンチパターン（中）

• anti-shotgun-debugging - 手当たり次第のデバッグを避ける
• anti-quick-patch - 理解しないまま応急的なパッチを当てるのを避ける
• anti-tunnel-vision - 最初の仮説に固執するのを避ける
• anti-debug-fatigue - デバッグによる疲労を認識する
• anti-blame-tool - ツールをすぐに責めない

10. 予防と学習（低〜中）

• prev-document-solution - バグの解決策を記録する
• prev-postmortem - 責任追及をしないポストモーテムを実施する
• prev-defensive-coding - 境界部分に防御的なコードを追加する
• prev-improve-error-messages - エラーメッセージを改善する

使用方法

詳しい説明とコード例については、個別のリファレンスファイルをお読みください。

• セクションの定義 - カテゴリーの構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート
• ルールの例：prob-reproduce-before-debug、hypo-binary-search

コンパイル済みの全ドキュメント

すべてのルールを展開した完全なガイド：AGENTS.md