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

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

Скилл systematic-debugging задаёт порядок поиска причины ошибки до предложения исправления. Подключайте его при сбоях сборки, деплоя, тестов и конфигурации, особенно после неудачных попыток починки.

MIT ★ 880 обновлён 2026-09-03

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

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

Сначала скилл предлагает классифицировать ошибку и проверить точное совпадение в официальной документации или GitHub Issues. Если особые условия для быстрого исправления не выполнены, нужно изучить стек ошибки, воспроизвести сбой, проверить недавние изменения и проследить путь данных до источника проблемы. Для систем из нескольких компонентов он предлагает собирать данные на границах между ними.

Дальше идут поиск работающего примера, формулировка одной проверяемой гипотезы и минимальный тест. Перед исправлением предлагается сохранить чистое состояние Git, а после — проверить тесты и убедиться, что проблема решена. После трёх неудачных попыток скилл переключает обсуждение с очередной заплатки на вопрос об архитектуре. Это правило важно соблюдать: накопление исправлений без отката может смешать причины сбоев. Для внешнего поиска и трассировки есть отдельные файлы references/external-research-guide.md и references/root-cause-tracing.md.

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

  • найти источник ошибки по стеку вызовов
  • отличить сбой окружения от ошибки кода
  • воспроизвести нестабильный сбой и собрать данные
  • проверить гипотезу минимальным изменением
  • остановить череду неудачных исправлений и обсудить архитектуру

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

  • Разбери ошибку сборки: сначала установи первопричину, затем предложи минимальную проверку.
  • После двух неудачных исправлений проследи путь данных и проверь недавние изменения.
  • Сбой возникает только в одном компоненте: собери данные на границах и найди, где ломается поток.

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

1Через Skills CLI (Vercel)

npx skills add sangrokjung/claude-forge --skill systematic-debugging -a claude-code

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

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

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

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

Вопросы о systematic-debugging

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

Выполните npx skills add sangrokjung/claude-forge --skill systematic-debugging -a claude-code. Файл скилла будет доступен по пути ~/.claude/skills/systematic-debugging/SKILL.md.

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

Он задаёт этапы расследования технических ошибок и требует установить первопричину до исправления. После нескольких неудачных попыток предлагает обсудить архитектуру, а не добавлять новые заплатки.

Что делать, если исправление не помогло?

Откатите изменение, вернитесь к расследованию и сформулируйте новую гипотезу. После трёх неудачных попыток скилл предлагает остановиться и обсудить архитектурный подход.

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

SKILL.md · MIT
---
name: systematic-debugging
description: |
  Structured debugging methodology — use before proposing fixes for any error or failure.
  Covers: code bugs, build errors, deploy failures, config conflicts, dependency issues, infra problems.
  Also use when previous fix attempts failed or root cause is unclear.
---

# Systematic Debugging

## Overview

Guessing fixes wastes time and creates new bugs. Quick patches hide root problems.

**Core principle: Never fix before finding the root cause. Symptom fixing is failure.**

## Iron Law

```
Never propose a fix without root cause investigation.
```

Phase 0 or Phase 1 must be completed before any fix is proposed.
Phase 0 fixes are ONLY allowed when ALL of these are true:
- External research found an official solution or known issue for this exact error
- Change is single file, single point (config value, import, typo)
- No logic changes

## When to Use

**All technical problems:**
- Test failures, build errors, deploy errors
- Config conflicts, dependency issues
- Infrastructure/environment problems
- Unexpected behavior, performance issues

**Especially when:**
- Under time pressure (urgency breeds guessing)
- "Let me just quickly fix this" comes to mind
- Multiple fix attempts have already been tried
- Previous fixes didn't work
- You don't fully understand the problem

## The Phases

Each Phase must complete before proceeding to the next.

### Phase 0: Quick Assessment

Run immediately when an error occurs. Before any fix attempt.

1. **Classify the error** — read the error message/symptoms:
   - Same code works in different environment? → Environment issue
   - After recent dependency/version change? → Dependency issue
   - Only fails in specific code path? → Code issue

2. **External research (exact match, 5 min max)** — check official docs and GitHub Issues for known issues. Don't rely on self-knowledge alone.
   - See: `references/external-research-guide.md`

3. **Branch decision**:
   - All Iron Law conditions met → Fix in Phase 0
   - Any condition unmet → Enter Phase 1 full process
   - **Phase 0 quick-fix fails**: Undo (git checkout/undo), enter Phase 1. This attempt counts in the fix counter.

### Phase 1: Root Cause Investigation

**Before any fix attempt:**

1. **Read the error carefully**
   - Don't skip errors/warnings
   - Read the entire stack trace
   - Record line numbers, file paths, error codes

