debug-systematic — скилл для Claude Code: отладка и установка
Скилл debug-systematic для Claude Code ведёт агента через четыре фазы отладки: воспроизведение, локализацию, поиск причины и проверку исправления. Разбирает сложные и плавающие ошибки.
MIT 152 установок ★ 114 обновлён 2026-11-10
npx skills add travisjneuman/.claude --skill debug-systematic -a claude-codeЧто делает debug-systematic
debug-systematic задаёт последовательный протокол для расследования ошибок. Сначала агент фиксирует шаги воспроизведения, окружение, частоту сбоя и точные сообщения, затем сужает область поиска до компонента, функции или диапазона строк. Без воспроизводимого сценария расследование не переходит к содержательной проверке гипотез.
Для локализации используются бинарный поиск, git bisect, удаление лишнего кода и сравнение окружений. На этапе диагностики агент формулирует гипотезу, делает прогноз и проверяет его логами или другими свидетельствами. Скилл также предлагает минимальное исправление, проверку побочных эффектов и меры против повторения ошибки.
Тест, фиксирующий сбой, добавляется только по просьбе пользователя. При регрессиях можно применять команды git bisect start, git bisect bad HEAD и git bisect good <known-good-commit>.
Какие задачи решает
- воспроизвести плавающий сбой
- локализовать регрессию в истории Git
- отделить ошибку окружения от ошибки кода
- найти причину race condition
- проверить исправление и защититься от повторения
Примеры запросов агенту
- Разбери этот сбой по четырём фазам: сначала зафиксируй воспроизведение, затем локализуй причину.
- Проверь регрессию через
git bisect, начиная сHEADи известного рабочего коммита. - Найди корневую причину ошибки, предложи минимальное исправление и проверь побочные эффекты.
Как установить debug-systematic
1Через Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a claude-code2Вручную: положить файлы
~/.claude/skills/debug-systematic/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/debug-systematic/
1Через Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a codex2Вручную: положить файлы
.agents/skills/debug-systematic/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a cursor2Вручную: положить файлы
.cursor/skills/debug-systematic/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install travisjneuman/.claude skills/debug-systematic2Вручную: положить файлы
.github/skills/debug-systematic/SKILL.md1Через Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a gemini-cli2Командой платформы
gemini skills install https://github.com/travisjneuman/.claude --path skills/debug-systematicВручную: положить файлы
.devin/skills/debug-systematic/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add travisjneuman/.claude --skill debug-systematic -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о debug-systematic
Как установить debug-systematic в Claude Code?
Выполните npx skills add travisjneuman/.claude --skill debug-systematic -a claude-code. После установки скилл находится в ~/.claude/skills/debug-systematic/SKILL.md.
Что делает debug-systematic?
Скилл проводит агента через воспроизведение, локализацию, диагностику и проверку исправления. Он помогает опираться на наблюдения, а не менять код наугад.
Добавляет ли скилл тест для найденной ошибки?
Тест, фиксирующий сбой, он предлагает писать только тогда, когда пользователь попросил о тестах.
Исходный текст
SKILL.md · MIT
---
name: debug-systematic
description: Systematic 4-phase debugging methodology for complex, intermittent, or mysterious issues. Use when investigating bugs, race conditions, or unexplained failures.
---
# Systematic Debugging Protocol
A disciplined, evidence-based approach to debugging that prevents guessing and ensures root cause discovery.
## The 4-Phase Protocol
### Phase 1: REPRODUCE (Establish Ground Truth)
**Goal**: Create reliable reproduction steps before ANY investigation.
**Actions**:
1. Document exact steps to trigger the bug
2. Record environment specifics (OS, versions, config, memory, network)
3. Determine frequency: Always? Sometimes? Specific conditions?
4. Capture exact error messages, stack traces, screenshots
5. Test on different environments to isolate variables
**Key Questions**:
- When did it last work correctly?
- What changed since then? (code, deps, config, infrastructure)
- Is it environment-specific?
- Is it data-specific?
- Is it timing-specific?
**Output**: Clear reproduction steps that reliably trigger the issue.
---
### Phase 2: ISOLATE (Narrow the Scope)
**Goal**: Reduce the search space from "entire codebase" to "specific component."
**Techniques**:
**Binary Search**:
1. Identify two points: working state and broken state
2. Test the midpoint
3. Recurse into the broken half
4. Continue until the change is identified
**Git Bisect** (for regressions):
```bash
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# Git will checkout commits for testing
# After each test:
git bisect good # or git bisect bad
# Continue until culprit found
```
**Code Elimination**:
- Comment out sections to isolate the problem
- Create minimal reproduction case
- Strip away everything non-essential
**Environment Isolation**:
- Exercise the failing path in isolation (minimal reproduction; a unit test only when the user asked for tests)
- Compare working vs broken environments
- Use fresh installs to eliminate pollution
**Output**: "The bug is in [specific component/function/line range]"
---
### Phase 3: DIAGNOSE (Understand Root Cause)
**Goal**: Know exactly WHY the bug occurs, not just WHERE.
**Scientific Method**:
1. **Observe**: What exactly is happening?
2. **Hypothesize**: Why might this be happening?
3. **Predict**: If hypothesis is correct, what else would be true?
4. **Test**: Verify predictions with evidence
5. **Iterate**: Refine hypothesis based on results
**Logging Strategy**:
```javascript
// Add strategic logging at boundaries
console.log("[DEBUG] Function entry:", { input, state });
console.log("[DEBUG] After processing:", { result, sideEffects });
console.log("[DEBUG] Function exit:", { returnValue });
```
**Common Root Causes**:
| Symptom | Likely Causes |
| -------------------------- | -------------------------------------------------- |
| Works locally, fails in CI | Environment differences, timing, resources |
| Intermittent failure | Race condition, flaky network, resource contention |
| Works then stops working | State mutation, memory leak, cache poisoning |
| Wrong data | Type coercion, encoding, timezone, precision |
| Silent failure | Swallowed exception, async error, missing await |
**Output**: Clear explanation of the root cause with evidence.
---
### Phase 4: FIX & VERIFY (Resolve and Prevent)
**Goal**: Fix the issue and prevent regression.
**Fix Process**:
1. **Implement minimal fix** - change as little as possible
2. **Check for similar patterns** - same bug elsewhere?
3. **Review fix for side effects** - read the callers, inputs, and error paths it touches
4. **Document the fix** - why it happened, how to prevent
Write a failing test that captures the bug only when the user asked for tests.
**Verification Checklist**:
- [ ] Review shows the Phase 3 root cause is addressed, not just the symptom
- [ ] The output the fix already produces (the reproduction, the command that did the work) confirms it
- [ ] Fix works in all affected environments
- [ ] No new warnings or errors introduced
**Prevention**:
- Add guards/validation at boundaries
- Improve error messages for easier future debugging
- Document gotchas for other developers
- Consider if architectural change prevents similar bugs
---
## Debugging Anti-Patterns
**DO NOT**:
- Guess and hope (change things randomly)
- Assume you know the problem without evidence
- Trust comments/docs over actual code behavior
- Debug production with print statements you'll forget to remove
- Fix the symptom instead of the root cause
- Make multiple changes at once
**DO**:
- Verify assumptions with evidence
- Change one thing at a time
- Log actual values, not what you expect
- Trust the code over documentation
- Take breaks when stuck (fresh eyes help)
---
## Quick Reference
```
1. REPRODUCE → Can I reliably trigger this?
2. ISOLATE → Where exactly is it failing?
3. DIAGNOSE → Why is it failing?
4. FIX → How do I fix it permanently?
```
---
## Output Template
```markdown
## Bug Investigation: [Title]
### Reproduction
- Steps to reproduce
- Environment details
- Frequency
### Isolation
- Search method used
- Scope narrowed to
### Root Cause
- What's actually wrong
- Why it happens
- Evidence
### Fix
- Code changes made
- What review confirmed, and what it couldn't
### Prevention
- How to prevent similar bugs
- Documentation updates
```
© travisjneuman · MIT · travisjneuman/.claude