dynamic-debugger

動的デバッガースキル

DAP-MCP 統合による Claude Code 向けの対話型デバッグ機能です。会話を離れずに、自然言語でコードをデバッグできます。

概要

このスキルは、MCP サーバー統合を介して Debug Adapter Protocol（DAP）による対話型デバッグを実現します。自然言語のコマンドを使って、複数のプログラミング言語でブレークポイントの設定、コードのステップ実行、変数の確認、実行フローの制御ができます。

利用できる機能：

• 自然言語によるデバッグコマンド（「42 行目にブレークポイントを設定」）
• 現在のサポート対象： Python（debugpy）、C/C++/Rust（lldb）
• 今後のサポート予定： JavaScript/TypeScript、Go、Java、.NET（configs/future/ を参照）
• 意図と言語の自動検出
• リソース制限付きのセッション管理
• 適切なエラー処理と復旧

有効化（オプトイン）

このスキルはデフォルトで無効です（disableModelInvocation: true）。

有効にするには：

1. 明示的に呼び出す（推奨）：

   "Use the dynamic-debugger skill to debug this function"
   

2. 自動有効化（SKILL.md のフロントマターを編集）：

   disableModelInvocation: false # or remove this line
   

オプトインが必要な理由：

• 外部の dap-mcp サーバーをインストールする必要があります
• デバッガープロセスを起動します（リソースを大量に消費します）
• ファイルシステムへの完全なアクセスが必要です
• デバッグを行うときだけ有効にするのが最適です

前提条件

必須：

• dap-mcp サーバーがインストールされていること（pip install dap-mcp または uv pip install dap-mcp）
• 言語固有のデバッガー（現在のサポート対象）：
  • Python：debugpy（pip install debugpy）
  • C/C++/Rust：lldb-dap（DAP 対応の lldb をインストール）

確認方法：

# Check dap-mcp installation
python3 -m dap_mcp --help

# Check language debuggers
python -c "import debugpy; print('debugpy ready')"
which gdb
dlv version

クイックスタート

シナリオ 1：Python の非同期処理のバグ

ユーザー：「この非同期関数は await が正しく機能していません。デバッグしてください。」

スキルが自動的に有効になります：

1. デバッグの意図を検出します（高い確度）
2. ファイル拡張子から Python を特定します
3. debugpy セッションを開始します
4. 非同期関数にブレークポイントを設定します
5. await の状態と変数の値を表示します

シナリオ 2：C++ のセグメンテーション違反

ユーザー：「malloc でセグメンテーション違反が発生しています。ブレークポイントを設定してください。」

スキルの応答：

1. 明示的なトリガー（「ブレークポイントを設定」）を検出します
2. ファイル拡張子から C++ を特定します
3. gdb セッションを開始します
4. スタックトレースを使ってセグメンテーション違反を捕捉します
5. クラッシュ発生時点のポインター値を確認します

シナリオ 3：JavaScript の Promise チェーン

ユーザー：「この Promise チェーンが解決されないのはなぜですか？」

スキルの応答：

1. 暗黙的なトリガー（「なぜ」）を検出します
2. 確認を求めます（中程度の確度）
3. package.json から JavaScript を特定します
4. .then() ハンドラーにブレークポイントを設定します
5. 非同期フローをステップ実行します

よくあるワークフロー

デバッグセッションの開始

明示的なトリガー（自動開始）：

• 「これをデバッグして」
• 「X 行目にブレークポイントを設定して」
• 「この関数をステップ実行して」
• 「変数 X を確認して」

暗黙的なトリガー（確認を求める場合があります）：

• 「X が間違っているのはなぜ？」
• 「これが動作しない」
• 「X の実行を追跡して」
• 「X でテストが失敗する」

デバッグコマンド

ブレークポイントの管理：

• 「42 行目にブレークポイントを設定」
• 「42 行目のブレークポイントを削除」
• 「すべてのブレークポイントを一覧表示」

実行の制御：

• 「ステップオーバー」（現在の行を実行）
• 「ステップイン」（関数呼び出しに入る）
• 「ステップアウト」（現在の関数を抜ける）
• 「続行」（次のブレークポイントまで実行）

変数の確認：

• 「userId の値は？」
• 「すべてのローカル変数を表示」
• 「式を評価：x + y」

セッションの管理：

• 「コールスタックを表示」
• 「スレッド／goroutine を一覧表示」
• 「デバッグを停止」

ナビゲーションガイド（必須）

状況に応じて、これらのファイルを必要なときに読み込んでください：

reference.md を読み込むタイミング

トリガー： ユーザーが特定の API 詳細、設定構文、またはエラーコードを必要としている 内容： API リファレンス全体、言語設定、セッション管理 API、エラー処理の詳細、リソース制限 サイズ： 3,000～4,000 トークン 質問例：「Go デバッガーを設定するには？」「リソース制限は？」「すべてのエラーコードを表示して」

examples.md を読み込むタイミング

トリガー： ユーザーが動作するコード例や具体的なデバッグシナリオを求めている 内容： 6 言語すべてを対象とした、ワークフロー全体を含む本番環境向けのデバッグ例 サイズ： 2,000～3,000 トークン クエリの例： 「Python の非同期デバッグの例を見せてください」「Rust の panic をデバッグするにはどうすればよいですか」「goroutine のデッドロックをデバッグする例」