2. **Reproduce consistently**
   - Get exact reproduction steps
   - Every time? If intermittent, collect more data

3. **Check recent changes**
   - git diff, recent commits
   - New dependencies, config changes
   - Environment differences (env vars, Node/runtime version, OS)

4. **Research external sources (deep read)**
   - Based on Phase 0 exact match results, investigate further
   - Read official docs for the failure mechanism
   - Check release notes for breaking changes
   - See: `references/external-research-guide.md`

5. **Collect evidence in multi-component systems**
   - Log data in/out at each component boundary
   - Run once to find where it breaks
   - Then deep-dive into that component

6. **Trace data flow**
   - Where does the wrong value originate?
   - Trace the call stack backwards to the source
   - See: `references/root-cause-tracing.md`

### Phase 2: Pattern Analysis

1. **Find similar working code** in the same codebase
2. **Compare with reference implementations** — read the full reference docs, don't skim
3. **Identify all differences** between working and broken — don't assume "that's irrelevant"
4. **Map dependencies** — what config, environment, other components are needed

### Phase 3: Hypothesis and Testing

**Before entering Phase 3:**
- Verify clean state (git status)
- If not clean: git stash or save checkpoint
- On hypothesis failure: rollback to safe point, try new hypothesis (no cumulative fixes)

