DEBUG SKILL - Blueprint v11

実行: /debug または3回連続失敗後に自動トリガー

トーン

デバッグはユーザーにとってストレスです。気さくなSMEは速度を落とし、 問題を体系的に進め、ユーザーを責めず、知らないことを知っているふりをしません。 修正が機能したら、祝うことなく先に進みます。仮説が失敗したら、そう述べて 次の仮説を試します。

サーキットブレーカー

同じ問題で3回連続失敗したということは、立ち止まってこのプロトコルを実行するということです。 以下のステップを実行せずに4番目の変更を試みないでください。診断されていない問題に 修正を浴びせることは時間を無駄にし、本当の原因を隠します。

ステップ1 - 最初にERRORS.mdを確認する

何をする前にも、ERRORS.mdを読んでください。正確なエラーメッセージまたは 見ているパターンを検索してください。マッチするものがあれば、文書化された修正を適用してください。 誰かが既に解決した問題を再診断しないでください。

ステップ2 - 根本原因を診断する

完全なエラー出力を読んでください。最初の行だけではなく、全て読んでください。 多くのエラーは、本当の原因がスタックフレームを2つか3つ下っています。

エラーを以下のいずれかに分類してください:

• コードエラー（ソースのバグ）
• 設定エラー（環境変数、ファイル欠落、パス誤り）
• 環境エラー（バージョン違い、システム依存関係の欠落）
• 統合エラー（以前は機能していた2つの部分が同期しなくなった）

確認する価値がある一般的なパターン:

• 非同期/同期のミックス、await の欠落、不正なインポートパス
• 環境変数名または形式の誤り（例：CORS_ORIGINS はJSONアレイを期待し、 カンマ区切り文字列ではない）
• requirements.txtまたはpackage.jsonに欠落している依存関係
• マイグレーションとモデルの不同期
• ある1つのファイルの最近の変更が別のファイルの仮定を破った

ステップ3 - 修正前に診断を検証する

誤った診断に適用された修正はノイズです。安く検証してください:

cat error.log | tail -50
python --version && node --version
printenv | grep <relevant_prefix>
alembic current && alembic history   # alembicを使用している場合

仮説ではなく、根本原因の証拠を得たら初めて修正を適用してください。

ステップ4 - 修正と検証

正確に1つの修正を適用してください。失敗しているテストまたはコマンドを すぐに実行して検証してください。複数の修正を一度に適用しないでください - 何かが機能したら、その変更が原因であることを知る必要があります。

修正が機能した場合: ステップ5に進みます。 修正が失敗した場合: 試したことを文書化し、明確にそう述べ、次の仮説に進みます。

ステップ5 - ERRORS.mdに文書化する

## ERR-[NNN]: [短いタイトル]
Date: [日付]
Gate: [vX.X.X]
Symptom: [ユーザーが見たもの]
Root cause: [実際の原因]
Fix applied: [正確な修正]
Attempts that failed: [機能しなかったこと、およびその理由]
Prevention: [将来を避ける方法]

「Attempts that failed」フィールドは重要です。将来のセッションは、 正しいパスだけでなく、誤ったパスを文書化してくれることに感謝するでしょう。

既知のスタックエラー

これらをプロジェクト開始時にERRORS.mdにシードして、最初のヒットが 既にカバーされるようにしてください:

• ERR-001: ModuleNotFoundError: No module named 'jose' 修正: requirements.txtに python-jose[cryptography] を追加してください。

• ERR-002: DATABASE_URL asyncpgプレフィックスが間違っている 修正: postgres:// を postgresql+asyncpg:// に変更してください。

• ERR-003: Co-Authored-By がHobbyプランでのホスティングデプロイをブロックする 修正: strip-coauthorフックはcommit-msgフックをインストールして、 自動的にラインを削除します。インストールされていない場合は、 bash ~/.claude/hooks/strip-coauthor.sh を一度実行してください。

• ERR-004: Alembic autogenerateが間違ったマイグレーションを生成する 修正: 出力を読まずにautogenerateを使用しないでください。マイグレーションを 手動で作成し、レビューしてください。

ルール

• このプロトコルを実行せずに4番目の修正変更を試みないでください
• エラー出力を斜め読みしないでください。すべて読んでください
• 一度に2つの修正を適用しないでください
• ERRORS.mdへのログを省略しないでください。そうしないと次のセッションが その苦しみを引き継ぎます
• バグをユーザーのせいにしないでください。状況のせいにしてください