mcpField
R
root-cause-tracing

root-cause-tracing

github.com/bobmatnyc开发78377 次安装15 周前更新
代码仓库

关于 root-cause-tracing

面向开发者的调试技能，适用于错误出现在调用链深处的情况。它引导逐层回溯以找到最初触发点，并在源头修复后补充各层校验。

主要功能

  1. 01沿调用链向上追踪
  2. 02识别最初触发点
  3. 03从源头修复问题
  4. 04增加分层校验

适用场景

  1. 01调查执行深处出现的错误
  2. 02查找无效数据的来源
  3. 03追踪触发故障的测试

安装

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

$npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill root-cause-tracing

安装后在 Claude Code 中输入/root-cause-tracing确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

metadata.json
references/
advanced-techniques.md
examples.md
integration.md
tracing-techniques.md

详细介绍

根因追踪

概述

Bug 往往会在调用栈深处显现（在错误的目录中执行 git init、在错误的位置创建文件、使用错误的路径打开数据库）。你的直觉可能会让你在错误出现的位置修复问题，但这只是在处理症状。

核心原则： 沿调用链反向追踪，直到找到最初的触发点，然后从源头修复。

这项技能是系统化调试工作流中的一种专门技术，通常用于第 1 阶段（根因调查），处理调用栈较深的问题时。

何时使用此技能

在以下情况使用根因追踪：

  • 错误发生在执行过程深处（而不是入口点）
  • 堆栈跟踪显示调用链很长
  • 不清楚无效数据的来源
  • 需要找出触发问题的测试或代码
  • 症状出现在距离实际原因很远的地方

与系统化调试的关系：

  • 系统化调试：整体框架（第 1–4 阶段）
  • 根因追踪：用于第 1 阶段调查的一项具体技术
  • 在系统化调试的第 1 阶段中使用根因追踪

铁律

NEVER FIX JUST WHERE THE ERROR APPEARS
ALWAYS TRACE BACK TO FIND THE ORIGINAL TRIGGER

修复症状会造成临时应付式解决方案，掩盖根本问题。

核心原则

  1. 反向追踪：从症状沿调用链追溯到源头
  2. 找到最初的触发点：确定错误数据或状态最初从何而来
  3. 从源头修复：解决根因，而非症状
  4. 纵深防御：修复源头后，在每一层添加验证

快速入门

5 步追踪流程
  1. 观察症状：错误消息是什么？哪个操作失败了？
  2. 找到直接原因：哪段代码直接导致了这个错误？
  3. 追问是谁调用了它：沿堆栈跟踪向上追溯一层
  4. 继续向上追踪：持续追溯，直到找到最初的触发点
  5. 从源头修复并加强防御：修复根因，并添加分层验证
决策树
Error appears deep in stack?
  → Yes: Start tracing backward
    → Can identify caller? → Trace one level up → Repeat
    → Cannot identify caller? → Add instrumentation (see advanced-techniques.md)
  → No: May not need tracing (error at entry point)

追踪流程

示例：在错误的目录中执行 Git 初始化

Error symptom → execFileAsync('git', ['init'], { cwd: '' })
  ← WorktreeManager.createSessionWorktree(projectDir='')
  ← Session.create() → Project.create() → Test code
  ← ROOT CAUSE: setupCoreTest() returns { tempDir: '' } before beforeEach

在每一层都要问： 这个值从何而来？这里是源头吗？

如需了解详细的追踪方法，请参阅追踪技巧 如需查看完整的真实案例，请参阅示例

找到根因后

从源头修复（如果在初始化前访问，则抛出错误）+ 添加纵深防御（在 Project.create、WorkspaceManager、环境保护措施和检测工具中进行验证）。

这可以防止类似 Bug，并更早发现问题。

导航

详细信息：

  • 追踪技巧：完整的追踪方法、模式和决策树
  • 示例：包含完整追踪链的真实调试场景
  • 高级技巧：堆栈跟踪、检测工具、测试污染检测
  • 集成：如何与系统化调试及其他技能配合使用

重要提醒

  • 切勿只在错误出现的位置修复
  • 务必追溯并找到最初的触发点
  • 在测试中使用 console.error() 调试（日志记录器可能会被抑制）
  • 在执行危险操作之前记录日志，而不是失败之后
  • 包含上下文：目录、cwd、环境、时间戳
  • 从源头修复后添加纵深防御
  • 随追踪过程记录过程（写下调用链）

危险信号——停止

出现以下想法时请停止：

  • “我就在这里添加验证”（却没有找到源头）
  • “这样就能防止错误”（只修复症状）
  • “反向追踪太难了”（应改为添加检测工具）
  • “先快速修一下”（会造成技术债务）

以上情况都意味着：继续追踪，找到根因。

与其他技能集成

  • systematic-debugging：在阶段 1 使用根因追踪
  • defense-in-depth：找到根因后添加
  • verification-before-completion：验证修复在源头生效
  • test-driven-development：针对根因而非症状编写测试

请参阅 集成，了解完整的工作流示例。

实际影响

来自一次调试会话（2025-10-03）：

  • 通过 5 层追踪找到根因
  • 在源头修复（getter 验证）
  • 添加 4 层防护
  • 1847 项测试通过，零污染
  • 节省时间：相比修复症状的方法，节省 3 小时以上

**总结：**追踪需要 15–30 分钟。修复症状则需要花费数小时反复处理问题。

评论

支持 Markdown