patterns.md を読み込むタイミング

トリガー： ユーザーがベストプラクティス、アーキテクチャパターン、またはデバッグ戦略について尋ねている 内容： 本番環境向けのデバッグパターン、パフォーマンス技法、セキュリティのベストプラクティス、よくある落とし穴 サイズ： 1,500～2,000 トークン クエリの例： 「デバッグのベストプラクティスは何ですか」「パフォーマンスの問題をデバッグするにはどうすればよいですか」「よくあるセキュリティ上のミスは何ですか」

デフォルトの動作： 基本的なデバッグコマンドには SKILL.md のみを使用します。明示的に必要な場合にのみ、補助ファイルを読み込みます。

セッション管理

同時に実行できるセッション： ユーザーごとに一度に 1 つのデバッグセッションのみ タイムアウト：

• セッションのアイドル時間：30 分
• 接続のアイドル時間：5 分
• 起動：最大 10 秒

リソース制限：

• メモリ：デバッグ対象プロセスは最大 4GB
• CPU 制限なし（デバッグはリソースを大量に消費します）
• セッション終了時に自動クリーンアップ

言語の検出

自動検出の方法：

1. ファイル拡張子（主なシグナル）
2. マニフェストファイル（package.json、Cargo.toml、go.mod）
3. プロジェクト構造の分析

信頼度のしきい値：

• 高（>90%）：言語を自動選択
• 中（70～90%）：ユーザーに確認
• 低（<70%）：ユーザーに指定を求める

手動での上書き： 「これを Python コードとしてデバッグしてください」（自動検出を回避）

トラブルシューティング

dap-mcp サーバーが見つからない

症状： 「dap-mcp サーバーを利用できません」 解決方法：

npm install -g dap-mcp
npx dap-mcp --version

言語デバッガーが見つからない

症状： 「debugpy が見つかりません」または「gdb を利用できません」 解決方法： 言語固有のデバッガーをインストールします（前提条件を参照）

セッションのタイムアウト

症状： 「セッションが 30 分後にタイムアウトしました」 解決方法： 「これをデバッグしてください」と入力して新しいセッションを開始します

同時セッションがブロックされた

症状： 「別のデバッグセッションがアクティブです」 解決方法： 「デバッグを停止」と入力して既存のセッションを停止するか、タイムアウトまで待ちます

メモリ制限を超過した

症状： 「デバッグ対象プロセスが 4GB のメモリ制限を超過しました」 解決方法： データ構造を縮小するか、大規模なデータセットにはサンプリングを使用します

エラーからの復旧

すべてのエラーには次の情報が含まれます。

1. 失敗した内容の明確な説明
2. 実行可能な復旧手順
3. 必要に応じた手動での代替コマンド

段階的な機能縮退： dap-mcp を利用できない場合、スキルは手動のデバッガーコマンドを提案します。

トークン予算

• オーケストレーションのオーバーヘッド：コマンドあたり <100 トークン
• 意図の検出：<20 トークン
• 言語の検出：<30 トークン（初回検出後はキャッシュ）
• エラーメッセージ：<50 トークン

設計方針： スキルのオーケストレーションは最小限に抑えます。トークンの大半はオーバーヘッドではなく、実際のデバッグのやり取りに使用します。

セキュリティ

⚠️ 重要なセキュリティ上の考慮事項：

• ファイルシステムへの完全なアクセス： このスキルはシステム上のあらゆるファイルを読み書きできます（デバッグに必要です）
• プロセスの実行： システムの完全な権限でデバッガープロセスを起動します
• サンドボックスなし： デバッグ対象のコードはユーザーの権限で実行されます
• デフォルトではローカルのみ： サーバーは localhost のみで待ち受けます（ネットワークに公開しないでください）
• 機密データ： デバッガーは、実行中のプロセスのメモリ、環境変数、認証情報にアクセスできます

ベストプラクティス：

• 信頼できるコードのみをデバッグしてください
• 使用前にデバッガーの設定を確認してください
• 環境内の本番環境用認証情報の取り扱いには注意してください
• 機密性の高いプロジェクトには専用の開発環境を使用してください
• 信頼できないバイナリは決してデバッグしないでください

プロセスの分離：

• デバッガーは Claude Code とは別のプロセスで実行されます
• 終了時にクリーンアップスクリプトがすべてのデバッガープロセスを終了します

パフォーマンス目標

• サーバーの起動：<10 秒
• ブレークポイント操作：<2 秒
• ステップ操作：<3 秒
• 変数の調査：<2 秒

次のステップ

1. 前提条件を確認する（「前提条件」セクションを参照）
2. 自然言語（「これをデバッグして」）でデバッグを開始する
3. 必要な場合にのみ補助ファイルを読み込む（「ナビゲーションガイド」を参照）
4. 特定のシナリオについては例を確認する（examples.mdを参照）
5. 本番環境でのデバッグに役立つパターンを学ぶ（patterns.mdを参照）

---

設計思想： 徹底してシンプルなオーケストレーションです。複雑な処理はすべてこのスキルではなく、dap-mcp サーバーが担います。私たちはデバッガーの乗組員に指示を出す、気さくな海賊船長にすぎません。