mcpField
D
debug-systematic

debug-systematic

github.com/travisjneuman开发106146 次安装1 天前更新
代码仓库

关于 debug-systematic

debug-systematic 提供循证的系统化调试流程，面向需要定位和修复软件故障的开发者。流程分为复现、隔离、诊断、修复与验证，强调以证据查明根因。

主要功能

  1. 01四阶段调试流程
  2. 02记录复现步骤与环境
  3. 03二分法及 git bisect 定位
  4. 04以假设和证据诊断根因
  5. 05最小化修复与验证
  6. 06调试反模式清单

适用场景

  1. 01稳定复现间歇性故障
  2. 02缩小回归问题的代码范围
  3. 03用证据区分症状与根因
  4. 04验证修复并降低再次发生风险

安装

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

$npx skills add https://github.com/travisjneuman/.claude --skill debug-systematic

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

详细介绍

系统化调试协议

一种严谨、以证据为依据的调试方法，可避免猜测并确保找到根本原因。

4 阶段协议

阶段 1：复现（确认事实）

目标：在进行任何调查之前，制定可靠的复现步骤。

操作：

  1. 记录触发 Bug 的确切步骤
  2. 记录环境详情（操作系统、版本、配置、内存、网络）
  3. 确定发生频率：总是发生？偶尔发生？在特定条件下发生？
  4. 捕获准确的错误消息、堆栈跟踪和屏幕截图
  5. 在不同环境中测试，以隔离变量

关键问题：

  • 最近一次正常工作是什么时候？
  • 此后发生了什么变化？（代码、依赖项、配置、基础设施）
  • 是否只在特定环境中出现？
  • 是否与特定数据有关？
  • 是否与时序有关？

输出：清晰且能可靠触发问题的复现步骤。

阶段 2：隔离（缩小范围）

目标：将搜索范围从“整个代码库”缩小到“特定组件”。

技术：

二分查找：

  1. 确定两个状态：正常状态和故障状态
  2. 测试中间状态
  3. 对出现故障的一半递归执行
  4. 继续，直到找到引入变更

Git 二分查找（用于回归问题）：

git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# Git will checkout commits for testing
# After each test:
git bisect good  # or git bisect bad
# Continue until culprit found

排除代码：

  • 注释掉部分代码以隔离问题
  • 创建最小复现案例
  • 移除所有非必要内容

环境隔离：

  • 单独运行失败路径（最小复现；仅在用户要求编写测试时才编写单元测试）
  • 比较正常与故障环境
  • 使用全新安装以排除污染因素

输出：“Bug 位于[特定组件/函数/代码行范围]”

阶段 3：诊断（理解根本原因）

目标：准确了解 Bug 为什么会发生，而不只是知道它发生在哪里。

科学方法：

  1. 观察：究竟发生了什么？
  2. 提出假设：为什么可能会发生这种情况？
  3. 预测：如果假设正确，还有什么情况也应该成立？
  4. 测试：用证据验证预测
  5. 迭代：根据结果完善假设

日志策略：

// Add strategic logging at boundaries
console.log("[DEBUG] Function entry:", { input, state });
console.log("[DEBUG] After processing:", { result, sideEffects });
console.log("[DEBUG] Function exit:", { returnValue });

常见根本原因：

症状可能原因
本地正常，在 CI 中失败环境差异、时序、资源
间歇性故障竞态条件、不稳定的网络、资源争用
先正常运行，之后停止工作状态变更、内存泄漏、缓存污染
数据错误类型强制转换、编码、时区、精度
静默失败异常被吞掉、异步错误、缺少 await

输出：提供证据的根本原因清晰说明。

阶段 4：修复与验证（解决问题并防止复发）

目标：修复问题并防止回归。

修复流程：

  1. 实施最小修复 - 尽可能少做改动
  2. 检查类似模式 - 其他地方是否存在同样的 Bug？
  3. 检查修复的副作用 - 阅读其涉及的调用方、输入和错误路径
  4. 记录修复 - 说明问题为何发生，以及如何预防

仅在用户要求编写测试时，才编写能复现 Bug 的失败测试。

验证清单：

  • 审查确认已解决阶段 3 中找到的根本原因，而不只是处理症状
  • 修复已产生的输出（复现结果、执行成功的命令）能够验证修复有效
  • 修复在所有受影响的环境中均有效
  • 未引入新的警告或错误

预防措施：

  • 在边界处添加保护措施和验证
  • 改进错误消息，便于今后调试
  • 记录其他开发者需要注意的问题
  • 考虑架构变更能否防止类似 Bug

调试反模式

不要：

  • 猜测并抱有侥幸（随意修改）
  • 没有证据就断定问题所在
  • 相信注释和文档，而不看代码的实际行为
  • 用打印语句调试生产环境，之后却忘记移除
  • 只修复症状，而不解决根本原因
  • 一次进行多项修改

应该：

  • 用证据验证假设
  • 一次只改一项
  • 记录实际值，而不是预期值
  • 相信代码，而不是文档
  • 陷入困境时休息一下（换个思路会有帮助）

快速参考

1. REPRODUCE → Can I reliably trigger this?
2. ISOLATE   → Where exactly is it failing?
3. DIAGNOSE  → Why is it failing?
4. FIX       → How do I fix it permanently?

输出模板

## Bug Investigation: [Title]

### Reproduction

- Steps to reproduce
- Environment details
- Frequency

### Isolation

- Search method used
- Scope narrowed to

### Root Cause

- What's actually wrong
- Why it happens
- Evidence

### Fix

- Code changes made
- What review confirmed, and what it couldn't

### Prevention

- How to prevent similar bugs
- Documentation updates

评论

支持 Markdown