Поиск первопричины бага

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

ОтладкаПак: Отладка82 строкиroot-cause-debugging

Установка

Выполните одну команду — она сохранит SKILL.md в папку скиллов агента. Перезапустите агента, и он подхватит скилл сам.

Claude Code — macOS, Linux
mkdir -p ~/.claude/skills/root-cause-debugging && curl -fsSL https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md -o ~/.claude/skills/root-cause-debugging/SKILL.md
Codex, Cursor — macOS, Linux
mkdir -p ~/.agents/skills/root-cause-debugging && curl -fsSL https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md -o ~/.agents/skills/root-cause-debugging/SKILL.md
Claude Code — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.claude\skills\root-cause-debugging" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md -UseBasicParsing -OutFile "$HOME\.claude\skills\root-cause-debugging\SKILL.md"
Codex, Cursor — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.agents\skills\root-cause-debugging" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md -UseBasicParsing -OutFile "$HOME\.agents\skills\root-cause-debugging\SKILL.md"

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/debugging/root-cause-debugging/SKILL.md

SKILL.md

Исходник

Root-Cause Debugging

Your job is to find why the bug happens, not to make the error message go away. Do not edit code to "see if it helps" before you can explain the failure.

Workflow

1. Reproduce

  • Get the exact failing input, command, request or test. Copy the real error text.
  • Run it yourself and watch it fail. If you cannot reproduce it, say so and gather more data (versions, environment, logs, config) instead of guessing.
  • Reduce the reproduction to the shortest form: one command or one failing test.
  • Note whether it fails every time or sometimes. A sometimes-failure is a different problem (timing, shared state, data); record the failure rate over several runs.

2. Read before you change

  • Read the full stack trace from the bottom frame that belongs to the project, not only the top line.
  • Read the code on the failing path end to end, including the callers that produce the bad value.
  • Check what changed recently: git log -p -n 5 -- <file>, dependency bumps, config or environment changes.

3. Isolate

Narrow the search space with cheap experiments:

  • Cut the input down until removing anything more makes the bug disappear.
  • Bypass layers (call the function directly, skip the cache, use a stub for the network) to find which layer owns the fault.
  • Compare a working case with a failing one and list every difference.
  • Add temporary logging or assertions at layer boundaries to see where the data first becomes wrong. Remove them afterwards.

4. Hypothesis, one at a time

  • State one hypothesis in a sentence: "The total is wrong because discount is applied twice when the cart has a coupon."
  • Decide what observation would prove it wrong. Run that check first.
  • Change one thing per experiment. If you change two things and it works, you do not know which one mattered.
  • Write down rejected hypotheses so you do not test them twice.

5. Confirm the cause

You have the cause only when you can answer: why does the bad value appear, where does it originate, and why does the working case not hit it. Show the evidence (a printed value, a failing assertion, a trace line), not a feeling.

6. Fix the cause

  • Fix at the place where the wrong thing is introduced, not where it is noticed. Catching an exception or adding a null check downstream is usually a symptom patch.
  • Check for the same defect elsewhere: grep for the same call pattern or helper.
  • Keep the fix small. Do not refactor unrelated code in the same change.

7. Regression test

  • Write a test that fails on the old code for the right reason, then passes with the fix. Run it both ways: stash or revert the fix temporarily and confirm it fails.
  • Run the surrounding test suite to check you broke nothing.
  • Re-run the original reproduction from step 1.

When fixes keep failing

Stop editing: a fix that does not work means your model of the system is wrong. Then:

  1. List what each attempt disproved.
  2. Re-check the assumptions you never tested: is this the code that runs? the right config? a stale build?
  3. Report to the user what is ruled out and what you need from them.

Report format

  • Symptom: one line, with the exact error.
  • Root cause: what and where (file and function), with the evidence.
  • Fix: what changed and why it addresses the cause.
  • Test: the regression test name and proof that it failed before.
  • Not verified: anything you could not check (other environments, production data).

Pitfalls

  • "It works now" after a change you cannot explain is not a fix. Flaky bugs also "work" after random changes.
  • Do not widen timeouts, add retries or swallow exceptions to hide the failure unless the cause is genuinely external, and then say so.
  • Do not trust comments, variable names or old docs over what the code does when you run it.
  • Do not leave debug prints, temporary files or commented-out experiments in the final diff.
  • Do not delete data, reset the database or discard uncommitted work to get a clean state without asking the user.
  • A bug in a dependency is possible but rare. Prove it with a minimal reproduction before blaming the library.

Source: AnyModel skills catalog · License: CC BY 4.0

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Отладка

Разбор логов

Читает логи и стектрейсы, находит первую настоящую ошибку, сопоставляет события по request id и времени, отделяет причину от каскада последующих ошибок, с рецептами grep и jq. Для расследования ошибок и инцидентов.

Поиск регрессии через git bisect

Находит коммит, который внёс регрессию, через git bisect вручную и автоматически с git bisect run, пропускает нестабильные и несобираемые коммиты. Для случаев, когда раньше работало, а теперь сломано.

Поиск утечек памяти

Подтверждает утечку под стабильной нагрузкой и ищет её через heap snapshot и сравнение в Node.js, tracemalloc в Python или heap dump в JVM, проверяет частые источники: кэши без лимита и слушатели. Используйте, когда память растёт со временем или процесс убивает OOM.

Охота на нестабильные тесты

Находит, почему тест то проходит, то падает: прогоны в цикле, случайный порядок, тайминги, общее состояние, часовые пояса, сеть, порядок в коллекциях, и чинит причину. Используйте, когда CI нестабилен или тест падает лишь иногда.