Debug Mode

Debug Mode（与 Cursor 一致）

你已进入 Debug Mode。不要直接改业务逻辑猜修复；按阶段顺序执行，并在要求用户复现后 停止等待。

进入方式

• 用户在 Claude Code 输入：/debug-mode（可选附带 bug 描述）
• 仅用户显式进入；不要在没有请求时自动进入本模式

架构概览

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：启动日志收集 API（每次 debug 会话一次）

从本 skill 目录定位脚本（安装后通常在 ~/.claude/skills/debug-mode/scripts/ 或项目内 .claude/skills/debug-mode/scripts/）：

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

验证：

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

• 默认端口 3847（DEBUG_SERVER_PORT 可覆盖）
• 日志文件：`{PROJECT_ROOT}/.claude/debug.log`
• 远程/只读文件系统：日志可改用 `/tmp/.claude/debug.log`，并在插桩里写死该路径

结束调试后停止服务：

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

更详细的语言片段见：references/instrumentation.md（需要插桩时再读）。

---

Phase 1：理解 Bug

若用户未说明，询问：

• 期望行为 vs 实际行为
• 复现步骤、错误信息、环境（dev/prod、浏览器、分支）

阅读相关源码，理清调用链与数据流。

---

Phase 2：生成假设

输出 可验证的假设 列表（至少 2 条，含非显而易见原因）：

基于分析，假设如下：

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

---

Phase 3：插桩

日志目标

• 主文件：{PROJECT_ROOT}/.claude/debug.log（NDJSON）
• 浏览器 / 可发 HTTP 的运行时：POST http://127.0.0.1:3847/debug
• 服务端也可 直接 append 同一日志文件（见 references/instrumentation.md）

project_root 规则（与 Cursor 相同）

PROJECT_ROOT 在插桩里必须是写死的绝对路径字符串（从对话中的文件路径推断）。

禁止在插桩代码里使用：import.meta.dir、__dirname、process.cwd()、Deno.cwd()、path.resolve() 等运行时解析。

例外：远程 CI / 本地不可写 → 使用 /tmp/.claude/debug.log。

Region 标记

所有插桩必须包在 region 内，便于一次性删除：

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

（Python/HTML/Go 等见 references/instrumentation.md）

日志规则

• 禁止 console.log、print、写 stderr/stdout 作为调试输出
• 每条日志带假设编号：[DEBUG H1]、[DEBUG H2] …
• 记录：变量值、分支、时序、关键决策点；保持最小必要集
• 每次让用户复现前：清空日志

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

插桩完成后告知用户如何复现，然后 STOP 并等待（不要继续分析或改修复逻辑）。

---

Phase 4：分析日志并诊断

用户确认已复现后：

1. 先看日志体量：wc -l 或 ls -lh；过大则用 tail / grep '\[DEBUG H' 2. 将日志行映射到假设：证实 / 排除 3. 输出诊断（带证据）：

## 诊断

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

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

若证据不足：提出新假设 → 追加插桩 → 清空日志 → 再请用户复现。

---

Phase 5：修复

• 实施修复，保留 #region DEBUG 插桩
• 再次 clear-log.sh，请用户验证修复是否生效，然后 STOP 等待

---

Phase 6：验证与清理

若已修复：

1. 用 Grep 查找 #region DEBUG，删除所有 region 及其中代码 2. 删除 .claude/debug.log（及可选 .claude/debug-server.out） 3. stop-server.sh 4. 简短总结根因与修复

若未修复：

• 读取新日志，询问用户观察到的现象，回到 Phase 2 迭代

---

硬性规则（与 Cursor Debug Mode 对齐）

---

API 速查

POST /debug 示例 body：

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

---

安装到 Claude Code

将本目录复制到个人或项目 skills 路径之一：

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

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

重启 Claude Code 后使用 /debug-mode。

debug-mode

在 Claude Code 里复刻 Cursor Debug Mode 的交互式调试流程：先列假设 → 在代码里插桩 → 你本地复现 → 读运行时日志验证 → 再修复，避免「凭感觉改代码」。

适用场景

