메뉴
A feedback-loop-first discipline for diagnosing hard bugs and performance regressions. Use when the user reports something broken, throwing, failing, flaky, or slow, or asks to "diagnose", "debug this", "原因を調べて".
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
A relentless one-question-at-a-time interview that sharpens a plan, decision, or idea until shared understanding is reached — not limited to software. Use when the user wants requirements or a decision clarified before acting, wants to stress-test their thinking, or asks to "grill me", "詰めて", "brainstorm this".
Executes an implementation plan or agreed work by orchestrating fresh subagents — one implementer per task, a reviewer between tasks — while the main model plans, briefs, and evaluates without writing code itself. Use when the user asks to "implement the plan", "start implementation", "実装して", or hands over a plan or spec to execute.
Builds a clearly-marked throwaway prototype to answer a design question before committing to an implementation. Use when the user wants to sanity-check whether logic or a state model feels right, explore what a UI should look like, or asks to "prototype this", "試作して".
Creates an Architecture Decision Record for a decision that is hard to reverse, surprising without context, and the result of a real trade-off. Use when such a decision has just been made, or the user asks to "record this decision", "ADRにして", or mentions decision records.
Reviews the diff since a fixed point along two axes run as parallel subagents — Spec (does the change match what was asked?) and Standards (repo conventions plus a code-smell baseline) — and reports them side by side. Use when the user asks to review a branch, work-in-progress changes, a diff, or "review since X".
Configures this repository for the engineering skills by writing .claude/engineering.local.md — where specs, plans, and ADRs are saved, if at all — and excluding it from git locally. Run once per repository before relying on doc-saving skills.
| name | diagnose-bug |
| description | A feedback-loop-first discipline for diagnosing hard bugs and performance regressions. Use when the user reports something broken, throwing, failing, flaky, or slow, or asks to "diagnose", "debug this", "原因を調べて". |
A discipline for hard bugs and performance regressions. Skip phases only when explicitly justified.
This is the skill. Everything else — bisection, hypothesis-testing, instrumentation — just consumes a tight pass/fail signal once you have one. Reading code to build a theory before that signal exists is the failure this skill prevents: stop and come back here.
Construct one, roughly in this order of preference: a failing test at whatever seam reaches the bug, a curl/CLI invocation diffed against a known-good snapshot, a headless browser script asserting on DOM/console/network, a replayed captured trace, a throwaway harness exercising the bug path in isolation, or a bisection/differential loop comparing two states or configs.
Once you have a loop, tighten it: faster (skip unrelated init, narrow scope), sharper (assert the specific symptom, not "didn't crash"), more deterministic (pin time, seed RNG, isolate filesystem/network). For non-deterministic bugs, aim for a higher reproduction rate rather than a clean repro — loop the trigger many times, parallelize, narrow timing windows, until the failure is frequent enough to debug against.
Phase 1 is done when you can name one command — already run, output pasted — that is red-capable (catches this specific bug, not just "errors"), deterministic, fast, and agent-runnable. If you genuinely cannot build a loop, say so explicitly, list what you tried, and ask the user for environment access or a captured artifact rather than proceeding to hypothesize without one.
Run the loop and confirm it produces the failure mode the user actually described, not a different one nearby.
Then shrink the repro to the smallest scenario that still goes red: cut inputs, callers, config, and steps one at a time, re-running after each cut. Done when every remaining element is load-bearing — removing any one of them makes the loop go green. This narrows the hypothesis space in Phase 3 and becomes the regression test in Phase 5.
Generate 3–5 ranked hypotheses before testing any of them; a single hypothesis anchors on the first plausible idea. Each must be falsifiable: "If X is the cause, changing Y makes it disappear." Discard or sharpen anything you can't state as a prediction.
Show the ranked list to the user before testing — they often re-rank instantly with domain knowledge, or know hypotheses already ruled out. Don't block on a response if they're unavailable.
Each probe should map to a specific prediction from Phase 3, changing one variable at a time. Prefer a debugger or REPL inspection over logs — one breakpoint beats ten logs. When logs are the only option, tag each with a unique prefix (e.g. [DEBUG-a4f2]) so cleanup is a single grep.
For performance regressions, logs are usually misleading. Measure a baseline first (timing harness, profiler, query plan), then bisect against it.
Write the regression test before the fix, but only if a correct seam exists — one where the test exercises the real bug pattern as it occurs at the call site, not a shallow substitute. If no correct seam exists, that's itself a finding: note it, the architecture is preventing the bug from being locked down.
When a seam exists: turn the minimised repro into a failing test there, watch it fail, apply the fix, watch it pass, then re-run the Phase 1 loop against the original, unminimised scenario.
Before declaring done: the original repro no longer reproduces, the regression test passes (or the missing seam is documented), all [DEBUG-...] instrumentation is removed, and the hypothesis that turned out correct is stated in the commit message so the next debugger learns.
An architectural cause behind the bug — no good seam, tangled callers — is worth recording; record-adr is a candidate.
