debug-tools

デバッグツール

証拠に基づいて修正を行い、失敗が繰り返された場合はエスカレーションする、反復的なデバッグワークフローです。

トリガー

• バグのデバッグ（「これをデバッグして」「調査して」「問題を追跡して」「バグを修正して」「なぜ X が壊れているのか」）→ ステップ 1
• リグレッションまたは比較（「以前は動いていた」「アップデート後に壊れた」「あちらでは動くのにこちらでは動かない」）→ ステップ 2
• デバッグログの追加（「デバッグログを追加して」「ログを埋め込んで」「ログで追跡して」）→ ステップ 3
• ログのクリーンアップ（「デバッグログを削除して」「ログをクリーンアップして」）→ ステップ 5

ワークフロー

このチェックリストをコピーし、項目にチェックを入れてください。

Progress:
- [ ] Step 1: Investigate
- [ ] Step 2: Compare against working code (when needed)
- [ ] Step 3: Gather runtime evidence (when needed)
- [ ] Step 4: Fix and verify
- [ ] Step 5: Clean up logs

セッションの状態に応じたステップから開始してください。すでに証拠があるセッションは、ステップ 1 からやり直しません。

ステップ 1. 調査する。 investigation.md を読み込み、「Understand the Bug」から「Rank Hypotheses」までの各セクションに沿って進めてください。すべての仮説にスコアと証拠の種類が付与され、最有力の仮説に証拠があるか、必要な実行時データが明示されていれば完了です。

ステップ 2. 動作するコードと比較する。 分析が行き詰まり、壊れたコードを動作する例と差分比較する必要がある場合、または以前は動作していたとユーザーが報告した場合は、debugging-patterns.md を読み込んでください。比較またはリグレッションの追跡が完了したら、ステップ 1 に戻って仮説の順位を付け直してください。

ステップ 3. 実行時の証拠を集める。 コードを読んでも仕組みが分からず、実行中のシステムを観察するしかない場合は、log-injection.md を読み込んでください。再現時の出力を確認したら、ステップ 1 に戻って仮説の順位を付け直してください。

ステップ 4. 修正して検証する。 investigation.md の「Propose Fix」「Verify」「Report」の各セクションに沿って進めてください。再現時に症状が現れなくなり、報告が作成されていれば完了です。症状が残っている場合は、実行結果から得られた内容をもとにステップ 1 に戻ってください。

ステップ 5. ログをクリーンアップする。 修正の検証後、または明示的に依頼された場合は、log-cleanup.md を読み込んでください。変更をバージョン管理に反映する前に実行してください。スクリプトの find で [DEBUG] ステートメントが見つからず、プロジェクトの構文チェックに合格すれば完了です。

機密情報が埋め込まれたログに出力されることがあってはなりません。パスワード、トークン、API キー、個人を特定できる情報、セッション識別子が該当します。このルールは、ステップ 3 を読み込まずに調査の途中で追加する場合も含め、ログを追加するあらゆる場面に適用されます。

アンチパターン：症状のいたちごっこ

同じ症状を複数の場所で修正している場合、局所的なバグではなく、アーキテクチャ上の問題がある兆候です。症状が残っているステップ 4 の報告の最後には Attempt N of 3 と記載し、別の修正を提案する前にその回数を読み上げてください。3 回に達したら、修正を中止してください。4 回目に行うのは、ユーザー向けのアーキテクチャ評価です。試したことと失敗した理由、問題がシステム全体に及ぶものか（不適切な抽象化、レイヤーの不足、誤った前提）、解決に必要なアーキテクチャ変更を説明してください。根本原因が変わり続ける、試行ごとに変更範囲が広がる、または試行のたびに信頼度スコアが下がる場合は、それより早く中止して再評価してください。