
Reproduction Steps【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skillsNavigate to /usersClick Load More buttonWait for loading spinnerERROR: Cannot read property map of undefinedEnvironmentBrowser: Chrome 120User: Admin roleData state: 50 users in database环境信息浏览器、用户角色、数据状态同样关键——bug 往往只在特定数据量或特定角色下触发。这对应 SKILL.md 中 MUST DO 的 Gather complete error messages and stack traces。 ### 1.3 检查最近的变更 回归类 bug 十有八九由最近提交引入 bash # What changed recently? git log --oneline -10 # What specifically changed in the failing file? git log -p UserList.tsx # When did this start failing? git bisect start git bisect bad HEAD git bisect good v1.2.0git bisect可以自动化二分定位第一个坏提交。关于二分定位的更完整用法仓库在 strategies.md 中有专门小节支持git bisect run npm test之类的全自动回归扫描。1.4 沿数据流反向追踪从报错点出发一步一步向前追问这个变量从哪来// Error happens here: users.map(u u.name) // users is undefined // Trace backward: // Where does users come from? const users props.users; // Where do props come from? UserList users{data.users} / // Where does data come from? const { data } useQuery(GET_USERS); // ROOT CAUSE: Query returns { users: null } when loading这一步骤往往能直接暴露根因——本例中查询处于 loading 状态时返回{ users: null }而组件渲染时没有任何空值保护。1.5 添加诊断性插桩在关键边界处加临时日志确认数据在各环节的真实形态// Add temporary logging at boundaries console.log([UserList] props:, JSON.stringify(props)); console.log([UserList] users type:, typeof props.users); console.log([UserList] users value:, props.users); // Check at data source console.log([API] Response:, response); console.log([API] Response.data:, response.data);提示插桩日志属于临时调试手段。SKILL.md 的约束明确要求 Remove all debug code before committing提交前删除所有调试代码。Phase 2模式分析目标找到正常工作的示例搞清楚正确行为应该长什么样。2.1 定位相似的正常实现# Find similar components that work correctly grep -r useQuery src/components/ --include*.tsx # Find how other lists handle loading states grep -r loading src/components/*List* --include*.tsx2.2 完整研究参考实现逐行对比正常与异常实现的差异——往往差异点就是病灶// WORKING: ProductList.tsx function ProductList({ products, loading }) { if (loading) return Spinner /; if (!products) return null; // ← Handles undefined case return products.map(p ProductItem key{p.id} {...p} /); } // BROKEN: UserList.tsx function UserList({ users, loading }) { if (loading) return Spinner /; // Missing: !users check return users.map(u UserItem key{u.id} {...u} /); // Crashes }2.3 记录全部差异AspectWorking (ProductList)Broken (UserList)Null checkif (!products)MissingDefault valueproducts ?? []NoneLoading handledBefore renderBefore renderError handledReturns ErrorStateMissing差异表让正常 vs 异常的差距一目了然是形成假设的直接输入。Phase 3假设验证目标用受控实验验证你的理解是否正确。3.1 形成具体、书面的假设## Hypothesis #1 **Statement:** The crash occurs because users is undefined when the query is complete but returns no data. **Prediction:** Adding a null check before .map() will prevent the crash. **Test:** Add if (!users) return null; before the map call.好的假设必须包含三要素陈述Statement、可观测的预测Prediction、最小验证实验Test。3.2 用最小变更验证// Change ONLY one thing function UserList({ users, loading }) { if (loading) return Spinner /; if (!users) return null; // ← Single change return users.map(u UserItem key{u.id} {...u} /); }3.3 一次只改变一个变量## Test Results | Hypothesis | Change | Result | Conclusion | |------------|--------|--------|------------| | #1: Null check | Add if (!users) | ✓ Pass | Confirmed | Do NOT test multiple hypotheses simultaneously.严禁同时验证多个假设——否则无法判断究竟是哪个改动生效。这与仓库的调试红线完全一致SKILL.md 的 MUST NOT DO 明令 Make multiple changes at once。Phase 4实现目标带防护措施地永久修复 bug而不是打补丁。4.1 先写失败的测试用例在动手改代码之前先让测试证明 bug 存在describe(UserList, () { it(should handle undefined users gracefully, () { // This test should FAIL before the fix const { container } render(UserList users{undefined} loading{false} /); expect(container).not.toThrow(); expect(screen.queryByRole(list)).not.toBeInTheDocument(); }); });这条测试在修复前必须失败当前实现没有空值保护修复后通过。TDD 的红绿循环保证了修复的可验证性。对应 SKILL.md 中 MUST DO 的 Add regression tests after fixing。4.2 实现针对根因的单一修复function UserList({ users, loading }: UserListProps) { if (loading) return Spinner /; if (!users || users.length 0) { return EmptyState messageNo users found /; } return ( ul rolelist {users.map(u UserItem key{u.id} {...u} /)} /ul ); }注意这里比最初的假设多了一个边界不仅处理undefined还处理空数组并渲染专门的EmptyState这是对根因查询返回空数据的完整覆盖而非只堵住崩溃点。4.3 验证没有产生新的破坏# Run full test suite npm test # Run specific component tests npm test UserList # Run integration tests npm run test:integration # Verify in browser # 1. Normal case: 50 users # 2. Empty case: 0 users # 3. Loading case: spinner shows # 4. Error case: error message shows验证覆盖四类场景正常数据、空数据、加载中、出错态。只有全部通过才算修复完成。SKILL.md 的 Output Templates 也要求调试结束时给出四件套Root Cause根因→ Evidence证据→ Fix修复→ Prevention防复发措施。三连修复阈值连续三次失败后立即停止连续 3 次修复尝试失败 → 停止After 3 failed fix attempts → STOP。三次失败且失败点各不相同通常意味着架构性问题而不是孤立的 bugFix Attempt 1: Added null check → New error in child component Fix Attempt 2: Fixed child component → New error in parent Fix Attempt 3: Fixed parent → Original error returns ↓ STOP. QUESTION ARCHITECTURE.到达阈值时应该做什么停止修补症状记录失败的模式每次修复又引入了什么新错误识别被违反的架构假设提出结构性变更而不是继续打补丁与团队讨论后再继续。这个停手阈值与决策流程图中的Question architecture分支衔接当修复尝试次数达到上限仍未通过测试时流程就进入架构反思而不是退回 Phase 1 无限重试。需要重置流程的红旗信号出现以下任何信号立即停止当前动作、回到 Phase 1 重新开始Red FlagWhy Its WrongProposing solutions before tracing data flowGuessing, not debuggingMaking multiple simultaneous changesCant identify which change workedSkipping test creationBug will recurLets try this and see if it worksShotgun debuggingFixing without understanding the causeBand-aid, not cure这些信号本质上把调试从科学实验退化成碰运气。对照 SKILL.md 的 MUST NOT DO 清单可以进一步验证跳过复现步骤、不做验证就猜测、一次改多处、假定已知根因、在生产环境无防护地调试都是被明令禁止的行为。决策流程图整个调试流程可以用下面这张决策图概括它是四阶段方法论的运行时总控┌──────────────────┐ │ Bug Reported │ └────────┬─────────┘ │ ┌──────────────▼──────────────┐ │ Can you reproduce it? │ └──────────────┬──────────────┘ No │ Yes ┌────────────────┴────────────────┐ ▼ ▼ ┌───────────────┐ ┌─────────────────┐ │ Get more info │ │ Trace data flow │ └───────────────┘ └────────┬────────┘ │ ┌──────────────▼──────────────┐ │ Do you understand the cause? │ └──────────────┬──────────────┘ No │ Yes ┌────────────────────────┴─────────┐ ▼ ▼ ┌───────────────┐ ┌─────────────────┐ │ Study working │ │ Write hypothesis│ │ examples │ └────────┬────────┘ └───────────────┘ │ ┌───────▼───────┐ │ Write test │ └───────┬───────┘ │ ┌───────▼───────┐ │ Implement │ └───────┬───────┘ │ ┌──────────────────▼──────────────────┐ │ Does test pass? │ └──────────────────┬──────────────────┘ No │ Yes ┌────────────────────────┴──────────┐ ▼ ▼ ┌───────────────┐ ┌─────────────────┐ │ Attempt 3? │ │ Done │ └───────┬───────┘ └─────────────────┘ No │ Yes ┌───────────────┴─────────────────┐ ▼ ▼ ┌───────────────────┐ ┌─────────────────────┐ │ Question │ │ Return to Phase 1 │ │ architecture │ └─────────────────────┘ └───────────────────┘关键分支解读无法复现→ 不盲目猜测先收集更多信息不理解根因→ 去研究正常实现Phase 2理解根因→ 写假设、写测试、实现测试未通过→ 判断是否达到三次尝试上限未达到则返回 Phase 1 重新调查达到则质疑架构。配套武器库工具、策略与常见模式系统性调试方法论不是孤立的——它在 claude-skills 仓库中与 debugging-wizard 技能的其他参考文档组成完整武器库在 SKILL.md 的路由表中按场景分发TopicReferenceLoad WhenDebugging Toolsreferences/debugging-tools.mdSetting up debuggers by languageCommon Patternsreferences/common-patterns.mdRecognizing bug patternsStrategiesreferences/strategies.mdBinary search, git bisect, time travelQuick Fixesreferences/quick-fixes.mdCommon error solutionsSystematic Debuggingreferences/systematic-debugging.mdComplex bugs, multiple failed fixes, root cause analysis调试器速查debugging-tools.md# Node.js / TypeScript node --inspect-brk dist/main.js # 暂停在首行可接 Chrome DevTools # Python python -m pdb script.py # 启动 pdb python -m pdb -c continue script.py # 异常后 post-mortem 检查 # Go (Delve) dlv debug ./cmd/server # (dlv) break main.go:55 # (dlv) print myVar # Rust rust-gdb ./target/debug/app代码内快速诊断技巧debugger; // JS 断点 console.log({ variable }); // 打印变量名值 console.trace(Called from); // 打印调用栈breakpoint() # Python 3.7 print(f{variable}) # Python 3.8 打印变量名值VS Code 调试配置示例.vscode/launch.json{ version: 0.2.0, configurations: [ { type: node, request: launch, name: Debug TypeScript, program: ${workspaceFolder}/src/main.ts, preLaunchTask: tsc: build, outFiles: [${workspaceFolder}/dist/**/*.js] } ] }核心调试策略strategies.mdStrategyBest ForBinary SearchUnknown bug location未知 bug 位置Minimal ReproComplex bugs, reporting复杂 bug、上报Git BisectRegression bugs回归 bugTime TravelKnown error location已知错误位置Rubber DuckLogic errors逻辑错误Delta DebugRecent breakage近期破坏例如二分查找定位未知 bug注释掉一半代码测试 bug 是否仍存在据此确定 bug 所在半区反复缩小范围直到隔离。最小复现策略则主张新建最小项目、只保留能复现 bug 的代码、逐个移除依赖、把输入简化到最小失败用例。高频 bug 模式识别common-patterns.mdPatternSymptomLikely CauseRace conditionIntermittent failuresMissing await, async timingOff-by-oneMissing first/last itemvs, array boundsNull referenceundefined is not...Missing null checkMemory leakGrowing memoryUncleaned listeners/intervalsN1 queriesSlow with more dataFetching in loopType coercionUnexpected behaviorinstead ofClosure issueWrong variable valueLoop variable captureStale stateOld value usedReact state closure常见修复范式quick-fixes.md也可作为 Phase 4 的直接参考例如空引用用可选链user?.profile?.name ?? Unknown、异步失败加.catch()或 try/catch、无限递归补递归基例等。注意quick-fixes 是理解问题后的修复手段绝不能反过来先套修复再找问题——这与系统性调试的第一原则相矛盾。在 claude-skills 中的定位与触发方式debugging-wizard 在仓库中归属 quality质量领域其 frontmatter 定义的触发词包括debug, error, bug, exception, traceback, stack trace, troubleshoot, not working, crash, fix issue。这意味着只要请求中涉及报错排查、崩溃分析、日志关联、根因定位SKILL.md 就会被自动激活并按场景加载上述参考文档。它的核心工作流Reproduce → Isolate → Hypothesize and test → Fix → Prevent与本篇四阶段方法论一一对应其 Output Templates 要求每次调试输出 Root Cause / Evidence / Fix / Prevention确保调试结论可审计、可复用。在项目级工作流中bug 修复链路被编排为Bug Investigation: Debugging Wizard → Framework Expert → Test Master → Code Reviewer【免费下载链接】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),仅供参考