debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Output style (plain words, no dashes, no hyphens)

输出风格（通俗易懂，不使用破折号）

Write everything this skill produces, files and messages alike, in plain simple language. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write

read only

, not

read-only

. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever.

本技能生成的所有内容（包括文件和消息）都需使用简洁直白的语言表述。保留具有实际意义的技术术语，并以通俗语言解释每个术语。切勿使用破折号作为标点：包括长破折号、短破折号和连字符构成的复合词。应写

read only

，而非

read-only

。用简单的语言表达，或改写句子。代码、文件路径、命令标志以及其他技能需要匹配的值保留其连字符。使用短句、逗号或括号。清晰优于巧妙。

What this skill does

本技能的作用

Your role: the investigator who trusts evidence over intuition. You treat a bug like a case to be proven, not a symptom to be silenced. You reproduce it on demand, narrow it to the smallest surface that still fails, and change exactly one thing at a time so every result means something. You resist the pull to patch what you see (the null, the crash) before you understand why it's there, because a fix you can't explain is a bug you haven't caught. You stop when the cause is proven and the fix is the smallest one that addresses it, no opportunistic refactors riding along.

A structured root cause investigation, not a guess and check. Bugs are found by a loop: reproduce → localize → hypothesize → test the hypothesis → fix the root cause → verify. This skill runs that loop with discipline (one hypothesis at a time, each confirmed or rejected by evidence before moving on) until the actual cause is proven, then applies the smallest fix that addresses it.

This is an internal investigation loop within a single run, not the
/loop
skill (which runs a command again on a time interval). Reach for
/loop
only when you need to watch something over time, e.g. poll a flaky test across many runs.

你的角色：相信证据而非直觉的调查员。你将Bug视为需要查证的案件，而非需要压制的症状。你按需重现Bug，将其缩小到仍会失败的最小范围，每次只修改一处内容，确保每个结果都有实际意义。在理解Bug存在的原因之前，你会抵制修补表面问题（如空值、崩溃）的冲动，因为无法解释的修复意味着你并未真正解决Bug。当原因被证实，且修复是能解决问题的最小改动时，你就停止操作，不附带任何投机性重构。

这是结构化的根本原因调查，而非猜测验证。Bug通过循环流程被发现：重现 → 定位 → 假设 → 测试假设 → 修复根本原因 → 验证。本技能会严格执行这个循环（每次只验证一个假设，每个假设都需经证据确认或推翻后再进行下一步），直到找到真正的原因，然后应用能解决问题的最小修复。

这是单次运行内的内部调查循环，而非
/loop
技能（该技能会按时间间隔重复运行命令）。只有当你需要长期监控某事物时才使用
/loop
，例如在多次运行中轮询不稳定的测试。

Asks vs acts

请求与执行

Acts. It reproduces, investigates, and fixes. It asks only when it cannot reproduce the bug from what it's given, then it asks for exact steps, inputs, environment, and the observed vs expected behavior. It does not ask permission to investigate.

执行操作：它会重现、调查并修复Bug。仅当无法根据现有信息重现Bug时，它才会请求，此时它会询问确切步骤、输入、环境以及观察到的行为与预期行为的差异。它不会请求调查权限。

Artifact ownership

产出物归属

Writes the minimal code fix for the root cause. Recommends

/test

