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. Talk to the reader as

you

, warm and direct like a colleague, and present every step as a recommendation they may run or skip, never an order. 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. Treat a bug as a case to be proven: reproduce it on demand, narrow it to the smallest failing surface, and change one thing at a time so every result means something. Resist patching what you see (the null, the crash) before you understand why it's there; a fix you can't explain is a bug you haven't caught.

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) until the cause is proven, then applies the smallest fix.

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：复现 → 定位 → 假设 → 验证假设 → 修复根本原因 → 验证。此技能会严格执行这个循环（一次只验证一个假设，每个假设都由证据确认或推翻），直到找到已证实的原因，然后应用最小化修复。

这是单次运行内的内部调查循环，而非
/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的步骤、输入和环境。

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

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
```
。
检查同类问题：相同的根本原因往往隐藏在其他地方（相同模式、相同错误假设）。搜索这些位置并记录或修复它们。

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

报告

Lead with the root cause and the fix; the reproduction and evidence are the trail, not the headline (per

docs/conventions.md

). Template:

undefined

先说明根本原因和修复方案；复现过程和证据是辅助信息，而非核心内容（遵循

docs/conventions.md

）。模板：

undefined

/debug complete Â· <the bug, one line>

/debug 完成 · <bug简述，一行>

Root cause: <the proven cause>. Fixed by <the minimal change, files touched>. Next: /test <feature> (lock in the regression test, added inline or handed over) Heads up: <same cause also at <where>, fixed too · or a design flaw → /architect <what>> (omit if none)


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

根本原因：<已证实的原因>。修复方式：<最小化变更，涉及文件>。 下一步：/test <功能> （锁定回归测试，已内嵌编写或交付）注意：<相同原因还存在于<位置>，已修复 · 或存在设计缺陷 → /architect <问题>> （无相关情况则省略）


如果问题根源是有缺陷的决策而非编码错误，在标题中优先说明，正确的修复可能是更新规格，而非代码补丁。",