К основному содержанию
скилл CX Codex

rspack-debugging — скилл для Claude Code: отладка крашей Rspack

Скилл rspack-debugging для Claude Code снимает через LLDB состояние краша нативного Rspack и собирает бэктрейсы при segfault, дедлоке или зависшей сборке.

MIT 282 установок ★ 100 обновлён 2026-10-22

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add rstackjs/agent-skills --skill rspack-debugging -a claude-code
Открыть на GitHub

Что делает rspack-debugging

Скилл ведёт агента через съём состояния краша нативного Rspack. Rspack написан на Rust, и падение или дедлок видны только на уровне стека — скилл добивается от LLDB подробного бэктрейса. Всё неинтерактивно: агент сам запускает отладчик и забирает вывод.

Внутри шесть гайдов под разные сценарии: краш при HMR, краш при сборке, подключение к зависшему процессу, разбор coredump для dev и для build, поиск асинхронного дедлока, когда главный поток висит в uv_run. Подготовку закрывает scripts/setup_debug_deps.cjs: он прописывает pnpm.overrides в package.json и переводит пакеты на серию @rspack-debug/*.

Без этой замены бэктрейс ничего не даст: в продакшн-пакетах вроде @rspack/core символы вырезаны. Ещё нужен установленный LLDB — xcode-select --install на macOS, пакет lldb на Linux. После отладки скрипт запускают с --restore и делают pnpm install, чтобы вернуть обычные пакеты. Бэктрейс агент сохраняет в debug_artifacts/backtrace_<timestamp>.txt в корне проекта.

Какие задачи решает

  • поймать бэктрейс при падении сборки Rspack
  • разобраться, почему HMR вешает DevServer
  • подцепиться отладчиком к застрявшему процессу сборки
  • прочитать coredump после нестабильного краша
  • найти асинхронный дедлок с главным потоком в uv_run

Примеры запросов агенту

  • Сборка на Rspack упала с segfault — сними бэктрейс через LLDB и положи его в debug_artifacts.
  • HMR стабильно вешает DevServer, пройди по гайду для краша при HMR.
  • Замени пакеты на debug-версии скриптом scripts/setup_debug_deps.cjs, а в конце верни как было.

Как установить rspack-debugging

1Через Skills CLI (Vercel)

npx skills add rstackjs/agent-skills --skill rspack-debugging -a claude-code

2Вручную: положить файлы

~/.claude/skills/rspack-debugging/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/rspack-debugging/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о rspack-debugging

Как установить rspack-debugging в Claude Code?

Выполни npx skills add rstackjs/agent-skills --skill rspack-debugging -a claude-code. Скилл появится в ~/.claude/skills/rspack-debugging/SKILL.md.

Что делает rspack-debugging?

Ведёт агента по съёму состояния краша нативного Rspack: запускает LLDB, получает стек и сохраняет его в файл в каталоге debug_artifacts.

Что нужно подготовить до отладки?

Установленный LLDB и замену пакетов: скрипт scripts/setup_debug_deps.cjs переводит их на серию @rspack-debug/*, после чего нужен pnpm install. В обычных пакетах символы вырезаны, и стек будет бесполезным.

Исходный текст

SKILL.md · MIT
---
name: rspack-debugging
description: Debug native Rspack crashes, segmentation faults, deadlocks, or stuck builds with LLDB and matching debug symbols.
---

# Rspack debugging

## Overview

This Skill guides you on how to capture the underlying crash state of Rspack (which is based on Rust). By using the LLDB debugger and Rspack packages with debug symbols, we can obtain detailed stack backtraces, which are crucial for pinpointing issues. The guides focus on non-interactive, automated debugging to easily capture backtraces.

## Preparation

Before starting, please ensure your environment meets the requirements.

1.  **Install LLDB**: You must install the LLDB debugger.
    - macOS: Run `xcode-select --install`
    - Linux: Install the `lldb` package (e.g., `apt-get install lldb`)
    - Detailed guide: [references/lldb.md](references/lldb.md)

2.  **Replace Debug Packages**:
    Production packages like `@rspack/core` have debug symbols stripped. They must be replaced with the `@rspack-debug/*` series packages to see useful stack information.

    **Automatic Replacement Script**:

    Resolve the bundled [`scripts/setup_debug_deps.cjs`](scripts/setup_debug_deps.cjs)
    relative to the Skill root while keeping the working directory in the user's
    project, then run:

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

    Running the above script will automatically add `pnpm.overrides` configuration to `package.json`, pointing Rspack packages to their corresponding Debug versions. Afterwards, please be sure to run `pnpm install` to update dependencies.

## Debugging workflows

Identify your specific scenario and follow the corresponding linked guide.

## Detailed guides

## Detailed guides

### Guide A: crash during HMR

**Scenario**: Stable Crash/Deadlock during DevServer HMR.
[Read Guide: references/guide_a_hmr_crash.md](references/guide_a_hmr_crash.md)

### Guide B: crash during build

**Scenario**: Stable Crash/Deadlock during Build (or Unstable Build Crash that is frequent enough).
[Read Guide: references/guide_b_build_crash.md](references/guide_b_build_crash.md)

### Guide C: attach to stuck process

**Scenario**: Unstable Deadlock during Build (happens randomly).
[Read Guide: references/guide_c_attach_to_stuck_process.md](references/guide_c_attach_to_stuck_process.md)

### Guide D: coredump analysis (Dev)

**Scenario**: Unstable Crash during DevServer HMR (hard to catch interactively).
[Read Guide: references/guide_d_coredump_analysis_dev.md](references/guide_d_coredump_analysis_dev.md)

### Guide E: coredump analysis (Build)

**Scenario**: Unstable Crash during Build.
[Read Guide: references/guide_e_coredump_analysis_build.md](references/guide_e_coredump_analysis_build.md)

### Guide F: async deadlock identification

**Scenario**: Unstable Async Deadlock. Main thread stuck in `uv_run`.
[Read Guide: references/guide_f_async_deadlock.md](references/guide_f_async_deadlock.md)

## Saving debug artifacts

**Critical Instruction for Agents**:
When you successfully obtain a backtrace or a tracing log, you **MUST** save it to a local file in the user's project directory so it is preserved after the session.

1.  **Create Directory**: Ensure a directory named `debug_artifacts` exists in the project root.
2.  **Save Backtraces**: Write the full output of `thread backtrace all` to `debug_artifacts/backtrace_<timestamp>.txt`.
3.  **Save Tracing Logs**: (Only if using Tracing Skill)

## Environment restoration

After debugging is complete, restore your `package.json` to use production packages:

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

Use the same resolved `<skill-root>` as in Preparation.

© rstackjs · MIT · rstackjs/agent-skills

Похожие скиллы

Все скиллы по теме «Фронтенд и UI» →
rust-debugging mohitmishra786 Скилл rust-debugging настраивает отладку Rust через GDB, LLDB, макрос dbg! и tokio-console. Помогает разбирать бэктрейсы паник и инспектировать асинхронные задачи. CX Codex +1 641установок zig-debugging mohitmishra786 Скилл zig-debugging для Claude Code: разбирает паники Zig, error return traces и сессии GDB/LLDB. Читает нечитаемые стеки. CX Codex +1 590установок discover-debugging rand Скилл discover-debugging подбирает материалы по отладке и профилированию, когда вы работаете с трассировками, утечками памяти или GDB. Помогает перейти от общей задачи к нужной инструкции. CX Codex +1 104установок rsdoctor web-infra-dev MCP-сервер rsdoctor отдаёт агенту данные сборки Rspack: размеры ассетов, зависимости модулей, время компиляции и диагностику дублей пакетов. CX Codex +1 ★ 1 152звёзд репо debugging tursodatabase Скилл debugging по отладке tursodb: сравнить байткод с SQLite, включить трейс-логи, прогнать ThreadSanitizer, воспроизвести баг по seed и замерить стек. CX Codex +1 1 300установок codex-debugging steipete Скилл codex-debugging помогает находить и устранять ошибки в кодовой базе codex-rs. Пригодится при разборе поведения интерфейса, протоколов и файлов конфигурации. CX Codex +1 108установок

Из того же набора21

Весь набор →
rspress-custom-theme Скилл rspress-custom-theme подсказывает агенту, как менять тему Rspress v2: от CSS-переменных до замены встроенных компонентов. CX Codex +1 435установок rspress-docs-generator Скилл rspress-docs-generator разворачивает сайт документации на Rspress v2 или обновляет существующие страницы под изменения в коде, тестах и API. CX Codex +1 344установок migrate-to-rsbuild Скилл migrate-to-rsbuild переводит фронтенд-проекты с webpack, Vite, Create React App и Vue CLI на сборщик Rsbuild. Он пошагово заменяет конфигурацию и проверяет запуск перед удалением старых пакетов. CX Codex +1 342установок rspack-tracing Скилл rspack-tracing для Claude Code и других IDE захватывает и анализирует traces сборок Rspack, чтобы найти медленные фазы компилятора, плагины и лоадеры. Помогает диагностировать крахи и узкие места прямо в процессе разработки. CX Codex +1 291установок storybook-rsbuild Скилл storybook-rsbuild настраивает Storybook на Rsbuild или переносит существующий проект с webpack и Vite. Он также учитывает интеграции с Rslib, Modern.js и Rspack. CX Codex +1 212установок migrate-to-rslib Скилл migrate-to-rslib переводит сборку библиотек с tsc или tsup на Rslib с проверкой билда и сохранением исходного кода. CX Codex +1 201установок rspack-split-chunks Скилл rspack-split-chunks помогает агенту диагностировать и настраивать optimization.splitChunks в Rspack: найти дубликаты модулей, избыточную загрузку, проблемы кеширования и слишком большие чанки. CX Codex +1 187установок rspress-v2-upgrade Скилл rspress-v2-upgrade автоматизирует переход Rspress-проекта с версии 1 на версию 2. Читает конфиг, обновляет зависимости, меняет импорты и валидирует результат по официальному гайду. CX Codex +1 150установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой