基于 Cline Skill 的系统化调试方法论：从复现到根因修复的可执行流程

本文聚焦 Cline 仓库中内置的 debugging 技能指令（位于 sdk/examples/plugins/agents-squad/skills/debugging.md）。这是一份面向 AI 编码助手的"可加载方法论"：当你让 Cline 排查一个 bug 时，它会把复现、隔离、诊断、修复、报告五个阶段的可执行规则注入会话上下文，让调试从"碰运气式的猜测"变成有据可循的系统流程。读完本文，你将掌握这套方法论的全部细节、其在 Agent Squad 插件中的实际加载机制，以及如何在自己团队的 Skills 体系中复刻与扩展它。

先理解这份文档在仓库中的角色

debugging.md 不是项目源码，而是一份 Skill 定义文件。Cline 的 Skill 机制（定制化文档见 docs/customization/skills.mdx）把"某个专业任务的详细指导"打包成带 YAML frontmatter 的 Markdown，按需加载，避免常驻上下文。

这份文件属于示例插件 Agent Squad（插件首页 sdk/examples/plugins/agents-squad/README.md）。它的 frontmatter 如下：

---
name: debugging
description: Systematic debugging — reproduce, isolate, diagnose, and fix bugs with root-cause analysis.
---

其中：

• name: debugging 是技能的标识符，供 list_skills / get_skill 按名查询；
• description 用于匹配触发：当用户请求与"复现、隔离、诊断、修复 bug、根因分析"相关时，Agent 会调用 get_skill("debugging") 加载正文指令；
• 正文即本技能的核心方法论——五个阶段的可执行清单。

从仓库结构（插件入口 sdk/examples/plugins/agents-squad/index.ts）看，Agent Squad 同目录下还有 code-review、test-generation、refactoring、api-design、migration、documentation 六个兄弟技能，debugging 与它们构成一套工程活动技能库，由 phantom/oracle/anvil/inquisitor 等子代理在运行时按需取用。

Skill 的加载机制：一条文件如何进入 Agent 上下文

要真正用好这份调试技能，需要理解它如何被读取。在 index.ts 中，readSkillDefinitions(baseCwd) 按优先级扫描三层目录并合并（同名时靠后来源覆盖靠前来源）：

层级	目录	说明
Bundled（随插件内置）	插件目录下的 skills/	本文件即位于此，与 index.ts 同级
Global（全局）	~/.cline/data/settings/skills/	由 CLINE_DATA_DIR 可覆盖的全局数据目录
Project（项目级）	<cwd>/.cline/skills/	跟随仓库提交、团队共享

解析逻辑（parseFrontmatter，见 index.ts）会剥离 UTF-8 BOM、用正则切出 --- 包裹的 YAML frontmatter，再交给 yaml 库解析；若 frontmatter 损坏则退化为"无元数据的纯 Markdown"。随后：

• list_skills 只返回 name + description + source（来源层级），供 Agent 检索可用能力；
• get_skill 把整份正文作为 instructions 返回，正文中的编号步骤会作为操作守则注入当前会话。

因此这份 debugging.md 的正文质量，直接决定了 Agent 排查 bug 时的行为规范程度——它本质上是一段被反复注入的系统提示（system prompt）片段。

阶段一：理解 Bug（Understand the Bug）

文档要求处理任何问题时先从信息收集开始，而不是立即动手改代码：

• 仔细阅读错误信息、堆栈追踪与日志：异常消息的首行、堆栈中第一个属于项目代码的帧，往往是最高价值线索；
• 复现问题：文档明确警告——"如果你无法复现，就无法验证修复"（If you can't reproduce it, you can't verify a fix）。一个无法复现的 bug 修复后你也无法确认它真的被修好；
• 区分预期行为与实际行为：明确"应当发生什么"与"实际发生了什么"的差异，差异点就是调查方向；
• 记录环境：操作系统、运行时版本、配置、输入数据。环境是后续"本地可跑、CI 挂了"类问题的关键变量。

这一阶段的产出是一个精确的"问题陈述"，它决定了后续隔离阶段是否具备可执行的最小抓手。

阶段二：隔离（Isolate）

隔离的目标是用**二分法（binary search）**不断收窄问题范围，文档给出从粗到细的四层追问：

1. 哪个文件？ 顺着堆栈追踪或数据流回到问题起源位置；
2. 哪个函数？ 在可疑函数的入口与出口加日志或断点，观察边界；
3. 哪一行？ 在可疑操作前后检查变量值；
4. 哪份输入？ 找出能触发 bug 的最小输入（minimal reproduction）。

