Debugging Wizard 技能实战指南用系统性根因分析方法在 Claude Code 中排查与修复 Bug【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills本指南以claude-skills仓库中的 Debugging Wizard 技能 为对象完整解析其五步调试工作流、路由到五个深度引用文件的渐进式披露架构以及覆盖 Python、JavaScript、Go 等语言的调试命令与六大调试策略。读完本文你将掌握一套先复现、再隔离、假设驱动、修复后防回归的可执行排障方法论并能直接在 Claude Code 中触发该技能完成错误定位与根因分析。一、技能定位一个面向质量域的专职调试专家Debugging Wizard 是仓库中 67 个全栈开发技能参见 README.md之一归属quality质量领域角色类型为specialist专家scope为analysis分析output-format为analysis分析型输出。从技能 frontmatterskills/debugging-wizard/SKILL.md可见其完整定义name: debugging-wizard description: Parses error messages, traces execution flow through stack traces, correlates log entries to identify failure points, and applies systematic hypothesis-driven methodology to isolate and resolve bugs. Use when investigating errors, analyzing stack traces, finding root causes of unexpected behavior, troubleshooting crashes, or performing log analysis, error investigation, or root cause analysis. license: MIT metadata: author: https://github.com/Jeffallan version: 1.1.0 domain: quality triggers: debug, error, bug, exception, traceback, stack trace, troubleshoot, not working, crash, fix issue role: specialist scope: analysis output-format: analysis related-skills: test-master, fullstack-guardian, monitoring-expert其能力声明遵循 CLAUDE.md 规定的能力描述 触发条件格式[Brief capability statement]. Use when [triggering conditions].禁止把流程步骤写进 description确保 Agent 会读取完整技能正文而不是只凭描述行事。triggers字段列出了 10 个触发关键词debug、error、bug、exception、traceback、stack trace、troubleshoot、not working、crash、fix issue当用户的排障请求命中这些词时技能会被激活。值得注意的工程细节仓库的 scripts/migrate-frontmatter.py 将debugging-wizard显式映射到quality域保证 skill 目录与metadata.domain一致CLAUDE.md 要求每个 SKILL.md 以指向文档站点的唯一 canonical 链接结尾该链接 URL 正是由domain skill-name拼出的因此域值错误会导致文档站 404。二、核心工作流五步系统性调试循环SKILL.md 正文将整个调试过程收敛为五步核心工作流Reproduce复现— 建立可一致重现的复现步骤Isolate隔离— 将问题缩小到最小失败用例Hypothesize and test假设与验证— 形成可测试的理论逐一验证或推翻Fix修复— 实施修复并验证方案Prevent预防— 添加测试与防护措施防止回归。这套循环贯穿分析 → 验证 → 修复 → 防回归全链路。与仓库中其他技能联动时它通常是排查链路的起点README 的 Multi-Skill Workflows 明确给出组合Bug Investigation: Debugging Wizard → Framework Expert → Test Master → Code Reviewer即先由 Debugging Wizard 定位根因再由框架专家确认上下文、Test Master 补测试、Code Reviewer 做最终审查。技能间的关联是双向声明的——Test Master 的related-skills中同样包含debugging-wizard见 skills/test-master/SKILL.md。三、渐进式披露架构一个 SKILL.md 五个深度引用文件该技能遵循 CLAUDE.md 定义的两级渐进式披露结构Tier 1 的 SKILL.md 保持精简约 80–100 行只承担角色定义、触发条件、核心工作流、约束和路由表Tier 2 的引用文件每个 100–600 行承载深度技术内容仅在上下文需要时按需加载从而实现约 50% 的 token 节省。SKILL.md 中的 Reference Guide 路由表完整列出五个引用文件及其加载时机Topic主题Reference引用文件Load When加载时机Debugging Toolsskills/debugging-wizard/references/debugging-tools.md按语言配置调试器Common Patternsskills/debugging-wizard/references/common-patterns.md识别 Bug 模式Strategiesskills/debugging-wizard/references/strategies.md二分搜索、git bisect、时间旅行Quick Fixesskills/debugging-wizard/references/quick-fixes.md常见错误的解决方案Systematic Debuggingskills/debugging-wizard/references/systematic-debugging.md复杂 Bug、多次修复失败、根因分析其中 Systematic Debugging 一行的注释明确标注其内容改编自 obra/superpowers作者 Jesse Vincent obraMIT License仓库的 CLAUDE.md 也记录了同样的归因来源研究过程可见 research/superpowers.md。仓库的校验脚本 scripts/validate-skills.py 会检查 SKILL.md 中引用的 reference 路径是否可解析到实际存在的文件确保路由表不会指向空链接。四、约束规范MUST DO 与 MUST NOT DOSKILL.md 用两组硬性约束框定调试行为边界防止越修越坏MUST DO必须做首先复现问题Reproduce the issue first收集完整的错误信息与堆栈跟踪一次只测试一个假设记录发现供后续参考修复后添加回归测试提交前移除所有调试代码MUST NOT DO禁止做不做验证就猜测同时做多处修改跳过复现步骤假设自己已经知道原因无保护地在生产环境调试在代码中遗留 console.log/debugger 语句这组约束与 Test Master 技能的测试先行理念见 skills/test-master/SKILL.md同源修复必须伴随回归测试调试痕迹必须清理。它们共同保证了调试产出物代码、日志、测试的最终质量。五、系统性调试四阶段从先找根因到三修阈值skill 的引用文件 systematic-debugging.md 开篇即给出核心原则——NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST没有根因调查就不允许修复并指出随意修复会造成修好一个、弄坏两个的恶性循环。它将调试流程固化为四个强制阶段Phase 1 根因调查Root Cause Investigation目标是在动手前彻底理解什么在失败、为什么失败。包含五个子步骤1.1 完整阅读错误消息——不能只看第一行要关注哪个操作失败、哪个文件的哪一行、调用栈是什么、是单个错误还是多个错误1.2 可靠复现——用文档记录 100% 能复现的步骤并注明浏览器、用户角色、数据状态等环境信息1.3 检查近期变更——git log --oneline -10看最近提交git log -p file看失败文件的具体改动必要时用 git bisect 定位引入点1.4 反向追踪数据流——从出错行如users.map(...)逐层回推数据来源props → 父组件 → useQuery定位真正的根因如查询加载中返回{ users: null }1.5 添加诊断性插桩——在数据边界处临时输出console.log([UserList] props:, JSON.stringify(props))等日志。Phase 2 模式分析Pattern Analysis找到正常工作的实现作参照。用grep定位同类组件完整研读正确实现然后用差异表记录正常实现 vs 出错实现在空值检查、默认值、加载态、错误处理上的每一项差异。Phase 3 假设测试Hypothesis Testing把理解写成假设 → 预测 → 测试三要素的形式每次只做一处最小改动、只验证一个变量用结果表记录每个假设的通过/失败结论严禁同时测试多个假设。Phase 4 实施Implementation先写一个修复前必然失败的测试用例再实现针对根因的单一修复最后运行完整测试套件与集成测试并在浏览器中覆盖正常、空数据、加载中、出错四种场景验证无新破坏。该文档还定义了极具实操价值的三修复阈值Three-Fix Threshold当连续 3 次修复尝试都在不同位置失败例如修好子组件又坏父组件、修好父组件原始错误又回来就应停止修补症状改为记录失败模式、识别被违背的架构假设、提出结构性变更并与团队讨论——三次失败通常意味着架构问题而非孤立 Bug。此外文档给出五条需要重置流程的红旗信号未追踪数据流就提方案猜测而非调试、同时做多处修改无法判断哪个改动生效、跳过测试创建Bug 会复发、试试看能不能行散弹式调试、不理解原因就修复贴创可贴而非治病。文档末尾附有完整的决策流程图从能否复现分支出发引导你在收集更多信息 / 追踪数据流 / 研究正确示例 / 写假设 / 写测试 / 实施 / 验证之间循环失败次数达到 3 次后转入质疑架构路径。六、常用调试命令Python、JavaScript、Go 与 git bisectSKILL.md 正文给出四组开箱即用的调试命令全部来自引用文件的对应章节可直接复制执行Pythonpdbpython -m pdb script.py # 启动调试器 # 进入 pdb 后 # b 42 — 在第 42 行设置断点 # n — 单步跳过step over # s — 单步进入step into # p some_var — 打印变量 # bt — 打印完整回溯补充自 debugging-tools.md 的进阶用法python -m pdb -c continue script.py可在异常发生后进入 post-mortem 现场代码内可用breakpoint()Python 3.7或import pdb; pdb.set_trace()print(f{variable})Python 3.8可同时打印变量名与值pdb 的完整命令集包括c继续、l列出代码、pp expr美化打印、w查看栈、q退出。JavaScript / Node.jsnode --inspect-brk script.js # 停在第一行挂接 Chrome DevTools # 在 Chrome 中打开 chrome://inspect → 点击 inspect # Sources 面板添加断点、观察表达式、单步执行补充自引用文件普通场景用node --inspect dist/main.js配合 ts-node 用node --inspect -r ts-node/register src/main.ts代码内用debugger;语句打点用console.log({ variable })、console.table(arrayOfObjects)、console.trace(Called from)快速诊断。Git bisect回归定位git bisect start git bisect bad # 当前提交是坏的 git bisect good v1.2.0 # 最后一个已知正常的 tag/commit # Git 会检出中间提交——测试后标记 git bisect good # 或git bisect bad # 重复直到 Git 指出第一个坏提交 git bisect reset引用文件还给出了自动化形式git bisect run npm test可让测试脚本自动判定每次检出的中间提交好坏。Godelvedlv debug ./cmd/server # 构建并附加 # (dlv) break main.go:55 # (dlv) continue # (dlv) print myVar补充自引用文件dlv attach pid附加到运行中的进程dlv test ./pkg/...调试测试常用命令包括next下一行、step进入、goroutines列出 goroutine。七、按语言的调试器速查与 VS Code 配置debugging-tools.md 提供了跨语言调试器对照表语言调试器启动命令TypeScript/JSNode Inspectornode --inspectPythonpdb/ipdbpython -m pdbGoDelvedlv debugRustrust-gdb/lldbrust-gdb ./target/debug/appJavaJDB/IDEIDE 调试器此外还提供 VS Code 的launch.json配置模板同时覆盖 TypeScriptNode 调试器 tsc: build预构建任务 outFiles与 Python集成终端控制台两种场景以及一张我需要 → 用什么工具速查表代码内断点用debugger;/breakpoint()打印变量名用console.log({x})/print(f{x})看栈用console.trace()/traceback.print_stack()检查对象用console.dir(obj)/dir(obj)。八、常见 Bug 模式库识别症状、锁定成因common-patterns.md 先把高频 Bug 归纳为模式表模式症状可能成因竞态条件Race condition间歇性失败缺少 await、异步时序差一错误Off-by-one丢失首/末元素与混用、数组越界空引用Null referenceundefined is not...缺少空值检查内存泄漏Memory leak内存持续增长未清理的监听器/定时器N1 查询数据越多越慢循环内逐条取数类型强制转换Type coercion行为异常而非闭包问题Closure issue回调中变量值错误循环变量捕获陈旧状态Stale state使用的是旧值React 状态闭包每个模式都配有 Bug/修复对照代码例如竞态条件的修复是改为const data await fetchData()闭包问题的修复是把var换成块级作用域的let或用 IIFE 捕获React 陈旧状态则要改用函数式更新setCount(prev prev 1)并配合clearInterval清理。文末的速查表给出症状 → 首选检查项的快速映射看到 undefined is not... 先查空值检查时好时坏查竞态条件回调值错误查闭包/陈旧状态越来越慢查内存泄漏与 N1差一个元素查循环边界与数组索引类型不匹配查vs。九、六大调试策略按场景选择打法strategies.md 提供六种策略及其适用场景策略适用场景二分搜索Binary Search未知 Bug 位置最小复现Minimal Repro复杂 Bug、上报问题Git Bisect回归类 Bug时间旅行Time Travel已知错误位置橡皮鸭Rubber Duck逻辑错误差异调试Delta Debug近期刚损坏二分搜索注释/停用一半代码测试 Bug 是否还在据此确定遗留半区反复直到定位典型应用是给数据处理流水线的各步骤之间插桩如console.log(After step2:, step2)。最小复现新建最小项目只保留复现所需代码逐个移除依赖、把输入化简到最小失败用例如const input { id: null }并记录精确复现步骤。Git Bisect配合第六节的命令在提交历史中二分定位首个坏提交。时间旅行从失败点出发逐步反推——第 45 行user.name报错为什么user是 undefined→第 40 行users.find(u u.id id)为何没找到→ 检查id是否正确、users是否有数据。橡皮鸭逐行向鸭子讲解代码应当做什么、实际做什么偏差通常会在讲述中自然显形。差异调试用git diff HEAD~5..HEAD、git log -p --follow -- file查看近期变更从改动中寻找线索。十、快速修复手册八类高频错误的即拿即用方案quick-fixes.md 汇集了 8 类最高频报错的标准修复套路Cannot read property x of undefined— 可选链user?.profile?.name、默认值?? Unknown、或守卫子句if (!user?.profile) return null;Unhandled promise rejection— 链式调用补.catch()或用try/catch包裹awaitReact 过多重渲染— 渲染期间调 setState 是死循环应把副作用移入useEffect对象/数组直接放依赖数组每次渲染都会变要用useMemo记忆化CORS 错误— 服务端加cors({ origin, credentials })或开发期在 Vite 配置/api代理到后端Maximum call stack size exceeded— 递归缺终止条件如factorial无if (n 1) return 1或对象存在循环引用导致JSON.stringify失败可用 replacer 把循环键替换为[Circular]Module not found— 先确认包已安装、import 路径是相对带./还是包名、ESM 是否缺扩展名、必要时清缓存重装await 用在非 async 函数— 给函数加async关键字forEach 不等待异步— 改用for...of串行等待或await Promise.all(items.map(...))并行处理。十一、输出模板让每次调试都有可复用的产出物SKILL.md 规定调试结束后必须按四段式输出Root Cause根因具体是什么导致的问题Evidence证据证明根因的堆栈跟踪、日志或测试Fix修复解决该问题的代码改动Prevention预防防止复发的测试或防护措施这套模板与 Test Master 技能的产出规范测试范围、测试用例、覆盖率分析、严重级别、修复建议见 skills/test-master/SKILL.md在设计上互补Debugging Wizard 负责诊断 修复 防复发Test Master 负责测试体系的建立与缺陷上报两者在同一排查链路中配合使用。十二、在 Claude Code 中启用与组合使用Debugging Wizard 是 README.md 中fullstack-dev-skills插件包的一部分安装方式为/plugin marketplace add jeffallan/claude-skills /plugin install fullstack-dev-skillsjeffallan安装后技能按 README.md 描述的上下文感知激活机制工作当你的请求命中triggers中的关键词如帮我排查这个 crash 的根因、这个 stack trace 什么意思时技能自动激活并加载references/systematic-debugging.md等对应引用文件随后可与其他技能组成多技能流水线完成完整排查——Bug Investigation: Debugging Wizard → Framework Expert → Test Master → Code Reviewer。本仓库是只读资源文章所有命令与配置均用于在读者自己的项目中查看、安装和运行该技能。理解这套方法论之后无论排障对象是前端组件、Node 服务、Python 脚本还是 Go 进程你都可以先走完复现 → 隔离 → 假设验证 → 修复 → 预防五步循环再借助模式库、策略表和快速修复手册把根因分析与防回归做到位。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考