前言¶
调试是开发者绕不开的日常。Bug 出现时，人类工程师往往有一套习惯：先复现、再缩小范围、提出假设、用证据验证，最后做最小修复。可当你把问题交给 AI 编程助手时，常见画风却是——Agent 连续改好几处代码、加一堆防御性判断，问题有时碰巧好了，有时却引入新回归，你甚至说不清它到底查到了什么。
systematic-debugging 正是针对这一痛点：它来自社区精选仓库 awesome-cursor-skills，把「复现 → 隔离 → 假设 → 验证 → 修复」这套结构化调试流程写进 SKILL.md，教 Agent 按步骤排错，而不是随机改代码碰运气。对经常让 Cursor、Claude Code 等工具帮忙查 Bug 的开发者来说，值得一装。
这是什么¶
systematic-debugging 是一个 Agent Skill，维护者为 Spencer Pauly 的 awesome-cursor-skills 项目，归类在 Workflow（工作流）技能中。
它的 frontmatter 定义如下：
---
name: systematic-debugging
description: Structured debugging methodology — reproduce, isolate, hypothesize, verify. Covers git bisect, binary search, logging, and minimal reproduction.
user-invocable: true
---
一句话定位：用可复现的步骤约束 AI 的调试行为——先拿到稳定复现路径，再缩小故障范围，形成可检验的假设，用最小实验验证，最后做最小修复并回归测试。Skill 正文明确写了 「Debug methodically instead of randomly changing code」（有条理地调试，而不是随机改代码），这正是它与普通「帮我修 Bug」提示词的核心区别。
该 Skill 遵循通用的 SKILL.md 开放格式，可在 Cursor、Codex CLI、Claude Code 等支持 Agent Skills 的工具中使用；各工具的安装目录略有差异，下文会分别说明。
核心功能与亮点¶
五步调试流程¶
Skill 把调试拆成五个阶段，Agent 应按顺序推进，而不是跳步乱改：
1. Reproduce（复现）
在动手改代码之前，必须先稳定复现 Bug：
- 记录触发问题的精确步骤
- 明确「期望行为」与「实际行为」的差异
- 确认问题是否可稳定复现（而非偶发）
- 记录运行环境：操作系统、Node 版本、浏览器等
Skill 写得很直白：「If you can’t reproduce it, you can’t fix it.」——复现不了，就继续向用户追问细节，不要凭空猜测。
2. Isolate（隔离）
把故障范围一点点缩小，Skill 提供了三种常用手段：
二分搜索代码库：注释掉一半逻辑，看 Bug 是否仍在；根据结果继续在另一半里二分，直到定位到具体模块。
Git bisect：适合「以前能用、某次提交后坏了」的场景，官方给出了完整命令流程：
git bisect start
git bisect bad # 当前提交是坏的
git bisect good <sha> # 这个提交还是好的
# Git 检出中间版本 —— 测试它
git bisect good # 或 git bisect bad
# 重复直到找到第一个坏提交
git bisect reset # 完成后重置
按层隔离：从前端/后端、数据库、API、单个组件等维度逐层剥离——查 Network 面板、直接 curl 接口、单独渲染组件，判断问题落在哪一层。
3. Hypothesize（假设）
要求 Agent 形成具体、可检验的假设，而不是模糊结论。Skill 给了正反例：
- 差：「数据好像有问题」
- 好：「
userId为 null，因为 auth 中间件没有在这条路由上执行」
4. Test the Hypothesis（验证假设）
用最小实验证明或推翻假设：
- 在可疑位置加
console.log或断点 - 检查怀疑变量的实际值
- 假设错误则回到第 3 步；假设成立则找到根因
5. Fix and Verify（修复与验证）
- 做最小改动修复根因，而非掩盖症状
- 用原始复现步骤确认 Bug 已消失
- 检查是否引入回归
- 补写一条能捕获此类 Bug 的测试
场景化调试工具表¶
Skill 还整理了一张「场景 → 工具」对照表，帮助 Agent 快速选对手段：
| 场景 | 建议工具 |
|---|---|
| 「以前能用」 | git bisect |
| 「不知道这段代码在哪跑」 | 在可疑函数入口/出口加日志 |
| 「数据看起来不对」 | 逐步检查每个变换环节 |
| 「只在生产环境失败」 | 对比环境变量、查日志、用生产数据本地复现 |
| 「偶发失败」 | 排查竞态、时序、未初始化状态 |
| 「错误信息没用」 | 在代码库中搜索该错误的抛出位置 |
常见 Bug 模式清单¶
Skill 列举了 Agent 应优先留意的典型模式，包括：Off-by-one、Null/undefined、竞态条件、React stale closure、类型强制转换（== vs ===）、漏写 await、本地与 CI/生产环境不一致等。这不是玄学清单，而是把人类调试经验编码成检查项，减少 Agent 在常见坑上反复绕圈。
四条铁律¶
- Never guess — always verify with evidence（不猜测，用证据验证）
- Fix the root cause, not the symptom（修根因，不修表象）
- 15 分钟无进展就退一步重新隔离
- 记录已尝试的方案，避免重复失败路径
user-invocable: true 表示用户也可以在 Agent 对话里通过 /systematic-debugging 显式调用，强制 Agent 走这套流程。
安装与启用¶
awesome-cursor-skills 的 Skills 均为「复制即用」：SKILL.md 放进对应工具的 skills 目录即可，无需额外依赖或编译。
在 Cursor 中安装¶
方式一：手动复制（推荐，便于团队共享）
-
从官方仓库获取文件：
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/systematic-debugging -
在项目根目录创建目录并放入
SKILL.md：
mkdir -p .cursor/skills/systematic-debugging
# 将 SKILL.md 复制到 .cursor/skills/systematic-debugging/SKILL.md
- 重启 Cursor 或重新打开项目，Agent 会自动发现该 Skill。
根据 Cursor 官方 Skills 文档，Cursor 会从以下位置扫描 Skill：
| 位置 | 作用域 |
|---|---|
.cursor/skills/ |
项目级，可提交 Git 与团队共享 |
.agents/skills/ |
项目级，跨工具兼容 |
~/.cursor/skills/ |
用户级，所有项目可用 |
~/.agents/skills/ |
用户级，跨工具兼容 |
文件夹名建议与 frontmatter 中的 name 一致（小写、连字符），即 systematic-debugging。
方式二：从 GitHub 导入
Cursor 支持通过 Customize → Rules → Add Rule → Remote Rule (Github) 填写仓库地址导入；也可用内置 /migrate-to-skills 将旧规则迁移为 Skill 格式。
在 Claude Code / Codex CLI 中使用¶
这类工具同样识别 SKILL.md 通用格式。Claude Code 通常读取项目下的 .claude/skills/ 或 .agents/skills/；Codex CLI 读取 .codex/skills/ 等目录（Cursor 文档亦提到为兼容会扫描这些路径）。将 systematic-debugging 目录复制到对应工具的 skills 根目录即可，具体以各工具当前文档为准。
安装完成后，可在 Cursor Settings → Rules → Agent Decides 区域看到已加载的 Skill；描述字段会帮助 Agent 判断何时自动启用。
典型用法示例¶
自动触发¶
当你在 Agent 对话中描述 Bug，例如：
登录后跳转到个人页，用户名显示为空，但 Network 里接口返回的数据是对的。
Agent 会根据 description 中的 reproduce, isolate, hypothesize, verify 等关键词，自动匹配并加载 systematic-debugging，按五步流程推进：先让你确认复现步骤与环境，再建议查 Network、隔离前端渲染层、提出「props 未传递」类假设，并用最小 log 验证。
显式调用¶
若你希望强制走结构化流程，在 Agent 输入框输入：
/systematic-debugging
然后描述问题。user-invocable: true 保证该 Skill 可作为斜杠命令直接唤起，适合 Agent 此前「乱改一气」、你需要它重新按方法论来一遍的场景。
Git bisect 协作示例¶
假设你知道 v1.2.0 正常、当前 main 分支异常，可以让 Agent 在 systematic-debugging 指导下执行：
git bisect start
git bisect bad HEAD
git bisect good v1.2.0-tag
# 每一轮：运行测试或手动验证 → git bisect good/bad
git bisect reset
Skill 要求 Agent 在 bisect 过程中记录每次测试结果，最终 pinpoint 引入回归的提交，而不是直接在大范围 diff 里盲改。
与「最小复现」配合¶
隔离阶段，Skill 强调构造最小可复现用例——去掉无关依赖和分支，只保留触发 Bug 的必要代码。这对 AI 尤其重要：上下文越小，Agent 越不容易被无关文件干扰，假设也更容易验证。
适用场景与注意事项¶
适合谁、什么场景：
- 日常让 AI 帮忙查 Bug，但受够了「改十处碰运气」
- 回归问题、偶发问题、环境差异问题，需要 Agent 先复现再动手
- 团队希望把调试 SOP 写进仓库，新成员和 Agent 共用同一套流程
- 技术负责人想降低 AI 引入静默回归的风险
注意事项：
- Skill 是方法论，不是万能补丁。它教 Agent 怎么查，不替代你对业务逻辑的判断；复杂分布式系统可能还需结合链路追踪、APM 等工具。
- 复现成本高的 Bug（仅生产、极低概率）Skill 也会建议追问细节和环境对比，Agent 仍可能无法一次定位，需要人工配合提供日志与数据。
- 不要与「快速瞎改」混用。若同一会话里你又提示「别管了直接全改一遍」，可能冲淡 Skill 约束；显式
/systematic-debugging效果更好。 - 版本随仓库更新。awesome-cursor-skills 持续维护，建议定期
git pull或重新复制，以获取新增的 Bug 模式或工具建议。 - 团队规范可二次扩展。你可以在项目内 fork 该 Skill，加入团队特有的日志规范、测试命令或禁止操作（例如「未复现前禁止改生产配置」）。
小结¶
调试能力不会因为是 AI 在执行就可以省略方法论。systematic-debugging 把复现、隔离、假设、验证、最小修复这套工程师常识写进 SKILL.md，让 Agent 排错时有章可循，少做无效修改，多留可追溯证据。对于 AI 编程工具用户，这是一个轻量、零依赖、复制即用的 Workflow Skill，值得放进 .cursor/skills/ 试一轮。
官方 Skill 地址：
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/systematic-debugging
awesome-cursor-skills 项目主页：
https://github.com/spencerpauly/awesome-cursor-skills