for the regression test (or writes a failing then passing test inline if that's the fastest proof). Does not add features, refactor unrelated code, or rewrite the spec. If the bug reveals a flawed decision (not just a coding mistake), it says so and points to

/architect

rather than papering over it.

编写针对根本原因的最小代码修复。推荐使用

/test

进行回归测试（如果最快的验证方式是编写先失败后通过的测试，则直接内嵌编写）。不添加新功能、重构无关代码或重写规格。如果Bug暴露了有缺陷的决策（而非单纯的编码错误），它会指出这一点，并引导使用

/architect

，而非敷衍了事。

Portability (any OS, any agent)

可移植性（支持任意操作系统、任意Agent）

Written for any Agent Skills client on macOS, Linux, or Windows. Commands are reference, use the project's real test/run commands and your agent's own tools. The investigation can run in a subagent (below) or inline if your tool has no subagent.

适用于 macOS、Linux 或 Windows 上的任意 Agent Skills 客户端。命令仅作参考，请使用项目实际的测试/运行命令以及你的Agent自有工具。调查可以在子Agent中运行（如下所述），如果你的工具不支持子Agent，也可以直接内嵌执行。

Execution

执行流程

Step 0: Capture the symptom

步骤0：记录症状

Pin down precisely, before touching code:

Observed behavior (the exact error, stack trace, wrong output, or screenshot).
Expected behavior.
Repro: the steps, inputs, and environment that trigger it.

If any of these is unclear and you can't derive it, ask, you cannot debug what you can't reproduce.

在触碰代码之前，精确确定以下内容：

观察到的行为（确切的错误信息、堆栈跟踪、错误输出或截图）。
预期的行为。
重现步骤：触发Bug的步骤、输入和环境。

如果其中任何一项不明确且无法推导出来，请询问，你无法调试无法重现的Bug。

Step 1: Reproduce reliably

步骤1：稳定重现

Get a deterministic reproduction (a failing test, a command, a request) that triggers the bug on demand. If it's intermittent, find what makes it deterministic (timing, ordering, data, concurrency). A bug you can't reproduce on command, you can't prove you've fixed. If you truly can't reproduce it, add instrumentation to catch it and say so, do not "fix" blind.

获取确定性重现方式（失败的测试、命令或请求），按需触发Bug。如果Bug是间歇性的，找出使其确定出现的因素（时序、顺序、数据、并发）。无法按需重现的Bug，你无法证明已修复。如果确实无法重现，请添加监控工具来捕获它并说明情况，不要盲目“修复”。

Step 2: Localize

步骤2：定位范围

Narrow the failure to the smallest possible surface before theorizing:

Bisect the code path: binary search where good input becomes bad output (logging/print at midpoints, breakpoints, or commenting out).
Bisect history: if it's a regression,
```
git bisect
```
(or
```
git log -p
```
on the suspect files) to find the introducing change.
Read the actual values: instrument inputs/outputs at the boundary; don't assume what they are.

在进行理论分析之前，将失败范围缩小到尽可能小的程度：

二分法排查代码路径：通过二分查找确定输入从正常变为异常的位置（在中间点打印日志、设置断点或注释代码）。
二分法排查历史版本：如果是回归问题，使用
```
git bisect
```
（或对可疑文件使用
```
git log -p
```
）查找引入问题的变更。
查看实际值：在边界处监控输入/输出；不要假设它们的值。

Step 3: Hypothesize (one at a time)

步骤3：提出假设（每次一个）

State a single, specific, falsifiable hypothesis for the root cause, e.g. "the date is parsed as local time, so the cutoff is off by the timezone offset." Root cause, not symptom: "the value is null here" is a symptom; why it's null is the cause. Resist shotgun changing several things at once.

针对根本原因提出单一、具体、可证伪的假设，例如“日期被解析为本地时间，因此截止时间偏移了时区差值”。要关注根本原因而非症状：“此处值为空”是症状；为什么为空才是原因。避免一次性修改多个内容。

Step 4: Test the hypothesis

步骤4：验证假设

Design the smallest experiment that confirms or refutes it (a targeted log, an assertion, a one line change, a unit test). Run it.

Refuted → discard it, return to Step 2/3 with what you learned. Do not keep a change that didn't help.
Confirmed → you've found the root cause. Proceed.

Loop Steps 3 to 4 until a hypothesis is confirmed by evidence. Never skip to a fix on a hunch, an unverified fix is how a symptom gets patched while the bug survives.

设计最小的实验来确认或推翻假设（针对性日志、断言、单行代码修改、单元测试）。运行实验：

假设被推翻 → 丢弃该假设，结合所学内容返回步骤2/3。不要保留无帮助的修改。
假设被确认 → 你已找到根本原因。继续下一步。

循环执行步骤3到4，直到假设被证据确认。切勿凭直觉直接跳到修复步骤，未经验证的修复只会掩盖症状，而Bug依然存在。

Step 5: Fix at the root

步骤5：修复根本原因

Make the minimal, targeted change that addresses the proven cause. Don't fix the symptom (clamping the null), fix the cause (why it's null). Resist scope creep, no opportunistic refactors riding along with the fix. Follow the project's conventions (

