debug-mode

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debug Mode

You are in Debug Mode — a hypothesis-driven debugging workflow. Do NOT jump to fixes. Follow each phase in order.

你已进入Debug Mode——一种基于假设的调试工作流。请勿直接跳到修复步骤，请按顺序完成每个阶段。

Phase 1: Understand the Bug

Ask the user (if not already provided): expected vs actual behavior, reproduction steps, error messages.

Read the relevant source code. Understand the call chain and data flow.

如果用户尚未提供，询问以下信息：预期行为与实际行为的差异、复现步骤、错误信息。

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

Phase 2: Generate Hypotheses

Generate testable hypotheses as a numbered list:

Based on my analysis, here are my hypotheses:

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

Include both obvious and non-obvious causes (race conditions, off-by-one, stale closures, type coercion, etc.).

生成可测试的假设，并以编号列表形式呈现：

Based on my analysis, here are my hypotheses:

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

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

Phase 3: Instrument the Code

Log file

Write to {project_root}/.claude/debug.log
using an absolute path.

project_root
= hardcoded constant string inferred from context (file paths in the conversation). PROHIBITED:

import.meta.dir

__dirname

process.cwd()

Deno.cwd()

path.resolve()

or any runtime detection. Exception: remote/CI environments or non-writable local filesystem — use

/tmp/.claude/debug.log

instead.

Before each reproduction: create

.claude/

if needed, then clear the log.

Server-side: file-append API (

fs.appendFileSync

open("a")

, etc.). Browser-side:

fetch

POST to a debug API route. Must work in all environments (dev/release).

使用绝对路径写入**

{project_root}/.claude/debug.log

**。

project_root

**是根据对话中的文件路径推断出的硬编码常量字符串。禁止使用：

import.meta.dir

、

__dirname

、

process.cwd()

、

Deno.cwd()

、

path.resolve()

或任何运行时检测方法。例外情况：远程/CI环境或不可写入的本地文件系统——改用

/tmp/.claude/debug.log

。

每次复现前：若需要则创建

.claude/

目录，然后清空日志。

服务端：使用文件追加API（如

fs.appendFileSync

、

open("a")

等）。浏览器端：通过

fetch

POST请求到调试API路由。必须在所有环境中可用（开发/发布环境）。

Region markers

ALL instrumentation MUST be wrapped in region blocks for clean removal:

// #region DEBUG       (JS/TS/Java/C#/Go/Rust/C/C++)

所有插桩代码必须包裹在区域块中，以便后续清理：

// #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)

undefined

(HTML/Vue/Svelte)

-- #region DEBUG (Lua)

...instrumentation...

// #endregion DEBUG (matching closer)

undefined

Logging rules

NEVER use
console.log
、
print
or any stdout/stderr output. All debug output MUST go to
```
debug.log
```
— server-side via file-append, browser-side via
```
fetch
```
to a debug API endpoint.
Log messages include hypothesis number:
```
[DEBUG H1]
```
,
```
[DEBUG H2]
```
, etc.
Log variable states, execution paths, timing, decision points
Be minimal — only what's needed to confirm/rule out each hypothesis

After instrumenting, tell the user to reproduce the bug, then STOP and wait.

**禁止使用
```
console.log
```
、
```
print
```
或任何标准输出/标准错误输出。**所有调试输出必须写入
```
debug.log
```
——服务端通过文件追加，浏览器端通过
```
fetch
```
发送到调试API端点。
日志消息需包含假设编号：
```
[DEBUG H1]
```
、
```
[DEBUG H2]
```
等。
记录变量状态、执行路径、时间、决策点
保持简洁——仅记录确认/排除每个假设所需的内容

插桩完成后，告知用户复现bug，然后停止并等待。

Phase 4: Analyze Logs & Diagnose

When the user has reproduced:

Check log file size first (e.g.
```
wc -l
```
or
```
ls -lh
```
). If the log is large, use
```
tail
```
or
```
grep "[DEBUG H"
```
to extract only the relevant lines instead of reading the entire file — avoid flooding the context window.
Map logs to hypotheses — determine which are confirmed vs ruled out
Present diagnosis with evidence:

undefined

当用户完成复现后：

先检查日志文件大小（如使用
```
wc -l
```
或
```
ls -lh
```
命令）。如果日志很大，使用
```
tail
```
或
```
grep "[DEBUG H"
```
提取相关行，而非读取整个文件——避免上下文窗口溢出。
将日志与假设对应——确定哪些假设被确认，哪些被排除
结合证据呈现诊断结果：

undefined

Diagnosis

Root cause: [Explanation backed by log evidence]

Evidence:

[H1] Ruled out — [why]
[H2] Confirmed — [log evidence]


If inconclusive: new hypotheses → more instrumentation → clear log → ask user to reproduce again.

Root cause: [Explanation backed by log evidence]

Evidence:

[H1] Ruled out — [why]
[H2] Confirmed — [log evidence]


如果结论不明确：生成新假设→更多插桩→清空日志→请用户再次复现。

Phase 5: Generate a Fix

Write a fix. Keep debug instrumentation in place.

Clear

.claude/debug.log

, ask user to verify the fix works, then STOP and wait.

编写修复代码。保留调试插桩代码。

清空

.claude/debug.log

，请用户验证修复是否有效，然后停止并等待。

Phase 6: Verify & Clean Up

If fixed: Remove all

#region DEBUG

blocks and contents (use Grep to find them), delete

.claude/debug.log

, summarize.

If NOT fixed: Read new logs, ask what they observed, return to Phase 2, iterate.

**如果修复成功：**移除所有

#region DEBUG

块及其内容（使用Grep查找），删除

.claude/debug.log

，总结情况。

如果未修复：读取新日志，询问用户观察到的情况，回到Phase 2，迭代处理。

Rules

Never skip phases. Instrument and verify even if you think you know the answer.
Never remove instrumentation before user confirms the fix.
Never use
console.log
、
print
etc. All debug output goes to
```
.claude/debug.log
```
via file-append only.
Always clear the log before each reproduction.
Always wrap instrumentation in
#region DEBUG
blocks.
Always wait for the user after asking them to reproduce.

**切勿跳过任何阶段。**即使你认为知道答案，也要进行插桩和验证。
在用户确认修复成功前，切勿移除插桩代码。
**禁止使用
```
console.log
```
、
```
print
```
等。**所有调试输出仅通过文件追加写入
```
.claude/debug.log
```
。
每次复现前务必清空日志。
务必将插桩代码包裹在
#region DEBUG
块中。
在要求用户复现后，务必等待用户反馈。