常见隔离手段

• 注释掉代码块，找出真正触发问题的代码段；
• 插入带标签的临时 console.log / console.error，让输出可检索、可对照；
• 用调试器单步执行；
• 编写最小复现测试用例——把"偶然出现"变成"可稳定复现"。

在 Cline 的调试技能语境中，"编写最小复现测试"这一条与仓库中 inquisitor 代理（对抗性审查）以及 test-generation 技能互为表里：一个可运行的最小用例既是隔离工具，也是后续修复阶段的验证基准。

阶段三：诊断（Diagnose）

隔离找到"问题在哪"之后，诊断回答"为什么"。文档归纳了最常见的七类根因（Root Cause），值得作为排查时的对照清单：

根因类别	典型表现
类型不匹配	运行时值与预期类型不符：null、undefined、对象形状不对
状态被意外修改	共享状态被另一条代码路径悄悄改写
竞态条件	异步/并发代码中依赖时序的行为
差一错误（off-by-one）	循环边界、数组索引、字符串切片偏差
缺失错误处理	未处理的 Promise rejection、未捕获异常、或被吞掉的错误
过期引用	闭包捕获了会变化的变量，或缓存数据已过期
环境差异	本地正常但 CI/生产失败：配置、权限或版本差异

诊断的关键动作是文档强调的那句话：至少连续追问两次"Why did this happen?"（对着现象连续问两遍为什么），以穿透症状层抵达根因层。例如"数组越界"是第一层答案，继续追问"为什么数组长度比预期短"、"为什么写入方少算了一位"，才能定位到真正的逻辑缺陷而不是表象。

阶段四：修复（Fix）

修复阶段的方法论核心是测试先行（test-first），五步闭环：

1. 先写一个会因该 bug 而失败的测试（在修复之前写）；
2. 做最小改动，只修复根因，不顺手重构无关代码——这与 Agent Squad 中 anvil 代理"外科手术式实现、严格控制改动范围"（见 sdk/examples/plugins/agents-squad/agents/anvil.md）的行为准则完全一致；
3. 验证测试通过；
4. 检查代码库其他位置是否存在同一模式——同一种错误写法常常在多处出现；
5. 运行完整测试套件确认无回归。

"测试先失败、再通过"的顺序保证了测试确实命中了该 bug，而不是一个恒真的占位断言；最后两步则把修复从"点状修补"升级为"模式级根治"。

阶段五：报告（Report）

文档要求修复完成后记录以下内容，形成可追溯的调试档案：

• Bug 是什么（症状 + 根因）；
• 如何复现它；
• 修复内容以及为什么这样修是正确的；
• 代码库其他位置是否也存在同一模式；
• 新增了哪个测试来防止回归。

在 Agent Squad 的编排模型下，这一阶段与交接机制（handoff store）衔接自然：父代理可以把排查结论写入交接文件，供后续实现、审查代理接力使用（典型流程见 插件 README 的 Typical orchestration 示例）。一份结构化的调试报告，本身就是下一位协作者或下一次类似问题的"复用资产"。

如何把这份方法论用于自己的项目

debugging.md 的可借鉴之处在于：它把社区成熟但零散的调试经验，沉淀为可触发、可复用的结构化指令。参照本文件，你可以在自己的 Skills 体系中扩展：

1. 直接使用内置版本：加载 Agent Squad 插件（在 Cline SDK 配置中将 pluginPaths 指向插件目录），让任何代理通过 get_skill 获取该指令；
2. 项目级覆盖：在 <cwd>/.cline/skills/debugging.md 放置同名文件，即可用你团队特有的调试约定（如日志规范、必须运行 lint、特定框架的排查顺序）覆盖内置正文；
3. 定制专属调试技能：仿照本文的 frontmatter + 编号步骤结构，为特定技术栈（如 React 渲染问题、数据库慢查询）编写更细分的技能，注意用强触发词的 description（参考 Skills 写作指南 docs/customization/skills.mdx 中"description 决定何时被触发"的原则）。

小结

debugging 技能将"复现 → 隔离 → 诊断 → 修复 → 报告"串成一条有纪律的调试流水线：复现建立可信的验证基准，二分隔离把搜索空间从整个代码库缩小到一行，七类根因清单提供诊断启发式，测试先行保证修复可证，结构化报告沉淀可复用的经验。它既是 Cline Agent 在收到 debug 请求时的高质量行为准则，也是一份可以直接借鉴的、编写任何"方法论型 Skill"的样板——仓库中与它同级的 code-review.md、migration.md 等均采用了同构的"清单式指令"写法，值得放在一起研读。