1. **Form a single hypothesis**: "X is the root cause because Y" — specific, not vague
2. **Test minimally**: smallest change to verify the hypothesis. One variable at a time.
3. **Verify before proceeding**:
   - Success → Phase 4
   - Failure → **New hypothesis** (don't stack fixes on top of failed ones)

### Phase 4: Implementation

1. **Write a failing test** — simplest reproduction, automated if possible, before fixing
2. **Apply a single fix** — only the identified root cause, one change at a time, no "while I'm at it"
3. **Verify the fix** — test passes? No other tests broken? Problem actually resolved?
4. **If fix doesn't work**:
   - How many fix attempts so far?
   - Under 3: return to Phase 1 with new information
   - **3 or more: proceed to Phase 4.5**

### Phase 4.5: Architecture Question

**Pattern of 3+ failed fixes:**
- Each fix reveals new problems elsewhere
- Fix requires "major refactoring"
- Each fix creates symptoms in other places

**Stop immediately and ask fundamental questions:**
- Is this pattern itself sound?
- Are we clinging to it out of inertia?
- Should we refactor the architecture instead of fixing symptoms?

**Report to user and discuss before any more fix attempts.**

## Red Flags — If you think this, STOP

- "Let me quickly fix it and investigate later"
- "Let me try changing X and see if it works"
- "Let me bundle multiple changes and test once"
- "Skip tests, just check manually"
- "It's probably X, let me fix it"
- "I don't fully understand but this might work"
- "Let me just try one more fix" (after 2+ attempts)
- "I don't need to check external docs for this one"
- "This is definitely a code issue" (without checking environment)

**Any of the above: STOP. Return to Phase 0/1.**
**3+ fix failures: Architecture Question (Phase 4.5)**

## Common Rationalizations

| Excuse | Reality |
|--------|---------|
| "Simple problem, don't need the process" | Simple problems have root causes too. The process is fast for simple bugs. |
| "Too urgent for process" | Systematic debugging is **faster** than guessing. |
| "Let me try this first, then investigate" | First fix sets the pattern. Start right. |
| "I'll write tests after fixing" | Fixes without tests don't last. Test first. |
| "Bundle changes to save time" | Can't tell what worked. Creates new bugs. |
| "Docs are too long, I'll wing it" | Partial understanding = guaranteed bugs. Read it all. |
| "I can see the problem, just fix it" | Seeing symptoms ≠ understanding root cause. |
| "One more fix" (2+ failures) | 3+ failures = architecture problem. Ask, don't fix. |
| "I know this error, no need to check docs" | LLM confidence ≠ accuracy. Verify externally. |

## Supporting Techniques

See references in this directory:
- **`references/external-research-guide.md`** — External docs/GitHub Issues lookup procedure
- **`references/root-cause-tracing.md`** — Call stack backtracing to find bug origins

## Quick Reference

| Phase | Key Activity | Success Criteria |
|-------|-------------|-----------------|
| **0. Quick Assessment** | Error classification, external research (exact match) | Error type classified + 1+ external search done |
| **1. Root Cause** | Read errors, reproduce, check changes, deep research | Understand what breaks and why |
| **2. Pattern** | Find working similar code, compare | Differences identified |
| **3. Hypothesis** | Single hypothesis, minimal test | Confirmed or new hypothesis |
| **4. Implementation** | Write test, fix, verify | Bug fixed, tests pass |
| **4.5. Architecture** | Stop after 3 failures, report | Architecture review decision |

© sangrokjung · MIT · sangrokjung/claude-forge

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

Все скиллы по теме «Тесты и QA» →

Сначала — systematic-debugging от других авторов.

systematic-debugging Jesse Vincent Скилл systematic-debugging для Claude Code и Codex блокирует фиксы до завершения анализа первопричины. Включается при падении тестов, баге или неожиданном поведении. CX Codex +1 306 118установок systematic-debugging spencerpauly Скилл systematic-debugging для Claude Code и других агентов: заставляет искать причину бага по шагам вместо случайных правок. Держит под контролем баги, которые проявляются только в продакшене. CX Codex +1 604установок systematic-debugging bobmatnyc Скилл systematic-debugging для Claude Code ведёт агента от воспроизведения ошибки до проверки исправления. Выявляет причину сбоя или неожиданного поведения. CX Codex +1 400установок systematic-debugging ChrisWiles Скилл systematic-debugging задаёт четырёхэтапный протокол отладки с упором на первопричину бага. Скилл пригодится при расследовании падений тестов или внезапных сбоев рантайма без поверхностных правок. CX Codex +1 ★ 6 091звёзд репо systematic-debugging GanyuanRan Скилл systematic-debugging помогает разбирать ошибки, сбои тестов и неожиданное поведение до правок. Он прослеживает причину до места, которое действительно нужно исправить. CX Codex +1 ★ 1 450звёзд репо debug-systematic travisjneuman Скилл debug-systematic для Claude Code ведёт агента через четыре фазы отладки: воспроизведение, локализацию, поиск причины и проверку исправления. Разбирает сложные и плавающие ошибки. CX Codex +1 152установок debugging-and-error-recovery addyosmani Скилл debugging-and-error-recovery для Claude Code помогает найти первопричину сбоя и проверить исправление. Он включается при падении тестов, ошибках сборки и неожиданном поведении кода. CX Codex +1 79 600установок service-debugging c0x12c Скилл service-debugging для Claude Code задаёт пошаговый поиск причин сбоев в бэкенд-сервисах — от сбора симптомов и проверки логов до локализации бага через git bisect. CX Codex +1 ★ 111звёзд репо gitnexus-debugging abhigyanpatwari Скилл gitnexus-debugging для Claude Code ищет причины ошибок в коде по связям между символами, вызовами и процессами. Трассирует сбои и регрессии. CX Codex +1 1 800установок debugging sentimony Скилл debugging для Claude Code задаёт протокол расследования багов и сбоев тестов: агент проверяет факты и воспроизводит ошибку до правок кода. CX Codex +1 2 800установок rstest-debugging rstackjs Скилл rstest-debugging помогает найти причину проблем Rstest со стартом, сборкой, рантаймом, логами, памятью и производительностью по трассам и сопоставимым замерам. CX Codex +1 133установок

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

Весь набор →
relay Скилл relay собирает однострочную команду для /compact и документ-«эстафету» с задачей для следующей сессии, чтобы работа не прерывалась при нехватке контекста. CX Codex +1 ★ 880звёзд репо adversarial-reviewer Субагент adversarial-reviewer для Claude Code проверяет изменения поведения перед закрытием задачи: воспроизводит дефекты и выносит вердикт, не меняя файлы репозитория. CX Codex ★ 880звёзд репо rca-debugger Субагент rca-debugger разбирает сложные сбои, когда обычная отладка не нашла причину: например, при нестабильной ошибке или расхождении CI и локального запуска. CX Codex ★ 880звёзд репо security-reviewer Субагент security-reviewer проверяет изменения кода на уязвимости OWASP Top 10, зашитые секреты и дырявые зависимости. Возвращает отчёт с приоритетами и безопасными примерами. CX Codex ★ 880звёзд репо harness-diet Скилл harness-diet для Claude Code, который измеряет always-loaded контекст харнесса и возвращает его в бюджет. Запускается, когда CLAUDE.md и всегда загружаемые правила разрослись. CX Codex +1 ★ 880звёзд репо tdd Команда ведёт задачу по циклу TDD: сначала интерфейсы и падающие тесты, затем код, рефакторинг и проверка покрытия. CX Codex +1 ★ 880звёзд репо escalation-fixer Субагент escalation-fixer для Claude берётся за сборку, если точечные фиксы не помогли, и может менять структуру проекта. CX Codex ★ 880звёзд репо e2e Команда e2e генерирует и запускает сквозные сценарии на Playwright с паттерном Page Object Model, собирая отчёты и снимки экрана. CX Codex +1 ★ 880звёзд репо

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

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