debugging-strategies

デバッグ戦略

デバッグを、再現、切り分け、仮説の立案、検証を行い、その後に修正するという、管理された調査に変えます。手当たり次第に変更を加えないでください。

言語やツールに固有のコマンド、高度なパターンについては、必要な場合にのみ references/debugging-toolbox.md を参照してください。

基本的な手順

1. 再現する

以下を明らかにします。

• 正確な手順
• 期待される動作と実際の動作
• 発生頻度：常に／断続的／特定の環境のみ
• 再現可能な最小ケース
• 環境：コミット、OS、ランタイム、依存関係のバージョン、設定

再現できない場合は、コードを変更する前に、さらに可観測性を高めるための情報を収集します。

2. 切り分ける

問題が発生している範囲を絞り込みます。

• 関係のない入力を取り除く
• 並行処理、キャッシュ、外部サービスを減らす
• 最後に正常だった状態と現在の状態を比較する
• コード、設定、データ、依存関係の変更を二分探索する

3. 仮説を立てる

考えられる原因を2～5個挙げます。それぞれについて、以下を確認します。

• 症状を説明できる理由
• 仮説を裏付ける証拠
• 仮説を否定する証拠
• 最も低コストな検証方法

理論のおもしろさではなく、発生確率と検証コストに基づいて優先順位を付けます。

4. 1つずつ検証する

一度に変更または計測する変数は1つだけにします。ログとコマンドは保持します。原因が確認されていない修正は、成果ではなくリスクです。

5. 検証し、再発を防止する

修正後は、以下を行います。

• 最小の再現手順を再実行する
• 関連するテストを再実行する
• 可能であれば回帰テストを追加する
• 根本原因と、修正によって問題が解決する理由を記録する

問題の振り分け

• Python のパフォーマンスボトルネック → python-performance-optimization。
• テスト設計または失敗する pytest スイート → python-testing-patterns。
• 繰り返しバグを引き起こす構造的なコードの問題 → python-design-patterns。
• Claude を使用するコードのプロンプトやモデルの動作 → prompting-claude-models。

出力

以下を返します。

• 症状の概要
• 再現状況
• 問題が発生している範囲
• 優先順位を付けた仮説
• 次に行う具体的な診断
• 修正の検証計画
• 再発防止策