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

debug-systematic — скилл для Claude Code: отладка и установка

Скилл debug-systematic для Claude Code ведёт агента через четыре фазы отладки: воспроизведение, локализацию, поиск причины и проверку исправления. Разбирает сложные и плавающие ошибки.

MIT 152 установок ★ 114 обновлён 2026-11-10

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

Что делает 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-code

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

~/.claude/skills/debug-systematic/SKILL.md

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

По шагам, с командами для каждой платформы: Как установить скилл в 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

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

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
systematic-debugging bobmatnyc Скилл systematic-debugging для Claude Code ведёт агента от воспроизведения ошибки до проверки исправления. Выявляет причину сбоя или неожиданного поведения. CX Codex +1 400установок ce-debug EveryInc Скилл ce-debug для Claude Code находит причину ошибки или медленной работы. Запускается по просьбе разобраться со сбоем или исправить его. CX Codex +1 3 700установок debug alexj11324 Скилл debug для Claude Code организует системную отладку ошибок и упавших тестов. Он удерживает агента от поспешных правок, пока не сформулирована и не проверена гипотеза. CX Codex +1 ★ 88звёзд репо debug-session rohitg00 Плагин debug-session организует интерактивную сессию отладки кода вместе с поиском регрессий через git bisect. Помогает локализовать сбойный коммит в истории репозитория. ★ 2 858звёзд репо gjalla-debug gjalla Скилл gjalla-debug для поиска первопричины бага с доказательствами до того, как агент предложит исправление. Работает с Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode. CX Codex +1 357установок debug-mantra thananon Скилл debug-mantra для Claude Code задаёт порядок отладки: воспроизвести сбой, найти путь ошибки, проверить гипотезы и сверить результаты. Запускается по /debug-mantra и при сообщениях об ошибках или поломках. CX Codex +1 5 100установок

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

Весь набор →
agent-teams Учит Claude собирать команды агентов: когда они уместны, сколько участников брать и как писать промпты запуска. Работает только при включённых Agent Teams. CX Codex +1 153установок generic-fullstack-ux-designer Скилл generic-fullstack-ux-designer для Claude Code задаёт UX-правила для приложений на Next.js и NestJS: состояния загрузки, формы, ошибки и SSR. CX Codex +1 153установок fundraising-analyzer Скилл fundraising-analyzer помогает разбирать фандрайзинг: сегментировать доноров, считать ROI кампаний и отслеживать удержание. Нужен при оценке сборов и планировании кампаний. CX Codex +1 153установок microservices-architecture Скилл microservices-architecture для Claude Code помогает проектировать микросервисные системы, делить монолит и выбирать способы связи между сервисами. Активируется при обсуждении распределённой архитектуры. CX Codex +1 153установок mobile-cicd Скилл mobile-cicd настраивает сборку, подпись кода и публикацию мобильных приложений для iOS и Android через Fastlane, GitHub Actions и EAS Build. CX Codex +1 152установок ai-policy-generator Скилл ai-policy-generator помогает создавать политики использования ИИ, оценивать риски и оформлять требования к данным, этике и соблюдению норм. CX Codex +1 152установок generic-static-ux-designer Скилл generic-static-ux-designer проектирования интерфейсов для статических сайтов на HTML, CSS и JS с упором на скорость загрузки, доступность и работу без скриптов. CX Codex +1 151установок pwa-development Скилл pwa-development для Claude Code помогает создавать устанавливаемые веб-приложения с поддержкой офлайн-режима. Подключается при разработке PWA, service worker и офлайн-сценариев. CX Codex +1 150установок

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

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