rspack-debugging — скилл для Claude Code: отладка крашей Rspack
Скилл rspack-debugging для Claude Code снимает через LLDB состояние краша нативного Rspack и собирает бэктрейсы при segfault, дедлоке или зависшей сборке.
MIT 282 установок ★ 100 обновлён 2026-10-22
npx skills add rstackjs/agent-skills --skill rspack-debugging -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/rspack-debugging/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/rspack-debugging/
1Через Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-debugging -a codex2Вручную: положить файлы
.agents/skills/rspack-debugging/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-debugging -a cursor2Вручную: положить файлы
.cursor/skills/rspack-debugging/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install rstackjs/agent-skills skills/rspack-debugging2Вручную: положить файлы
.github/skills/rspack-debugging/SKILL.md1Через Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-debugging -a gemini-cli2Командой платформы
gemini skills install https://github.com/rstackjs/agent-skills --path skills/rspack-debuggingВручную: положить файлы
.devin/skills/rspack-debugging/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add rstackjs/agent-skills --skill rspack-debugging -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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