systematic-debugging · vstorm-co — скилл для Claude Code: отладка по шагам
Скилл systematic-debugging для Claude Code ведёт агента по пяти шагам: от воспроизведения ошибки до проверки исправления. Помогает разбирать ошибки без правок наугад.
MIT ★ 1 125 обновлён 2026-10-27
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a claude-codeЧто делает systematic-debugging
Скилл задаёт жёсткий цикл: воспроизвести ошибку, изолировать минимальный вход, поставить диагноз, починить, проверить. Перескакивать нельзя, и угадывать наугад тоже — так написано в самом файле.
Внутри рабочая мелочёвка, которая обычно и решает, сколько живёт баг. Какую строку читать в стектрейсе (для сегфолта смотрят на последнюю функцию, для Python на самый внутренний кадр). Какие отладочные вставки добавлять в C и в Python и что потом их надо убрать. Короткий список частых причин: выход за границы массива на единицу, несовпадение знаковых и беззнаковых типов, UTF-8 приняли за байты, относительный путь сломался при смене рабочей папки.
Три неудачных попытки с одним подходом означают, что неверен подход, а не детали. Скилл велит бросить его и зайти с другой стороны. Сам он ничего не запускает: SKILL.md — это текст, который держит агента в рамках, когда тот начинает метаться.
Какие задачи решает
- Найти минимальный вход, на котором воспроизводится падение
- Прочитать стектрейс и понять, с какого кадра начинать
- Отличить первую ошибку компиляции от каскада следующих
- Разобраться, почему код считает верно на малых данных и висит на больших
- Объяснить падение теста, которого нет при локальном прогоне
Примеры запросов агенту
- Разберись, почему падает
pytest tests/test_parse.py, и иди по шагам из systematic-debugging. - Не угадывай: сначала воспроизведи ошибку и покажи полный вывод с кодом возврата.
- Третья попытка не помогла — смени подход, как велит systematic-debugging.
Как установить systematic-debugging
1Через Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a claude-code2Вручную: положить файлы
~/.claude/skills/systematic-debugging/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/systematic-debugging/
1Через Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a codex2Вручную: положить файлы
.agents/skills/systematic-debugging/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a cursor2Вручную: положить файлы
.cursor/skills/systematic-debugging/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install vstorm-co/pydantic-deepagents apps/cli/skills/systematic-debugging2Вручную: положить файлы
.github/skills/systematic-debugging/SKILL.md1Через Skills CLI (Vercel)
npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a gemini-cli2Командой платформы
gemini skills install https://github.com/vstorm-co/pydantic-deepagents --path apps/cli/skills/systematic-debuggingВручную: положить файлы
.devin/skills/systematic-debugging/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о systematic-debugging
Как установить systematic-debugging в Claude Code?
Выполните npx skills add vstorm-co/pydantic-deepagents --skill systematic-debugging -a claude-code. Файл скилла появится по пути ~/.claude/skills/systematic-debugging/SKILL.md.
Что делает systematic-debugging?
Ведёт агента по циклу из пяти шагов: воспроизведение, изоляция, диагностика, исправление, проверка. На каждом шаге сказано, что смотреть и какие отладочные вставки добавлять.
Что делать, если исправление не сработало несколько раз?
После трёх неудачных попыток с одним подходом скилл требует бросить его и выбрать другую стратегию вместо перебора вариантов.
Исходный текст
SKILL.md · MIT
---
name: systematic-debugging
description: "Systematic approach to diagnosing and fixing errors"
tags: [debugging, errors, benchmark]
version: "1.0.0"
---
# Systematic Debugging
A structured approach to finding and fixing bugs.
## The Debugging Loop
```
1. REPRODUCE → 2. ISOLATE → 3. DIAGNOSE → 4. FIX → 5. VERIFY
```
Never skip steps. Never guess-and-check repeatedly.
## Step 1: Reproduce
- Run the exact command that fails
- Capture FULL output (stdout AND stderr)
- Note: exit code, error message, stack trace
- If intermittent, identify what changes between runs
## Step 2: Isolate
- What's the MINIMAL input that triggers the error?
- Which specific line/function fails? (read the traceback bottom-up)
- Is it a compile error, runtime error, or wrong output?
- Does it fail on all inputs or specific ones?
## Step 3: Diagnose
### Read the error message carefully
| Error type | Where to look |
|-----------|---------------|
| Compile error | The FIRST error (later ones are often cascading) |
| Segfault | Last function in the stack trace, check array bounds and null pointers |
| Python traceback | The innermost frame (bottom), but also check the middle for context |
| Wrong output | Diff expected vs actual: `diff <(expected) <(actual)` |
| Timeout/hang | Is it an infinite loop? Deadlock? I/O bound? Add a timer or counter |
### Add minimal instrumentation
- C: `fprintf(stderr, "reached checkpoint %d\n", __LINE__);`
- Python: `print(f"DEBUG: {var=}", file=sys.stderr)`
- Check intermediate values, not just final output
- Remove debug prints after fixing
## Step 4: Fix
- Change ONE thing at a time
- If the same approach fails 3 times → completely different strategy
- Don't add workarounds — fix the root cause
- Common root causes:
- Off-by-one errors (loop bounds, array indexing)
- Type mismatches (int vs float, signed vs unsigned)
- Encoding issues (UTF-8 vs bytes)
- Path errors (relative vs absolute, missing trailing slash)
- Race conditions (file not written yet, process not started)
## Step 5: Verify
- Run the same command that failed before
- Test with multiple inputs, not just the one that was failing
- Check edge cases: empty input, single element, very large input
- Run any existing test suite
## Common Failure Patterns
### "It compiles but gives wrong output"
1. Print all intermediate values
2. Compare with a known-correct reference implementation
3. Check: integer overflow, floating point precision, endianness
### "It works on small input but times out on large"
1. Check algorithm complexity — O(n²) on 1M items = timeout
2. Profile: which loop/function takes the most time?
3. Restructure: hash maps, sorting, streaming
### "It works locally but fails in the test"
1. Check: absolute vs relative paths
2. Check: different working directory
3. Check: different input format than expected
4. Read the test script to understand what it actually checks
© vstorm-co · MIT · vstorm-co/pydantic-deepagents
Похожие скиллы
Все скиллы по теме «Тесты и QA» →Сначала — systematic-debugging от других авторов.