mcpField
D
debug-mode

debug-mode

github.com/doraemonkeys開発11982 回インストール5 日前に更新
リポジトリ

debug-mode について

debug-mode は、コーディングエージェント向けの仮説駆動型デバッグスキルです。原因の検討から証拠収集、診断、修正の検証、後片付けまでを段階的に進めます。

主な機能

  1. 016段階のデバッグ手順
  2. 02検証可能な仮説の作成
  3. 03ファイルへのデバッグ記録
  4. 04リージョンで囲む計測コード
  5. 05証拠に基づく診断と検証

活用シーン

  1. 01原因が特定できない不具合の調査
  2. 02断続的な障害の証拠収集
  3. 03計測コードを消す前の修正検証

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/doraemonkeys/claude-code-debug-mode --skill debug-mode

インストール後、Claude Code で/debug-modeを入力して読み込まれたか確認します。

詳細

デバッグモード

デバッグモードです。仮説に基づくデバッグワークフローに従います。修正に飛びつかないでください。各フェーズを順番に進めてください。

フェーズ 1：バグを理解する

ユーザーから情報が提供されていない場合は、期待される動作と実際の動作、再現手順、エラーメッセージを尋ねてください。

関連するソースコードを読みます。呼び出しチェーンとデータフローを理解してください。

フェーズ 2：仮説を立てる

検証可能な仮説を番号付きリストで作成してください。

Based on my analysis, here are my hypotheses:

1. **[Title]** — [What might be wrong and why]
2. **[Title]** — [Explanation]
3. **[Title]** — [Explanation]

明白な原因だけでなく、競合状態、オフバイワン、古くなったクロージャ、型変換など、見落としやすい原因も含めてください。

手動での再現はユーザーを疲れさせます。特に、根本原因が見つからないまま 3 回以上繰り返す場合はなおさらです。再現サイクルを最小限に抑えるため、十分に詳細で適切なデバッグ情報をあらかじめ含めてください。

フェーズ 3：コードに計測処理を追加する

ログファイルと証拠の収集

デフォルトでは、絶対パスを使用して {project_root}/.agents/debug.log に書き込みます。

project_root = コンテキスト（会話内のファイルパス）から推定したハードコードされた定数文字列です。禁止事項：import.meta.dir、__dirname、process.cwd()、Deno.cwd()、path.resolve()、または実行時の検出。例外：リモート環境、CI 環境、またはローカルファイルシステムに書き込めない場合は、代わりに /tmp/.agents/debug.log を使用します。

各再現の前に、必要に応じて .agents/ を作成してください。.agents/debug.log が存在し、空でない場合は、debug.log を空にリセットする前に、debug-1.log、debug-2.log など、連番で最初に利用可能な名前に変更してアーカイブしてください。過去のログは保持してください。

サーバー側：ファイル追記 API（fs.appendFileSync、open("a") など）。ブラウザー側：デバッグ API ルートに fetch で POST します。すべての環境（開発版／リリース版）で動作させてください。

標準外の環境と断続的なバグへの対応（形式より証拠を重視）：

  • 制限のある環境／リモート環境／モバイル環境： コードがモバイル、組み込み、またはリモート環境で実行され、プロジェクトルートに書き込めない場合は、ログの保存先（デバイスストレージ、リモートエンドポイント、メモリバッファーなど）を適切に変更し、ログをユーザーに提供または貼り付けてもらってください。
  • 断続的なバグ： バグをすぐに発生させられない場合は、計測処理を残したままにし、問題が発生したらログを報告してもらってください。
リージョンマーカー

すべての計測処理は、後で確実に削除できるようにリージョンブロックで囲んでください。

// #region DEBUG       (JS/TS/Java/C#/Go/Rust/C/C++)
# #region DEBUG        (Python/Ruby/Shell/YAML)
 (HTML/Vue/Svelte)
-- #region DEBUG       (Lua)

...instrumentation...

// #endregion DEBUG    (matching closer)
ログのルール
  • console.log、print、または stdout／stderr への出力は絶対に使用しないでください。 すべてのデバッグ出力は debug.log に記録する必要があります。サーバー側ではファイル追記、ブラウザー側ではデバッグ API エンドポイントへの fetch を使用します。
  • ログメッセージには仮説番号を含めてください（[DEBUG H1]、[DEBUG H2] など）。
  • 変数の状態、実行経路、タイミング、判断ポイントを記録してください。
  • 必要最小限にしてください。各仮説を確認または否定するために必要な情報だけを記録します。

計測処理を追加したら、環境が許す場合は自分でバグを再現してください（失敗するコマンド、テスト、またはエンドポイントを実行します）。自分で再現できない場合に限り、ユーザーに再現方法を伝えたうえで、停止して返答を待ってください。

フェーズ 4：ログを分析して診断する

バグを（自分またはユーザーが）再現したら、次の手順に従います。

  1. まずログファイルのサイズを確認してください（例：wc -l または ls -lh）。ログが大きい場合は、ファイル全体を読むのではなく、tail または grep "[DEBUG H" を使用して関連する行だけを抽出してください。コンテキストウィンドウがログで埋まらないようにします。
  2. ログを仮説と照合し、確認されたものと否定されたものを特定します。
  3. 根拠を示して診断結果を提示します。
## Diagnosis

**Root cause**: [Explanation backed by log evidence]

Evidence:
- [H1] Ruled out — [why]
- [H2] Confirmed — [log evidence]

結論が出ない場合：新たな仮説を立てる → さらに計測処理を追加する → ログをアーカイブしてリセットする → もう一度自分で再現する。自分で再現できない場合に限り、ユーザーに依頼してください。

フェーズ 5：修正を作成する

修正を実装します。デバッグの計測処理は残してください。

.agents/debug.log をアーカイブしてリセットし、修正を検証するために、もう一度自分で再現してください。自分で再現できない場合は、ユーザーに検証を依頼したうえで、停止して返答を待ってください。

フェーズ 6：検証とクリーンアップ

修正できた場合： すべての #region DEBUG ブロックとその内容を削除します（Grep で検索してください）。すべての .agents/debug*.log ファイル（アーカイブ済みのログを含む）を削除し、概要をまとめます。

修正できていない場合： 新しいログを読みます。再現したのがユーザー本人の場合に限り、ユーザーに確認した内容を尋ねます。フェーズ 2 に戻り、繰り返します。

ルール

  • フェーズを絶対に省略しないでください。 答えがわかっていると思っていても、計測と検証を行ってください。
  • 修正を検証するまで、計測コードを絶対に削除しないでください（自分で検証するか、自分で再現できない場合はユーザーが検証します）。
  • console.log、print などは絶対に使用しないでください。 すべてのデバッグ出力を {project_root}/.agents/debug.log に記録してください（実行時の制約に応じて、出力先を調整してください）。
  • 再現するたびに、既存のログを必ずアーカイブし、debug.log をリセットしてください。
  • 計測コードは必ず #region DEBUG ブロックで囲んでください。

コメント

Markdown 対応