mcpField
D
debugging-protocol

debugging-protocol

github.com/jwilger开发5138 次安装17 周前更新
代码仓库

关于 debugging-protocol

一套用于调试的 Agent 技能，要求先调查根因，再进行修复，并以四阶段流程验证结果。适用于希望减少盲目尝试、在多次假设失败后及时升级问题的软件开发者。

主要功能

  1. 01修复前收集错误与复现信息
  2. 02对照正常案例查找差异
  3. 03每次仅测试一个明确假设
  4. 04通过测试验证根因修复
  5. 05三次失败后停止修复并升级

适用场景

  1. 01调查可复现的软件错误
  2. 02避免未经验证的症状修补
  3. 03在多种修复假设失败后重新审视问题
  4. 04在 TDD 流程中分析意外测试失败

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jwilger/agent-skills --skill debugging-protocol

安装后在 Claude Code 中输入/debugging-protocol确认已加载。

详细介绍

调试协议

价值观： 反馈——系统性调查带来理解。 理解才能带来正确的修复。正确的修复能够防止问题再次发生。 跳过调查会导致只修复症状，从而掩盖错误。

目的

传授严谨的 4 阶段调试流程，要求在尝试修复前先分析根本原因。避免最常见的调试失败模式：不了解问题为何存在就贸然修复。

实践

铁律：未经调查，不得修复

在完成根本原因调查之前，绝不要为了修复 Bug 而更改代码。看到错误后立刻知道该如何修复时，恰恰是你最可能出错的时候。先调查。

应该做：

  • 先完整阅读错误消息和堆栈跟踪，再做其他事
  • 调查前先稳定复现 Bug
  • 弄清楚某处为何出错，而不只是哪里出错

不应该做：

  • 看到空指针错误就添加空值检查（只修复症状）
  • 随便“试几种方法”，看看哪种有效（随机调试）
  • 因为“这个问题很简单”就跳过调查
阶段 1：了解故障

收集事实，暂时不要解读。

  1. 阅读完整的错误消息——每一行都要读，而不只是第一行
  2. 确定发生故障的确切文件和行号
  3. 稳定复现故障（如果无法复现，这也是重要信息）
  4. 检查近期更改：git log --oneline -10 和 git diff
  5. 梳理数据流：错误值来自哪里？

输出： 清楚说明发生了什么、发生在哪里，以及从何时开始。

阶段 2：寻找正常工作的示例

对比故障代码与正常工作的代码。差异就是 Bug 所在。

  1. 找到功能类似且正常工作的代码
  2. 对比设置、输入、状态和配置
  3. 找出正常工作和发生故障的情况之间的差异
  4. 检查依赖项：是否更新了库？环境是否发生变化？

输出： 正常工作和发生故障的情况之间的具体差异。

阶段 3：验证一个假设

提出一个明确、单一的假设。只做一处更改来验证它，并从结果中学习。

  1. 陈述假设：“我认为这个 Bug 是由 [X] 导致的，因为有 [证据]”
  2. 做一处更改来验证
  3. 观察结果
  4. 如果假设不成立，彻底撤销更改
  5. 根据学到的信息提出新假设

不要一次更改多处内容。如果同时更改导入、类型和逻辑，你就无法判断哪项更改起了作用。

输出： 有证据支持的已证实或已否定的假设。

阶段 4：修复并验证

由于你已了解根本原因，因此可以有把握地修复。

  1. 编写一个能够复现 Bug 的失败测试（如果尚不存在）
  2. 实施修复，针对阶段 3 中确定的根本原因
  3. 验证：新测试通过，所有现有测试也仍然通过
  4. 确认修复的是根本原因，而不是症状

输出： 有测试支撑的修复，且所有测试均通过。

升级处理：三次失败规则

如果三次修复尝试都失败，就停止。问题并非你以为的那样。

第三次失败后：

  1. 完全停止尝试修复
  2. 记录尝试过的内容，以及每次尝试失败的原因
  3. 质疑自己的假设：抽象是否有误？领域模型是否有误？问题本身是否完全判断错了？
  4. 寻求更全面的视角——架构评审、领域专家，或升级给用户处理

三次修复失败几乎总是意味着设计存在问题，而不是代码存在问题。继续修改代码无济于事。

示例：

Attempt 1: Add caching (hypothesis: slow queries) -> Still slow
Attempt 2: Add index (hypothesis: missing index) -> Still slow
Attempt 3: Eager loading (hypothesis: N+1) -> Still slow
STOP. Profile the system.
Result: 90% of time in external API call. Not a database problem at all.

执行说明

  • 独立模式：建议性。铁律依靠自行遵守。
  • 流水线模式：门控要求。通过 TDD 门禁之前，必须提供调试证据。

硬性约束：

  • 铁律（先调查，再修复）：[H]
  • 三次失败升级规则：[RP]

约束

  • 铁律：想跳过调查的冲动，在修复看起来显而易见时最强烈。而这恰恰是调查最有价值的时候——因为错误的“显而易见”修复所浪费的时间，比调查本身耗费的时间更多。如果你在思考为什么这个问题是那个不需要调查的例外，那你就违反了铁律。
  • 三振出局：三种假设都失败后，问题就不是你认为的那样。所谓“停下”，是指停止修复并回到调查，而不是彻底停止工作。重新审视你的假设，扩大调查范围，并查看相关系统。如果仍然找不到根本原因，就升级处理。
  • 撤销失败的假设：“彻底撤销”意味着代码库恢复到测试该假设之前的确切状态。不是“基本撤销，只保留了一些改进”，也不是“主文件里撤销了，但留下了调试日志”。失败假设引起的所有更改都必须还原。

验证

使用此技能进行调试后，请验证：

  • 在进行任何代码更改前，已完成第 1 阶段调查
  • 已阅读完整的错误消息（而不只是第一行）
  • 已稳定复现该错误
  • 已找到可用于对比的有效示例
  • 每次尝试修复前，都明确陈述了一个假设
  • 每次假设验证只做了一项更改
  • 尝试新假设前，已撤销失败的假设
  • 实施修复前，已编写或确认存在一个失败测试
  • 修复后，已验证所有测试均通过
  • 未在升级处理前超过三次修复尝试

如果有任何一项未达成，请重新检查相关阶段。

依赖项

此技能可独立运行，无必需依赖项。它与以下内容集成：

  • tdd： 在 TDD 过程中测试意外失败时，此技能会指导你先调查，再修改代码
  • user-input-protocol： 调试遇到模糊的决策点时，应暂停并询问用户，而不是猜测
  • domain-modeling： 如果三次修复都失败，根本原因可能是领域建模问题——请升级至领域审查

缺少依赖项？请使用以下命令安装：

npx skills add jwilger/agent-skills --skill tdd

评论

支持 Markdown