mcpField
D
debug-mode

debug-mode

github.com/doraemonkeys开发11982 次安装5 天前更新
代码仓库

关于 debug-mode

debug-mode 是面向编码 Agent 的假设驱动调试技能，涵盖理解问题、检验原因、记录证据、诊断、验证修复和清理。

主要功能

  1. 01六阶段调试流程
  2. 02生成可检验假设
  3. 03将调试信息写入文件
  4. 04用区域标记包裹埋点
  5. 05依据证据诊断并验证

适用场景

  1. 01调查原因不明的故障
  2. 02收集间歇性故障证据
  3. 03清理埋点前验证修复

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/doraemonkeys/claude-code-debug-mode --skill debug-mode

安装后在 Claude Code 中输入/debug-mode确认已加载。

详细介绍

调试模式

你正处于调试模式——一种以假设为导向的调试工作流。不要贸然修复。请按顺序完成各个阶段。

阶段 1：了解 Bug

如果用户尚未提供，请询问：预期行为与实际行为、复现步骤、错误消息。

阅读相关源代码。了解调用链和数据流。

阶段 2：提出假设

以编号列表的形式提出可测试的假设：

Based on my analysis, here are my hypotheses:

1. **[Title]** — [What might be wrong and why]
2. **[Title]** — [Explanation]
3. **[Title]** — [Explanation]

同时涵盖明显和不明显的原因（竞态条件、差一错误、过期闭包、类型强制转换等）。

手动复现会让用户感到疲惫，尤其是经过 3 轮或更多轮仍未找到根本原因时。请预先提供足够详细且合理的调试信息，以尽量减少复现轮次。

阶段 3：添加代码埋点

日志文件与证据收集

默认使用绝对路径写入 {project_root}/.agents/debug.log。

project_root = 根据上下文（对话中的文件路径）推断出的硬编码常量字符串。禁止使用：import.meta.dir、__dirname、process.cwd()、Deno.cwd()、path.resolve() 或任何运行时检测。例外：远程／CI 环境或本地文件系统不可写时，改用 /tmp/.agents/debug.log。

每次复现前：如有需要，创建 .agents/。如果 .agents/debug.log 已存在且非空，先归档（重命名为 debug-1.log、debug-2.log 等，按顺序递增），再将 debug.log 清空，以保留历史日志。

服务端：使用文件追加 API（fs.appendFileSync、open("a") 等）。浏览器端：使用 fetch 向调试 API 路由发送 POST 请求。必须在所有环境中都能运行（开发／发布环境）。

适配非标准环境和间歇性 Bug（重视证据，而非形式）：

  • **受限／远程／移动运行环境：**如果代码运行在无法写入项目根目录的移动、嵌入式或远程环境中，请调整日志目标位置（例如设备存储、远程端点或内存缓冲区），并请用户提供／粘贴日志。
  • **间歇性 Bug：**如果无法立即触发 Bug，请保留代码埋点，待问题再次发生时让用户提供日志。
区域标记

所有代码埋点都必须用区域块包裹，以便干净地移除：

// #region DEBUG       (JS/TS/Java/C#/Go/Rust/C/C++)
# #region DEBUG        (Python/Ruby/Shell/YAML)
 (HTML/Vue/Svelte)
-- #region DEBUG       (Lua)

...instrumentation...

// #endregion DEBUG    (matching closer)
日志规则
  • 绝不使用 console.log、print 或任何标准输出／错误输出。所有调试输出都必须写入 debug.log——服务端通过文件追加写入，浏览器端通过 fetch 发送到调试 API 端点。
  • 日志消息中包含假设编号：[DEBUG H1]、[DEBUG H2] 等。
  • 记录变量状态、执行路径、时间信息和决策点。
  • 保持精简——只记录确认或排除各项假设所需的信息。

添加代码埋点后，如果运行环境允许，请自行复现 Bug（运行失败的命令、测试或端点）。只有无法复现时，才告诉用户如何复现，然后停止并等待。

阶段 4：分析日志并诊断

当 Bug 已经复现（由你或用户复现）后：

  1. 先检查日志文件大小（例如运行 wc -l 或 ls -lh）。如果日志较大，请使用 tail 或 grep "[DEBUG H" 提取相关行，而不要读取整个文件——避免挤占上下文窗口。
  2. 将日志与假设对应起来——判断哪些假设已确认，哪些已排除。
  3. 提供带有证据的诊断：
## Diagnosis

**Root cause**: [Explanation backed by log evidence]

Evidence:
- [H1] Ruled out — [why]
- [H2] Confirmed — [log evidence]

如果结论不明确：提出新假设 → 添加更多代码埋点 → 归档并清空日志 → 再次自行复现；只有在无法复现时才询问用户。

阶段 5：生成修复方案

编写修复方案。保留调试代码埋点。

归档并清空 .agents/debug.log，然后再次自行复现，以验证修复。如果无法自行复现，请用户验证，然后停止并等待。

阶段 6：验证并清理

如果已修复： 移除所有 #region DEBUG 块及其内容（使用 Grep 查找），删除所有 .agents/debug*.log 文件（包括归档日志），并进行总结。

如果尚未修复： 阅读新日志；只有在用户亲自复现问题时，才询问用户观察到了什么。返回阶段 2并继续迭代。

规则

  • 绝不跳过任何阶段。 即使你认为自己知道答案，也要进行插桩和验证。
  • 在确认修复有效之前，绝不移除插桩（由你验证，或在你无法自行复现时由用户验证）。
  • 绝不使用 console.log、print 等。 将所有调试输出写入 {project_root}/.agents/debug.log（如果运行时限制有要求，可调整传输方式）。
  • 每次复现之前，始终先归档现有日志并重置 debug.log。
  • 始终将插桩代码包裹在 #region DEBUG 块中。

评论

支持 Markdown