• 接口返回正常但 UI / 状态不对
• 异步、竞态、闭包陈旧等难以从堆栈直接看出的问题
• 需要对比「某条代码路径有没有走到、变量当时是什么」

不太适合：明显的拼写错误、一眼能看懂的堆栈行号、改一行就能修好的 typo。

前置条件

• Claude Code（支持 Skills / 斜杠命令）
• 本机已安装 Node.js（用于跑日志收集服务，无额外 npm 依赖）

安装

任选一种方式，把本目录放到 Claude Code 的 skills 路径下即可：

# 全局：所有项目可用
cp -r skills/debug-mode ~/.claude/skills/debug-mode

# 仅当前仓库
mkdir -p .claude/skills
cp -r /path/to/corner-skills/skills/debug-mode .claude/skills/

安装后重启 Claude Code，在输入框输入 / 应能看到 `debug-mode`。

Skill 配置了 disable-model-invocation: true：只有你用 /debug-mode 进入，Claude 不会自动开启，避免普通对话里误插桩。

快速开始

1. 进入 Debug Mode

在 Claude Code 中输入：

/debug-mode 点击提交后列表不刷新，Network 里接口 200

也可以先 /debug-mode，再在后续消息里补充复现步骤。

2. 配合 Agent 完成一轮调试

Agent 会按阶段推进，你需要在中间手动复现 bug（和 Cursor 一样）：

3. 结束后

项目下可能产生（建议加入 .gitignore）：

.claude/debug.log          # NDJSON 运行时日志
.claude/debug-server.pid  # 日志服务进程信息
.claude/debug-server.out   # 服务 stdout（可选）

---

工作原理

本 skill 会在本机启动一个轻量 HTTP 服务，把前端/后端的调试信息汇总到同一个日志文件，供 Claude 读取分析。

flowchart LR
  subgraph local["本机"]
    S["debug-server :3847"]
    L[".claude/debug.log"]
  end
  subgraph code["你的项目 #region DEBUG"]
    FE["浏览器 fetch"]
    BE["后端 fetch / 写文件"]
  end
  FE -->|POST /debug| S
  BE --> S
  BE --> L
  S --> L
  CC["Claude Code"] -->|读日志| L

• 默认端口：3847（环境变量 DEBUG_SERVER_PORT 可改）
• 日志路径：{项目根}/.claude/debug.log
• 插桩约定：必须用 // #region DEBUG … // #endregion DEBUG 包裹，修复后一次性删掉
• 不要用 console.log / print 做调试输出（会污染终端，且与 Cursor 规则不一致）

各语言插桩示例见：references/instrumentation.md。

---

手动操作脚本（可选）

Agent 通常会代你执行；你也可以自己在项目根目录操作：

SKILL=~/.claude/skills/debug-mode/scripts   # 按实际安装路径修改
PROJECT=$(pwd)

# 启动日志服务
bash "$SKILL/start-server.sh" "$PROJECT" 3847

# 探活
curl http://127.0.0.1:3847/health

# 清空日志（每次复现前）
bash "$SKILL/clear-log.sh" "$PROJECT" 3847

# 停止服务
bash "$SKILL/stop-server.sh" "$PROJECT"

手动发一条测试日志

curl -X POST http://127.0.0.1:3847/debug \
  -H 'Content-Type: application/json' \
  -d '{"hypothesis":"H1","message":"smoke test","data":{"ok":true}}'

cat .claude/debug.log

HTTP API

POST /debug 常用字段：

---

目录说明

debug-mode/
├── README.md                 # 本文件（给人看）
├── SKILL.md                  # Agent 执行的完整流程（给 Claude 看）
├── scripts/
│   ├── debug-server.js       # 日志收集 API
│   ├── start-server.sh
│   ├── stop-server.sh
│   └── clear-log.sh
├── references/
│   └── instrumentation.md    # 前后端插桩代码片段
└── evals/
    └── evals.json            # skill 评测用例（可选）

---

常见问题

Q：`/debug-mode` 找不到？ 确认目录名为 debug-mode，且位于 ~/.claude/skills/ 或项目 .claude/skills/ 下，然后重启 Claude Code。

