debug-mode

Debug Mode (consistent with Cursor)

You have entered Debug Mode. Do not directly change business logic and guess at fixes; execute in phase order, and after asking the user to reproduce, stop and wait。

How to enter

• The user enters in Claude Code:/debug-mode(optionally with a bug description)
• Only the user explicitly enters it; do not automatically enter this mode when there is no request

Architecture overview

flowchart LR
  subgraph local["本机"]
    S["debug-server.js<br/>:3847"]
    L[".claude/debug.log"]
  end
  subgraph app["项目代码 #region DEBUG"]
    BE["后端: fetch 或 appendFile"]
    FE["浏览器: fetch POST"]
  end
  FE -->|POST /debug| S
  BE -->|POST /debug 或写文件| S
  BE --> L
  S --> L
  CC["Claude Code"] -->|读/清空日志| L

---

Phase 0: Start the log collection API (once per debug session)

Locate the script from this skill directory (after installation it is usually in ~/.claude/skills/debug-mode/scripts/ or within the project .claude/skills/debug-mode/scripts/）：

# SKILL_SCRIPTS = 本 skill 的 scripts 目录绝对路径
# PROJECT_ROOT  = 当前调试的项目根目录（从用户打开的文件路径推断，写死在后续插桩里）
bash "${SKILL_SCRIPTS}/start-server.sh" "${PROJECT_ROOT}" 3847

Verify:

curl -sf http://127.0.0.1:3847/health

• Default port 3847（DEBUG_SERVER_PORT can be overridden)
• Log file:{PROJECT_ROOT}/.claude/debug.log
• Remote/read-only filesystem: logs can instead use /tmp/.claude/debug.log, and hard-code that path in the instrumentation

Stop the service after debugging ends:

bash "${SKILL_SCRIPTS}/stop-server.sh" "${PROJECT_ROOT}"

For more detailed language snippets see:references/instrumentation.md(read it again when instrumentation is needed).

---

Phase 1: Understand the Bug

If the user has not explained, ask:

• Expected behavior vs actual behavior
• Reproduction steps, error messages, environment (dev/prod, browser, branch)

Read the relevant source code, clarify the call chain and data flow.

---

Phase 2: Generate hypotheses

Output a list of verifiable hypotheses (at least 2, including non-obvious causes):

基于分析，假设如下：

1. **[标题]** — [可能原因]
2. **[标题]** — ...
3. ...

---

Phase 3: Instrumentation

Logging targets

• Main file:{PROJECT_ROOT}/.claude/debug.log（NDJSON）
• Browser / runtime that can send HTTP:POST http://127.0.0.1:3847/debug
• The server side can also directly append to the same log file (see references/instrumentation.md）

project_root rules (same as Cursor)

PROJECT_ROOT in instrumentation must be ahard-coded absolute path string(inferred from the file path in the conversation).

ProhibitedIn the instrumentation code, use:import.meta.dir、__dirname、process.cwd()、Deno.cwd()、path.resolve() and other runtime resolution.

Exception: remote CI / locally unwritable → use /tmp/.claude/debug.log。

Region markers

All instrumentation must be wrapped in a region for one-time removal:

// #region DEBUG
...instrumentation...
// #endregion DEBUG

(For Python/HTML/Go etc. see references/instrumentation.md）

Logging rules

• Prohibited console.log、print, writing stderr/stdout as debug output
• Each log entry carries a hypothesis number:[DEBUG H1]、[DEBUG H2] …
• Record: variable values, branches, timing, key decision points; keep the minimal necessary set
• Before each time the user reproduces:clear the log

bash "${SKILL_SCRIPTS}/clear-log.sh" "${PROJECT_ROOT}" 3847

After instrumentation is complete, tell the user how to reproduce, then STOP and wait(do not continue analyzing or change the fix logic).

---

Phase 4: Analyze the logs and diagnose

After the user confirms reproduction:

1. First look at the log volume：wc -l or ls -lh; if too large, use tail / grep '\[DEBUG H'
2. Map log lines to hypotheses:confirm / rule out
3. Output a diagnosis (with evidence):

## 诊断

**根因**：[有日志依据的结论]

**证据**：
- [H1] 排除 — …
- [H2] 证实 — [引用日志字段/行]

If evidence is insufficient: propose a new hypothesis → add more instrumentation → clear the logs → ask the user to reproduce again.

---

Phase 5: Fix

• Implement the fix,keep #region DEBUG instrumentation
• Again clear-log.sh, ask the user to verify whether the fix works, then STOP and wait

---

Phase 6: Verify and clean up

If fixed:

1. Use Grep to find #region DEBUG, delete all regions and the code within them
2. Delete .claude/debug.log(and optionally .claude/debug-server.out）
3. stop-server.sh
4. Briefly summarize the root cause and fix

If not fixed:

• Read the new logs, ask the user about the observed symptoms, return to Phase 2 and iterate

---

Hard rules (aligned with Cursor Debug Mode)

Rule	Description
Do not skip phases	Even if you "seem to know the answer", still instrument + verify with logs
Do not remove instrumentation early	Keep it until the user confirms the fix #region DEBUG
Do not debug with stdout	Only write .claude/debug.log or POST /debug
Clear the logs before each reproduction	clear-log.sh or > .claude/debug.log
Must be wrapped in a region	For easy cleanup
Wait for the user after reproduction	Do not keep advancing automatically

---

API quick reference

Method	Path	Purpose
GET	/health	Liveness check for the service and log path
POST	/debug	Write one NDJSON line (body: hypothesis, message, data, location）
POST	/clear	Clear the log file

Example POST /debug body:

{
  "hypothesis": "H1",
  "message": "cart total before tax",
  "data": { "subtotal": 99.5, "items": 3 },
  "location": "src/cart.ts:88"
}

---

Install into Claude Code

Copy this directory into one of the personal or project skills paths:

# 个人（全局）
cp -r skills/debug-mode ~/.claude/skills/debug-mode

# 或项目内
mkdir -p .claude/skills && cp -r /path/to/corner-skills/skills/debug-mode .claude/skills/

After restarting Claude Code, use /debug-mode。