企业官网建设流程全解析

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（分析型输出）。从技能 frontmatter（skills/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 正文将整个调试过程收敛为五步核心工作流：

1. Reproduce（复现）— 建立可一致重现的复现步骤；
2. Isolate（隔离）— 将问题缩小到最小失败用例；
3. Hypothesize and test（假设与验证）— 形成可测试的理论，逐一验证或推翻；
4. Fix（修复）— 实施修复并验证方案；
5. 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 路由表完整列出五个引用文件及其加载时机：

其中 Systematic Debugging 一行的注释明确标注其内容改编自 obra/superpowers（作者 Jesse Vincent @obra，MIT License），仓库的 CLAUDE.md 也记录了同样的归因来源，研究过程可见 research/superpowers.md。仓库的校验脚本 scripts/validate-skills.py 会检查 SKILL.md 中引用的 reference 路径是否可解析到实际存在的文件，确保路由表不会指向空链接。

四、约束规范：MUST DO 与 MUST NOT DO

SKILL.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 bisect

SKILL.md 正文给出四组开箱即用的调试命令，全部来自引用文件的对应章节，可直接复制执行：

Python（pdb）

python -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.js

node --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，可让测试脚本自动判定每次检出的中间提交好坏。

Go（delve）

dlv 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 提供了跨语言调试器对照表：

此外还提供 VS Code 的launch.json配置模板，同时覆盖 TypeScript（Node 调试器 +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 归纳为模式表：

每个模式都配有 Bug/修复对照代码，例如竞态条件的修复是改为const data = await fetchData()；闭包问题的修复是把var换成块级作用域的let或用 IIFE 捕获；React 陈旧状态则要改用函数式更新setCount(prev => prev + 1)并配合clearInterval清理。

文末的速查表给出"症状 → 首选检查项"的快速映射：看到 "undefined is not..." 先查空值检查；时好时坏查竞态条件；回调值错误查闭包/陈旧状态；越来越慢查内存泄漏与 N+1；差一个元素查循环边界与数组索引；类型不匹配查==vs===。

九、六大调试策略：按场景选择打法

strategies.md 提供六种策略及其适用场景：

二分搜索：注释/停用一半代码，测试 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 类最高频报错的标准修复套路：

1. Cannot read property 'x' of undefined— 可选链user?.profile?.name、默认值?? 'Unknown'、或守卫子句if (!user?.profile) return null;；
2. Unhandled promise rejection— 链式调用补.catch()，或用try/catch包裹await；
3. React 过多重渲染— 渲染期间调 setState 是死循环，应把副作用移入useEffect；对象/数组直接放依赖数组每次渲染都会变，要用useMemo记忆化；
4. CORS 错误— 服务端加cors({ origin, credentials })，或开发期在 Vite 配置/api代理到后端；
5. Maximum call stack size exceeded— 递归缺终止条件（如factorial无if (n <= 1) return 1），或对象存在循环引用导致JSON.stringify失败（可用 replacer 把循环键替换为'[Circular]'）；
6. Module not found— 先确认包已安装、import 路径是相对（带./）还是包名、ESM 是否缺扩展名、必要时清缓存重装；
7. await 用在非 async 函数— 给函数加async关键字；
8. forEach 不等待异步— 改用for...of串行等待，或await Promise.all(items.map(...))并行处理。

十一、输出模板：让每次调试都有可复用的产出物

SKILL.md 规定调试结束后必须按四段式输出：

1. Root Cause（根因）：具体是什么导致的问题
2. Evidence（证据）：证明根因的堆栈跟踪、日志或测试
3. Fix（修复）：解决该问题的代码改动
4. 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-skills@jeffallan

安装后技能按 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