Q：浏览器插桩没有日志？ 先 curl http://127.0.0.1:3847/health 确认服务在跑；确认插桩 URL 端口与启动时一致（默认 3847）。

Q：日志文件在哪？ 一般在项目根目录 .claude/debug.log。远程或只读环境可改用 /tmp/.claude/debug.log（需在插桩里写死绝对路径）。

Q：和 Cursor IDE 内置 Debug Mode 的关系？ 流程与规则对齐（假设 → 插桩 → 复现 → 读日志 → 修复 → 清理）；本 skill 通过本地 HTTP + 统一日志文件在 Claude Code 中实现同样协作方式。

Q：调试完忘记停服务？

bash ~/.claude/skills/debug-mode/scripts/stop-server.sh "$(pwd)"

---

相关链接

• Claude Code Skills 文档：<https://code.claude.com/docs/en/skills>
• 更细的插桩示例：references/instrumentation.md

插桩参考（前后端）

默认日志 API：http://127.0.0.1:3847（可用 DEBUG_SERVER_PORT 改端口）

统一日志文件：{project_root}/.claude/debug.log（NDJSON，一行一条）

禁止 console.log / print / stdout 作为调试输出；一律走文件追加或 HTTP POST。

---

浏览器（React / Vue / 原生 JS）

在 #region DEBUG 内使用（DEBUG_PORT 与启动脚本一致）：

// #region DEBUG
const __DBG = (h, msg, data) =>
  fetch(`http://127.0.0.1:3847/debug`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      hypothesis: h,
      message: msg,
      data,
      location: "ComponentName.tsx:42",
    }),
  }).catch(() => {});
// #endregion DEBUG

调用示例：__DBG("H1", "after fetch", { items: list.length });

---

Node / Bun / Deno（服务端）

方式 A — HTTP（与浏览器相同，需 debug-server 已启动）

// #region DEBUG
fetch("http://127.0.0.1:3847/debug", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    hypothesis: "H2",
    message: "handler entry",
    data: { userId },
    location: "routes/user.ts:18",
  }),
}).catch(() => {});
// #endregion DEBUG

方式 B — 直接写日志文件（无需 HTTP，适合 CLI / 无浏览器环境）

LOG_PATH 必须是写死的绝对路径（从对话中的项目路径推断，禁止 process.cwd() / __dirname 动态解析）：

// #region DEBUG
import fs from "fs";
const LOG_PATH = "/ABS/PATH/TO/project/.claude/debug.log";
fs.appendFileSync(
  LOG_PATH,
  JSON.stringify({
    ts: new Date().toISOString(),
    hypothesis: "H2",
    message: "[DEBUG H2] handler entry",
    data: { userId },
    location: "routes/user.ts:18",
  }) + "\n"
);
// #endregion DEBUG

---

Python

# #region DEBUG
import json, urllib.request
def _dbg(h, msg, data=None, loc=""):
    urllib.request.urlopen(
        urllib.request.Request(
            "http://127.0.0.1:3847/debug",
            data=json.dumps({"hypothesis": h, "message": msg, "data": data, "location": loc}).encode(),
            headers={"Content-Type": "application/json"},
            method="POST",
        ),
        timeout=0.5,
    )
# #endregion DEBUG

或文件追加（绝对路径写死）：

# #region DEBUG
LOG_PATH = "/ABS/PATH/TO/project/.claude/debug.log"
with open(LOG_PATH, "a") as f:
    f.write(json.dumps({"hypothesis": "H1", "message": "[DEBUG H1] step", "data": x}) + "\n")
# #endregion DEBUG

---

Go

// #region DEBUG
func dbgLog(h, msg string, data any) {
    b, _ := json.Marshal(map[string]any{"hypothesis": h, "message": msg, "data": data})
    http.Post("http://127.0.0.1:3847/debug", "application/json", bytes.NewReader(b))
}
// #endregion DEBUG

---

Region 标记对照

日志消息格式：[DEBUG H1]、[DEBUG H2] … 与假设编号对应。