Systematic debugging
四阶段根因分析:调查、模式分析、假设测试、修复。铁律:没有根因就没有修复。禁止猜测性修复和症状压制。触发短语:"调试"、"debug"、"排查"、"根因"。From its SKILL.md
npx -y skills add StringKe/ai-agents --skill systematic-debuggingAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 9 stars9 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
3.2 KB, as published. Nobody here has run it
/systematic-debugging — 系统化调试
用结构化的四阶段流程定位和修复问题的根因。拒绝猜测性修复和症状压制。
铁律
没有根因就没有修复。
如果你无法清晰说出"问题的原因是 X,因为 Y",就不要开始写修复代码。
四阶段流程
阶段 1:根因调查
目标:收集事实,理解问题的完整表现。
- 复现问题,记录确切的错误信息和行为
- 收集相关日志、堆栈跟踪、错误输出
- 确定问题首次出现的时间点(git log、git bisect)
- 圈定问题涉及的代码范围
# 有用的调查命令
git log --oneline -20 # 最近提交
git log --all --oneline -- path/to/file # 文件变更历史
git bisect start HEAD known-good-commit # 二分定位
产出:一份事实清单,不含任何推测。
详细的根因追踪方法见 references/root-cause-tracing.md。
阶段 2:模式分析
目标:从事实中识别模式,缩小怀疑范围。
分析方向:
- 问题是否与特定输入相关
- 问题是否具有时间模式(总是发生 / 偶尔发生 / 特定条件下发生)
- 问题是否与特定代码路径相关
- 是否有类似的已知问题
产出:2 到 3 个可能的根因假设,按可能性排序。
阶段 3:假设测试
目标:通过实验验证或排除每个假设。
对每个假设:
- 设计一个能证实或证伪它的实验
- 执行实验
- 记录结果
- 根据结果更新假设排序
# 实验方法示例
# 添加诊断日志
# 修改输入数据
# 隔离组件运行
# 对比正常和异常环境的差异
如果 3 个以上的修复尝试失败,停下来质疑架构层面的假设。参考 references/defense-in-depth.md。
产出:确认的根因,附带实验证据。
阶段 4:修复实现
目标:修复根因,不是掩盖症状。
- 编写测试复现问题(修复前测试应失败)
- 修复根因
- 确认测试通过
- 检查是否有其他位置存在相同问题(全局搜索相同模式)
- 运行完整测试套件确认无回归
修复守卫:
- 禁止通过降低日志级别来消除警告
- 禁止用 try/catch 吞掉异常
- 禁止用 @SuppressWarnings 忽略问题
- 禁止在不理解原因的情况下添加 sleep/retry
调试笔记
在调试过程中,维护一个调试笔记(可以在聊天中,不需要写入文件):
问题:[一句话描述]
事实:
- [事实 1]
- [事实 2]
假设:
1. [假设 1] — 状态:[待验证/已排除/已确认]
2. [假设 2] — 状态:[待验证/已排除/已确认]
实验记录:
- [实验 1]:[结果]
根因:[确认后填写]
参考资料
references/root-cause-tracing.md:详细的根因追踪方法论references/defense-in-depth.md:多层防御思维references/condition-based-waiting.md:基于条件的等待替代 sleep