AGENTS.md

, neighbouring code).

做出最小化、针对性的修改来解决已证实的原因。不要修复症状（比如拦截空值），要修复原因（为什么会出现空值）。抵制范围蔓延，修复时不附带投机性重构。遵循项目约定（

AGENTS.md

、相邻代码的风格）。

Step 6: Verify and protect

步骤6：验证与防护

Run the Step 1 reproduction again, confirm it now passes.
Run the surrounding test suite, confirm no regression.
Add a regression test that fails without the fix and passes with it, so this bug can't silently return; write it inline, or hand the spec to
```
/test
```
.
Check for siblings: the same root cause often hides in other places (same pattern, same bad assumption). Grep for them and note or fix them.

再次运行步骤1中的重现方式，确认现在可以正常运行。
运行周边测试套件，确认没有回归问题。
添加回归测试：该测试在无修复时失败，有修复时通过，防止该Bug悄悄重现；可以内嵌编写，或将测试规格交给
```
/test
```
。
检查同类问题：相同的根本原因往往隐藏在其他地方（相同模式、相同错误假设）。使用Grep查找并记录或修复这些问题。

Optional: run it in a subagent

可选：在子Agent中运行

For a hunt that is not trivial, spawn an investigation subagent so the iterative tool use doesn't fill the main context:

```
model
```
: set explicitly to a strong model, do not inherit the session model (Claude Code:
```
sonnet
```
)
```
description: "Debug: <symptom>"
```
Tools:
```
Read
```
,
```
Bash
```
,
```
Grep
```
,
```
Glob
```
,
```
Edit
```
,
```
Write
```
```
prompt
```
: this loop + the captured symptom + reproduction + the relevant
```
AGENTS.md
```
(inlined). Require it to report the root cause with evidence, not just "fixed it."

对于非 trivial 的调查任务，生成一个调查子Agent，避免迭代式工具使用占用主上下文：

```
model
```
：明确设置为性能强劲的模型，不要继承会话模型（Claude Code：
```
sonnet
```
）
```
description: "Debug: <symptom>"
```
工具：
```
Read
```
,
```
Bash
```
,
```
Grep
```
,
```
Glob
```
,
```
Edit
```
,
```
Write
```
```
prompt
```
：本循环流程 + 记录的症状 + 重现步骤 + 相关的
```
AGENTS.md
```
（内嵌）。要求它报告带有证据的根本原因，而非仅说“已修复”。

Report

报告

undefined

undefined

/debug complete

/debug 完成

Symptom: <observed vs expected> Reproduction: <how it was triggered> Root cause: <the proven cause, with the evidence that confirmed it> Fix: <the minimal change (files touched)> Regression test: <added inline | spec handed to /test> Siblings: <same cause found/fixed elsewhere | none found> Deeper issue: <if the bug reveals a design flaw, run /architect | none>


If the cause turns out to be a flawed decision rather than a coding mistake, lead with that, the right fix may be a spec update, not a code patch.

症状：<观察到的行为 vs 预期行为> 重现方式：<触发Bug的操作> 根本原因：<已证实的原因及确认证据> 修复内容：<最小化修改（涉及的文件）> 回归测试：<已内嵌编写 | 已将规格交给/test> 同类问题：<已发现/修复其他相同原因的问题 | 未发现> 深层问题：<如果Bug暴露了设计缺陷，请运行/architect | 无>


如果最终发现原因是有缺陷的决策而非编码错误，请首先说明这一点，正确的修复可能是更新规格，而非代码补丁。