mcpField
R
rspack-debugging

rspack-debugging

github.com/rstackjs開発97270 回インストール6 日前に更新
リポジトリ

rspack-debugging について

rspack-debugging は、LLDB とデバッグシンボル付きパッケージを使って Rspack のクラッシュやデッドロックを調べるスキルです。状況別の手順でバックトレースを取得し、プロジェクト内にデバッグ情報を保存します。

主な機能

  1. 01LLDB によるクラッシュとデッドロックの調査
  2. 02デバッグ用パッケージの設定と復元
  3. 03HMR とビルド障害のガイド
  4. 04コアダンプと停止プロセスの分析手順
  5. 05バックトレースをプロジェクトに保存

活用シーン

  1. 01再現性のある HMR クラッシュの調査
  2. 02断続的なビルド障害の記録
  3. 03停止した Rspack プロセスの分析
  4. 04非同期デッドロックの特定

インストール

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

$npx skills add https://github.com/rstackjs/agent-skills --skill rspack-debugging

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
guide_a_hmr_crash.md
guide_b_build_crash.md
guide_c_attach_to_stuck_process.md
guide_d_coredump_analysis_dev.md
guide_e_coredump_analysis_build.md
guide_f_async_deadlock.md
lldb.md
scripts/
setup_debug_deps.cjs

詳細

Rspack のデバッグ

概要

このスキルでは、Rust をベースとする Rspack のクラッシュ時の状態を取得する方法を説明します。LLDB デバッガーとデバッグシンボル付きの Rspack パッケージを使用すると、問題の特定に不可欠な詳細なスタックバックトレースを取得できます。このガイドでは、バックトレースを簡単に取得できるよう、非対話型の自動デバッグに焦点を当てています。

準備

開始する前に、お使いの環境が要件を満たしていることを確認してください。

  1. LLDB をインストールする: LLDB デバッガーをインストールする必要があります。

    • macOS: xcode-select --install を実行します
    • Linux: lldb パッケージをインストールします（例：apt-get install lldb）
    • 詳細なガイド：references/lldb.md

  2. デバッグパッケージに置き換える: @rspack/core などの本番用パッケージでは、デバッグシンボルが削除されています。有用なスタック情報を確認するには、@rspack-debug/* 系のパッケージに置き換える必要があります。

    自動置換スクリプト：

    作業ディレクトリはユーザーのプロジェクト内に維持したまま、Skill のルートを基準に scripts/setup_debug_deps.cjs のパスを解決し、 次のコマンドを実行します。

    node "<skill-root>/scripts/setup_debug_deps.cjs"

    上記のスクリプトを実行すると、package.json に pnpm.overrides 設定が自動的に追加され、Rspack パッケージが対応する Debug 版を参照するようになります。その後、依存関係を更新するため、必ず pnpm install を実行してください。

デバッグのワークフロー

該当するシナリオを特定し、対応するリンク先のガイドに従ってください。

詳細ガイド

詳細ガイド

ガイド A：HMR 中のクラッシュ

シナリオ：DevServer の HMR 中に、安定してクラッシュまたはデッドロックが発生する。 ガイドを読む：references/guide_a_hmr_crash.md

ガイド B：ビルド中のクラッシュ

シナリオ：ビルド中に、安定してクラッシュまたはデッドロックが発生する（または、頻繁に発生する不安定なビルドクラッシュ）。 ガイドを読む：references/guide_b_build_crash.md

ガイド C：停止したプロセスにアタッチする

シナリオ：ビルド中に不安定なデッドロックがランダムに発生する。 ガイドを読む：references/guide_c_attach_to_stuck_process.md

ガイド D：コアダンプの分析（開発時）

シナリオ：DevServer の HMR 中に不安定なクラッシュが発生し、対話的に捕捉するのが困難である。 ガイドを読む：references/guide_d_coredump_analysis_dev.md

ガイド E：コアダンプの分析（ビルド時）

シナリオ：ビルド中に不安定なクラッシュが発生する。 ガイドを読む：references/guide_e_coredump_analysis_build.md

ガイド F：非同期デッドロックの特定

シナリオ：不安定な非同期デッドロックが発生する。メインスレッドが uv_run で停止している。 ガイドを読む：references/guide_f_async_deadlock.md

デバッグ成果物の保存

エージェントへの重要な指示： バックトレースまたはトレースログの取得に成功した場合、セッション終了後も保持できるよう、必ずユーザーのプロジェクトディレクトリ内のローカルファイルに保存してください。

  1. ディレクトリを作成する：プロジェクトのルートに debug_artifacts という名前のディレクトリがあることを確認します。
  2. バックトレースを保存する：thread backtrace all の出力全体を debug_artifacts/backtrace_<timestamp>.txt に書き込みます。
  3. トレースログを保存する：（Tracing Skill を使用している場合のみ）

環境の復元

デバッグが完了したら、package.json を本番用パッケージに戻します。

node "<skill-root>/scripts/setup_debug_deps.cjs" --restore
pnpm install

準備の際と同じ <skill-root> を使用してください。

コメント

Markdown 対応