debug-mode
Skill14 starsChanged 6 months agoMITView on GitHub
Runtime debug mode - insert log probes, collect runtime data, locate and fix bugs. Best for: reproducible bugs with unclear cause, race conditions, timing issues, performance/memory leaks, and regressions. Use when user says: "debug-mode", "debug mode", "探针调试", "运行时调试", "trace this bug", "找出这个bug", "加日志排查", "插探针", or needs to debug runtime issues that static analysis can't solve.
- Deletes or force-pushes
9 other projects use a version of this.
Adopted by
Most recently taken up by
- doraemonkeys/claude-code-debug-modetheir own version, first seen Oct 24, 2026
- whoaskedssselery/claude-workspacetheir own version, first seen Oct 20, 2026
- liush2yuxjtu/pi-debug-modetheir own version, first seen Oct 17, 2026
- wangnan0916/runtime-debug-toolkittheir own version, first seen Oct 15, 2026
- kaushik912/my-claude-skillstheir own version, first seen Sep 28, 2026
- heiets/universal-debug-mode-skilltheir own version, first seen Sep 14, 2026
Other versions9 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 9
- doraemonkeys/claude-code-debug-mode★ 120same name
- liush2yuxjtu/pi-debug-mode★ 4same name
- vanenshi/skills★ 2same name
- kaushik912/my-claude-skills★ 1same name
- duniecdawid/ultra-claude★ 0same name
- heiets/universal-debug-mode-skill★ 0same name
- khanashes/claude-skills★ 0same name
- wangnan0916/runtime-debug-toolkit★ 0same name
- whoaskedssselery/claude-workspace★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- app-icon-generatorSkill
- break-itSkill
- dev-launcherSkill
- diagram-proSkill
- image-uploadSkill
- localizeSkill
- mac-app-uninstallSkill
- mac-cleanup-diskSkill
- mac-cleanup-memorySkill
- mac-cleanup-processSkill
- macos-app-scaffoldSkill
- npm-safetySkill
- root-causeSkill
- skill-scanSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. 0 are common, 9 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 9 edited versions we read keep these.
9
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 50
Before reading any code, ask the user targeted questions to collect clues.
- Distinctive: line 61
If the user's initial description is detailed enough (includes repro steps, error messages, expected vs actual), skip this step and proceed …
- Distinctive: line 67
Read relevant code, identify suspect areas
- Very specific: line 121
No setup needed — probes use console.log with a [DEBUG PROBE N] prefix.
- Distinctive: line 133
All probes MUST be wrapped in START/END block comments for safe block-level cleanup:
- Very specific: line 143
After inserting all probes, print: ✅ CHECKPOINT 3: N probes inserted into source files
- Very specific: line 147
Use console.log with a structured prefix.
- Distinctive: line 228
For file-based logging: Before each run, write a run separator to the log:
- Very specific: line 255
For intermittent bugs (race conditions, timing issues): run multiple times (2-3 runs) with a separator before each.
- Distinctive: line 291
After verification passes, proceed to cleanup
- Distinctive: line 295
If the user reports the fix didn't work:
- Distinctive: line 319
Search for all probe blocks in code:
- Distinctive: line 327
Verify cleanup is complete:
- Very specific: line 351
All probes MUST use 🔍 DEBUG PROBE [N] label / 🔍 DEBUG PROBE END [N] block markers — this ensures safe block-level deletion during cleanup
- Very specific: line 354
Add .claude-debug/ to .gitignore if not already ignored
“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Debug Mode — Runtime Debugging
Locate and fix bugs by inserting log probes, collecting runtime data, and analyzing execution traces. Multi-language support.
⛔ MANDATORY RULES — ENFORCED VIA CHECKPOINTS
This skill uses a checkpoint system. You MUST print each checkpoint marker BEFORE proceeding to the next step. If you skip a checkpoint, the entire debug session is invalid.
Each step ends with a checkpoint that you must print exactly:
✅ CHECKPOINT 1: Probe plan created — N probes planned✅ CHECKPOINT 2: Log collector started✅ CHECKPOINT 3: N probes inserted into source files(you must have used the Edit tool N times)✅ CHECKPOINT 4: N log entries collected✅ CHECKPOINT 5: Root cause identified with log evidence✅ CHECKPOINT 6: Fix applied and verified with probes✅ CHECKPOINT 7: All probes removed, cleanup complete
HARD RULES:
- You CANNOT print CHECKPOINT 5 without first printing CHECKPOINTS 1-4
- You CANNOT propose a fix without citing specific log entries as evidence
- You MUST use the Edit tool to physically insert probe code into source files at Step 3 — reading code and proposing probes mentally does not count
- You MUST collect and read actual log output at Step 5 — you cannot analyze logs you haven't collected
- Static analysis may reveal an obvious issue — you may fix it first. But if the fix doesn't work, you MUST instrument and collect runtime data before attempting another fix. The purpose is runtime verification, not guesswork.
Core Principles
- Understand before instrumenting — Read code and error messages, identify suspect areas, place probes only on critical paths
- Minimal intrusion — Probes must not alter original logic, only observe and record
- Closed loop — Instrument → Run → Collect → Analyze → Fix → Verify → Clean up
Workflow
Step 0: Triage — Gather Context from User
Before reading any code, ask the user targeted questions to collect clues. Only ask what you don't already know — skip questions the user has already answered in their initial message.
Questions to consider (pick the relevant ones):
- What is the expected behavior vs actual behavior?
- How do you reproduce it? (exact steps, commands, or user actions)
- Is it consistent or intermittent? (every time, or only sometimes?)
- When did it start? (after a specific change, deployment, or dependency update?)
- Any error messages or stack traces? (ask user to paste them)
- What have you already tried?
If the user's initial description is detailed enough (includes repro steps, error messages, expected vs actual), skip this step and proceed directly to Step 1.
Print: ✅ CHECKPOINT 0: Context gathered
Step 1: Understand the Problem & Plan Probes
- Read relevant code, identify suspect areas
- Form 2-3 hypotheses
- For each hypothesis, plan probes: which file, which line, which variables to observe
- Determine the logging strategy based on runtime environment:
- CLI / Server / Script → file-based logging (
.claude-debug/debug.log) - Browser / Frontend (Vue, React, etc.) →
console.logprobes (user pastes output) - Hybrid (SSR, Electron) → file-based for server, console for renderer
- CLI / Server / Script → file-based logging (
- Output the probe plan as a table, then immediately proceed to Step 2:
📋 Probe Plan:
| # | File:Line | Label | Variables | Hypothesis |
|---|-----------|-------|-----------|------------|
| 1 | app.js:22 | checkout-cache-check | available, sku | Cache returning stale value |
| 2 | app.js:45 | reserve-entry | stock, reserved | Actual stock state at reservation time |
...
Logging strategy: file-based / console / hybrid
⏳ Inserting probes...Step 2: Start Log Collector
For file-based logging (CLI / Server):
Initialize the debug directory with a structured log system:
mkdir -p .claude-debug
: > .claude-debug/debug.log
echo "run_count=0" > .claude-debug/stateWriting a run separator — before each execution, write a run header:
RUN_NUM=$(($(awk -F= '/run_count=/ {print $2}' .claude-debug/state) + 1))
echo "run_count=$RUN_NUM" > .claude-debug/state
echo "" >> .claude-debug/debug.log
echo "========== RUN #$RUN_NUM | $(date -u +%Y-%m-%dT%H:%M:%SZ) ==========" >> .claude-debug/debug.logThis ensures multiple runs are clearly separated in the log file.
Optional: HTTP collector (for JS/TS/Python projects that benefit from a debug server)
node "${CLAUDE_SKILL_DIR}/scripts/debug-server.js" 3333 &
echo $! > .claude-debug/server.pid
curl -s http://localhost:3333/healthFor console-based logging (Browser / Frontend):
No setup needed — probes use console.log with a [DEBUG PROBE N] prefix. Tell the user to open the browser console (F12 → Console) and filter by DEBUG PROBE.
Step 3: Insert Probes (MUST use Edit tool)
You MUST use the Edit tool to physically modify source files. For each probe in your plan, call the Edit tool once to insert the probe code. Do not just describe what probes you would insert — actually insert them.
Select the probe template matching the project language and runtime environment. Every probe MUST include:
- File name and line number
- Label (semantic description of probe location)
- Key variable values
- Timestamp (for file-based logging) or structured prefix (for console logging)
All probes MUST be wrapped in START/END block comments for safe block-level cleanup:
// 🔍 DEBUG PROBE [N] label
<probe code - one or more lines>
// 🔍 DEBUG PROBE END [N]Where [N] is the probe number from the plan. This ensures cleanup can delete entire blocks without accidentally removing real code.
After inserting all probes, print: ✅ CHECKPOINT 3: N probes inserted into source files
Browser / Frontend (Vue, React, Svelte, etc.)
Use console.log with a structured prefix. For reactive frameworks, access .value for refs/signals:
// 🔍 DEBUG PROBE [1] funcName-entry
console.log(`[DEBUG PROBE 1] funcName-entry | var1=${var1} | var2=${JSON.stringify(var2)}`)
// 🔍 DEBUG PROBE END [1]Vue-specific (reactive state):
// 🔍 DEBUG PROBE [1] reactive-state
console.log(`[DEBUG PROBE 1] reactive-state | refVal=${someRef.value} | computedVal=${someComputed.value} | storeVal=${store.someState}`)
// 🔍 DEBUG PROBE END [1]React-specific (hooks state):
// 🔍 DEBUG PROBE [1] component-render
console.log(`[DEBUG PROBE 1] component-render | state=${JSON.stringify(state)} | prop=${prop}`)
// 🔍 DEBUG PROBE END [1]JavaScript / TypeScript (Node.js / Server)
// 🔍 DEBUG PROBE [1] funcName-entry
require('fs').appendFileSync('.claude-debug/debug.log', `[${new Date().toISOString()}] [js] file.js:42 | funcName-entry | var1=${JSON.stringify(var1)}, var2=${JSON.stringify(var2)}\n`);
// 🔍 DEBUG PROBE END [1]Python
# 🔍 DEBUG PROBE [1] funcName-entry
import datetime; open(".claude-debug/debug.log", "a").write(f"[{datetime.datetime.now().isoformat()}] [python] file.py:42 | funcName-entry | var1={var1}, var2={var2}\n")
# 🔍 DEBUG PROBE END [1]Swift
// 🔍 DEBUG PROBE [1] funcName-entry
if let fh = FileHandle(forWritingAtPath: ".claude-debug/debug.log") {
fh.seekToEndOfFile()
fh.write("[\(ISO8601DateFormatter().string(from: Date()))] [swift] file.swift:42 | funcName-entry | val=\(variable)\n".data(using: .utf8)!)
fh.closeFile()
}
// 🔍 DEBUG PROBE END [1]Go
// 🔍 DEBUG PROBE [1] funcName-entry
if f, err := os.OpenFile(".claude-debug/debug.log", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644); err == nil {
fmt.Fprintf(f, "[%s] [go] file.go:42 | funcName-entry | var=%v\n", time.Now().Format(time.RFC3339), variable)
f.Close()
}
// 🔍 DEBUG PROBE END [1]Java / Kotlin
// 🔍 DEBUG PROBE [1] funcName-entry
java.io.File(".claude-debug/debug.log").appendText("[${java.time.Instant.now()}] [kotlin] file.kt:42 | funcName-entry | var=$variable\n")
// 🔍 DEBUG PROBE END [1]Shell / Bash
# 🔍 DEBUG PROBE [1] funcName-entry
echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [bash] script.sh:42 | funcName-entry | var=$variable" >> .claude-debug/debug.log
# 🔍 DEBUG PROBE END [1]Step 4: Run & Reproduce
For file-based logging: Before each run, write a run separator to the log:
RUN_NUM=$(($(awk -F= '/run_count=/ {print $2}' .claude-debug/state) + 1))
echo "run_count=$RUN_NUM" > .claude-debug/state
echo -e "\n========== RUN #$RUN_NUM | $(date -u +%Y-%m-%dT%H:%M:%SZ) ==========" >> .claude-debug/debug.logThen run the code:
<project run command>For console-based logging (Browser / Frontend): Tell the user:
"Probes inserted at:
fileA.xx:line— observing XXXfileB.xx:line— observing YYYPlease:
- Open browser console (F12 → Console)
- Reproduce the issue
- Copy all lines starting with
[DEBUG PROBEand paste them here"
For any project requiring manual interaction (GUI app, mobile): Tell the user which probes are in place and ask them to reproduce and share the output.
For intermittent bugs (race conditions, timing issues): run multiple times (2-3 runs) with a separator before each. Compare logs across RUN #1, RUN #2, etc. to spot inconsistencies.
Step 5: Analyze Logs
For file-based logging:
cat .claude-debug/debug.logFor console-based logging: analyze the log entries pasted by the user.
Analysis checklist:
- Ordering: Is the execution order as expected?
- Missing entries: Which probes were NOT triggered (code paths not taken)?
- Unexpected values: Are variable values as expected?
- Duplicates: Any unexpected repeated executions (loop/reentry issues)?
- Timing gaps: Abnormal time intervals between probes (performance/timeout issues)?
Step 6: Locate & Fix
Based on log analysis:
- State the root cause clearly, citing specific log entries as evidence
- Implement the fix
- Keep probes in place, re-run to collect "after fix" logs:
For file-based logging:
echo -e "\n========== VERIFY | $(date -u +%Y-%m-%dT%H:%M:%SZ) ==========" >> .claude-debug/debug.log
<project run command>For console-based logging: ask the user to reproduce again and paste the new console output.
- Compare "before fix" and "VERIFY" logs — the problematic entries should now show correct values
- After verification passes, proceed to cleanup
Fix Failed — What Next
If the user reports the fix didn't work:
- Don't remove existing probes — they provide baseline data
- Add targeted probes around the fix you just applied — observe whether the fix code actually executes, and what values it sees
- Compare before/after logs — look for:
- Did the new code path execute at all? (missing probe entry = code not reached)
- Did it execute but with unexpected input values?
- Did another code path override or undo the fix?
- Re-run and collect. Maximum 3 iterations total. After 3 rounds, report findings and discuss next steps with the user.
Step 7: Cleanup
MANDATORY — must not be skipped:
# Stop HTTP collector (if started)
if [ -f .claude-debug/server.pid ]; then
kill $(cat .claude-debug/server.pid) 2>/dev/null
fi
# Delete debug directory (if created)
rm -rf .claude-debug/Search for all probe blocks in code:
grep -rn "🔍 DEBUG PROBE" . --include="*.ts" --include="*.js" --include="*.py" --include="*.swift" --include="*.go" --include="*.kt" --include="*.java" --include="*.sh" --include="*.vue" --include="*.jsx" --include="*.tsx" --include="*.svelte"For each file, remove entire probe blocks — everything from 🔍 DEBUG PROBE [N] to 🔍 DEBUG PROBE END [N] inclusive. Use the Edit tool to delete each block. The START/END markers ensure no real code is accidentally removed.
Verify cleanup is complete:
grep -rn "DEBUG PROBE" . --include="*.ts" --include="*.js" --include="*.py" --include="*.swift" --include="*.go" --include="*.kt" --include="*.java" --include="*.sh" --include="*.vue" --include="*.jsx" --include="*.tsx" --include="*.svelte"This must return zero results. No probe code may remain.
Probe Label Conventions
| Pattern | Example | Use For |
funcName-entry | processOrder-entry | Function entry |
funcName-exit | processOrder-exit | Function exit |
funcName-error | processOrder-error | Error catch |
varName-state | cart-state | State snapshot |
reactive-state | reactive-state | Vue ref/computed, React state |
condition-branch | earlyReturn-branch | Control flow branch |
loop-iter | retry-iter | Loop iteration |
async-await | fetchData-await | Async await point |
Important Notes
- Probe code must not affect original logic (all probes wrapped in try-catch or error suppression)
- All probes MUST use
🔍 DEBUG PROBE [N] label/🔍 DEBUG PROBE END [N]block markers — this ensures safe block-level deletion during cleanup - Log directory is
.claude-debug/, log file is.claude-debug/debug.log, run counter is.claude-debug/state - Each run is separated by
========== RUN #N | timestamp ==========, verification run is labeled========== VERIFY | timestamp ========== - Add
.claude-debug/to .gitignore if not already ignored - For production code, confirm with user before inserting probes
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

