debug

输出风格（朴素用语，不使用破折号或连字符）

请用朴素、简单的语言编写此技能生成的所有内容，包括文件和消息。直接、友善地对读者使用“你”来称呼，就像对待同事一样。请把每个步骤都写成建议，让读者可以选择执行或跳过，切勿使用命令式语气。保留有实际含义的技术术语，并用朴素的语言解释每个术语。绝不使用破折号作为标点符号，也不使用连字符，包括 em dash、en dash 和带连字符的复合词。写作时使用“只读”，不要写“只读式”。请用简单的词语表达，或重写句子。其他技能会匹配的代码、文件路径、命令标志和取值应保留其中的连字符。使用短句、逗号或括号。清楚胜过巧妙。

此技能的作用

你的角色： 相信证据而非直觉的调查者。请把 Bug 当作一个需要证据证实的案件：按需复现，将问题缩小到最小的故障范围，并且每次只改动一处，让每个结果都有意义。在弄清楚问题为何出现之前，避免只修补表面现象（空值、崩溃）。无法解释的修复，说明你还没有真正找出 Bug。

这是一次有条理的根因调查，而不是猜测和试错。通过一个循环来找出 Bug：复现 → 定位 → 提出假设 → 验证假设 → 修复根因 → 验证。此技能会有条理地执行这个循环（一次只验证一个假设，并根据证据确认或排除），直到证实问题原因，然后实施最小修复。

这是单次运行中的内部调查循环，不是 /loop 技能（该技能会按时间间隔重复运行命令）。只有在需要随时间观察某件事时才使用 /loop，例如，在多次运行中轮询一个不稳定的测试。

询问与行动

会采取行动。 它会复现、调查并修复问题。只有在根据已有信息无法复现 Bug 时，才会询问，届时会询问准确的步骤、输入、环境，以及观察到的行为和预期行为。它不会征求调查许可。

产物归属

为根因编写最小代码修复。建议使用 /test 编写回归测试（如果在原处先写一个失败、再写一个通过的测试是最快的验证方式，也会这样做）。不会添加功能、重构无关代码或重写规范。如果 Bug 暴露出有问题的决策（而不只是编码错误），会明确指出，并建议使用 /architect，而不是掩盖问题。

---

可移植性（适用于任何操作系统和任何 Agent）

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

执行

步骤 0：记录症状

在改动代码前，准确确定以下内容：

• 观察到的行为（确切的错误、堆栈跟踪、错误输出或截图）。
• 预期行为。
• 复现方法：触发问题的步骤、输入和环境。

如果其中任何内容不明确，且你无法推断出来，请询问。无法复现的问题就无法调试。

步骤 1：可靠复现

找到一种确定性的复现方法（失败的测试、一条命令或一个请求），以便按需触发 Bug。如果问题偶尔才出现，请找出能让它稳定复现的因素（时序、顺序、数据、并发）。无法按需复现的 Bug，就无法证明已修复。如果确实无法复现，请添加检测信息以便捕获问题，并说明这一点，不要盲目“修复”。

步骤 2：定位

在提出假设之前，把故障范围缩小到最小：

• 对代码路径做二分定位：通过二分查找找出正常输入变成错误输出的位置（在中间位置添加日志或打印语句、设置断点，或注释代码）。
• 对历史记录做二分定位：如果问题是回归，使用 git bisect（或检查可疑文件中的 git log -p）来找到引入问题的改动。
• 读取实际值：在边界处检测输入和输出，不要凭假设判断它们的值。

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

针对根本原因提出一个具体、可证伪的假设，例如：“日期被解析为本地时间，因此截止时间受时区偏移影响。”要找根本原因，而不是症状：“这里的值为 null”是症状；为什么它为 null 才是原因。不要一次胡乱改动多个地方。

步骤 4：验证假设

设计能证实或推翻假设的最小实验（有针对性的日志、一条断言、一行代码改动或一个单元测试）。运行实验。

• 被推翻 → 根据学到的信息放弃该假设，返回步骤 2/3。不要保留没有帮助的改动。
• 得到证实 → 你已找到根本原因。继续。

重复步骤 3 到步骤 4，直到有证据证实某个假设。绝不要凭直觉直接修复；未经验证的修复会修补症状，却让 bug 继续存在。

步骤 5：从根本上修复

进行最小且有针对性的改动，解决已证实的原因。不要修补症状（比如限制 null 的取值），要修复原因（它为什么是 null）。避免扩大范围，不要顺带进行机会性重构。遵循项目约定（AGENTS.md、相邻代码）。

步骤 6：验证并防止复发

• 再次运行步骤 1 中的复现，确认问题现已解决。
• 运行相关测试套件，确认没有引入回归。
• 添加回归测试，确保没有该修复时测试会失败，有了修复后则会通过，防止此 bug 悄然复发；可以直接编写测试，也可以将测试规范交给 /test。
• 检查同类问题：相同的根本原因往往也会藏在其他地方（相同模式、相同错误假设）。用 grep 搜索，并记录或修复发现的问题。

可选：交由子 Agent 运行

对于不简单的排查，可以启动一个调查子 Agent，避免迭代使用工具占满主上下文：

• model：明确指定强大的模型，不要继承会话模型（Claude Code：sonnet）
• description: "Debug: <symptom>"
• 工具：Read、Bash、Grep、Glob、Edit、Write
• prompt：此循环 + 已捕获的症状 + 复现步骤 + 相关的 AGENTS.md（内联）。要求其提供带有证据的根本原因，而不只是说“已修复”。

报告

开头先说明根本原因和修复；复现步骤和证据是过程记录，不是标题（参见 docs/conventions.md）。模板：

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

**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)

如果原因是决策有误，而非编码错误，应在标题中先说明这一点；正确的修复可能是更新规范，而不是修改代码。