AI 技能AI 插件人工智能开发工具【免费下载链接】superpowers-zh AI 编程超能力 · 中文增强版 — superpowers250k ⭐完整汉化 4 个中国原创 skills让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 26 款 AI 编程工具真正会干活项目地址https://gitcode.com/gh_mirrors/su/superpowers-zh点击查看免费下载导读本文完整讲解开源仓库 superpowers-zh 中 systematic-debugging 技能 的核心方法论一套面向 AI 编程助手与人类工程师的四阶段调试流程——根因调查 → 模式分析 → 假设与验证 → 实施。文章将以该技能文档为骨架结合仓库内配套的根因追踪、纵深防御、条件等待三份辅助技术文档及其可运行的示例代码、二分查找脚本与压力测试用例深入剖析先找根因、再谈修复的工程原则。读完本文你将掌握一套可立即复用的系统化调试 SOP能在生产故障、不稳定测试、深层调用栈 bug 等场景中脱离猜改循环稳定定位真正的源头。技能定位与核心原则技能元信息该技能以标准 frontmatter 声明元数据见 SKILL.mdname: systematic-debugging description: 遇到任何 bug、测试失败或异常行为时使用在提出修复方案之前执行 version: 1.0.0 license: MIT metadata: hermes: tags: [debugging]触发条件遇到任何 bug、测试失败或异常行为时在提出修复方案之前执行适用范围既服务于 Claude Code / Copilot CLI / Hermes Agent 等 AI 编程工具通过 hermes tags 暴露也是供人类工程师对照执行的标准流程。核心原则只修症状就是失败技能的出发点是两条近乎严苛的约束核心原则在尝试修复之前务必先找到根本原因。只修症状就是失败。敷衍走流程等于违背调试的精神。并有一条铁律贯穿始终不做根因调查不许提修复方案在完成第一阶段根因调查之前不允许提出任何修复方案。这套设计刻意用ALWAYS / NEVER式的绝对措辞而不是应该/尽量来抵抗压力环境下的合理化倾向这一点在技能的 CREATION-LOG.md 中被明确记录为bulletproofing防弹化手段——它来自对真实工程中时间紧迫时最容易猜测式修复这一观察的系统性反制。何时使用覆盖全类型技术问题技能的何时使用部分定义了适用范围任何技术问题都应触发该流程测试失败生产环境 bug异常行为性能问题构建失败集成问题其中有三类高风险情形尤其必须使用时间紧迫紧急情况最容易让人猜测式修复觉得一个小修改就能搞定已经尝试了多种修复、上一次修复没有生效、或你完全没有理解问题。同时技能特别强调以下场景也不要跳过流程问题看起来很简单——简单的 bug 也有根本原因只是流程走得更快你很赶时间——越急越容易返工领导要求立刻修好——系统化调试比反复尝试更快。这份越简单越要查根因、越紧急越要按流程的设计正是针对日常工程中两个最大的诱因轻敌与焦虑。四个阶段详解完整调试 SOP技能要求必须按顺序完成每个阶段才能进入下一个阶段。下面结合仓库配套文档逐阶段展开。第一阶段根因调查在尝试任何修复之前本阶段唯一目标理解问题而不是解决问题。四个步骤缺一不可。1. 仔细阅读错误信息。不要跳过错误或警告——它们往往直接包含解决方案。要求完整阅读堆栈跟踪并记下行号、文件路径、错误码。2. 稳定复现。自问能可靠地触发它吗具体的复现步骤是什么每次都能复现吗如果无法复现则收集更多数据而不是猜测。这一步是后续一切验证工作的地基。3. 检查近期变更。什么变更可能导致了这个问题重点检查git diff、最近的提交、新依赖、配置变更和环境差异。4. 在多组件系统中收集证据。当系统有多个组件如 CI → 构建 → 签名或 API → 服务 → 数据库时在提出修复方案之前先添加诊断埋点按如下套路执行对每个组件边界 - 记录进入组件的数据 - 记录离开组件的数据 - 验证环境/配置的传递 - 检查每一层的状态 执行一次以收集证据确定断裂点在哪里 然后分析证据定位故障组件 然后针对该组件深入调查SKILL.md 给出了一个四层签名链路的诊断示例工作流 → 构建脚本 → 签名脚本 → 实际签名# 第 1 层工作流 echo Secrets available in workflow: echo IDENTITY: ${IDENTITY:SET}${IDENTITY:-UNSET} # 第 2 层构建脚本 echo Env vars in build script: env | grep IDENTITY || echo IDENTITY not in environment # 第 3 层签名脚本 echo Keychain state: security list-keychains security find-identity -v # 第 4 层实际签名 codesign --sign $IDENTITY --verbose4 $APP由此可以逐层定位断裂点例如secrets → workflow ✓, workflow → build ✗从而锁定故障组件。5. 跟踪数据流。当错误发生在调用栈深处时使用完整的反向追踪技术——技能指向 root-cause-tracing.md详见下文辅助技术章节。简要版三步走错误值从哪里产生的谁用错误值调用了这里持续向上追踪直到找到源头在源头修复而不是在症状处修复。第二阶段模式分析先找到模式再修复在确认根因方向后不要急于下手先做对照分析找到可正常工作的示例——在同一代码库中寻找类似的正常代码与出问题的代码作对比与参考实现对比——如果是实现某个模式完整阅读参考实现不要略读要逐行阅读在应用之前彻底理解该模式识别差异——列出正常代码与出问题代码之间的每一个差异无论多小不要假设那不可能有影响理解依赖关系——这个功能需要哪些其他组件需要哪些设置、配置、环境它有哪些隐含假设这一阶段直接对治两类常见错误一知半解照搬模式以及忽略隐含前提导致环境性失败。第三阶段假设与验证科学方法采用严格的科学方法循环提出单一假设——清晰地陈述我认为 X 是根本原因因为 Y写下来要具体不要含糊最小化测试——做出最小的改动来验证假设每次只改一个变量不要同时修复多个问题继续之前先验证——生效了进入第四阶段没生效则提出新假设不要在失败假设上叠加更多修复当你不确定时——直接说我不理解 X不要假装自己知道寻求帮助并做更多调研。单一假设 单变量验证的设计是为了强制思考、防止散弹枪式修复shotgun fixes这是技能防弹化设计的结构性防御之一见 CREATION-LOG.md。第四阶段实施修复根本原因而非症状1. 创建失败的测试用例。先做最简化的复现尽可能用自动化测试没有测试框架就写一次性测试脚本。修复前必须先有测试并建议使用仓库中的 test-driven-development 技能 来编写规范的失败测试。注意技能在 CREATION-LOG 中特别澄清TDD 的最简单的代码原则与调试的找根因原则是两套方法论不要混淆见 CREATION-LOG.md。2. 实施单一修复。只修复已定位的根本原因每次只改一处不做顺便改改的优化不捆绑重构。3. 验证修复。测试通过了吗其他测试没有被破坏吧问题真的解决了吗在宣称成功之前使用 verification-before-completion 技能 做完成前验证。4. 如果修复不起作用——止损规则停下来先数一数已经尝试了几次修复少于 3 次回到第一阶段用新信息重新分析3 次或以上停下来质疑架构见第 5 步没有经过架构讨论不要尝试第 4 次修复。5. 如果 3 次以上修复都失败了质疑架构。以下模式表明存在架构问题每次修复都暴露出新的共享状态/耦合/其他位置的问题修复需要大规模重构才能实现每次修复都在其他地方产生新的症状。此时应停下追问根本性问题这个模式从根本上合理吗我们是不是在惯性驱动下坚持了错误方案应该重构架构还是继续修补症状在尝试更多修复之前和你的搭档讨论。技能明确这不是假设失败——这是架构有误。红线停下来按流程走技能列出了一句式自检清单一旦发现自己正在想以下任何一句就必须停下并回到第一阶段先临时修一下以后再排查试着改改 X 看看行不行一次性改多个地方跑测试看看跳过测试我手动验证大概是 X 的问题让我修一下我不完全理解但这应该能行模式说的是 X但我换个方式用主要问题有这些[未经调查就列出修复方案]没有追踪数据流就提出解决方案再试一次修复已经尝试了 2 次以上每次修复都暴露出不同地方的新问题红线部分是技能防弹化的核心——它把当下感觉完全合理的偷懒瞬间逐字列出制造认知摩擦cognitive friction让使用者看见即止损见 CREATION-LOG.md。搭档发出的信号说明你的方法不对在结对调试或人与 AI 搭档协作中同伴的提醒往往是流程偏离的早期警报信号含义难道不是这样吗你在没有验证的情况下做了假设它能告诉我们……吗你应该先收集证据别猜了你在没有理解的情况下提出修复深入想想要质疑根本性问题而不只是症状我们卡住了沮丧的语气你的方法没有奏效看到这些信号时停下来回到第一阶段。常见借口与对应现实技能以表格形式逐条驳斥了调试中最常见的合理化借口借口现实问题很简单不需要走流程简单问题也有根本原因。对于简单 bug流程很快就能走完。紧急情况没时间走流程系统化调试比反复猜测式修复更快。先试一下再排查第一次修复就定下了基调。从一开始就做对。确认修复有效后再写测试没有测试的修复留不住。先写测试才能证明修复有效。一次修多个问题省时间无法隔离哪个生效了。还会引入新 bug。参考实现太长了我自己改改一知半解必然出 bug。完整阅读。我看出问题了让我修一下看到症状 ≠ 理解根因。再试一次在 2 次以上失败后3 次以上失败 架构问题。质疑模式不要继续修。四阶段速查表阶段关键活动通过标准1. 根因阅读错误、复现、检查变更、收集证据理解了什么出了问题以及为什么2. 模式找到正常示例、对比识别出差异3. 假设提出理论、最小化验证假设被验证或产生新假设4. 实施创建测试、修复、验证bug 已修复测试通过当流程显示找不到根因时如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的则你已经完成了流程记录你排查了什么实施适当的处理措施重试、超时、错误提示添加监控/日志以便后续排查。但技能给出了一个清醒的警告95% 的找不到根因其实是排查不充分。换句话说先怀疑自己的调查深度再归因于外部环境。配套辅助技术同一目录下的深度资料系统化调试不是一个孤立的 SKILL仓库在 skills/systematic-debugging/ 目录下配套了三份可单独引用的技术文档与一份可运行示例分别是根因追踪、纵深防御校验、基于条件的等待。下面逐一展开。根因追踪root-cause-tracingroot-cause-tracing.md 解决Bug 出现在调用栈深处的典型困境如git init在错误目录执行、在错误位置创建文件、用错误路径打开数据库。其核心原则沿着调用链反向追踪直到找到最初的触发点然后在源头修复并配有决策流程图。适用场景错误发生在执行深处不在入口点堆栈跟踪显示很长的调用链不清楚无效数据从哪里来需要找出是哪个测试/代码触发了问题。追踪流程以一个真实的 TypeScript 案例完整演示观察症状Error: git init failed in /Users/jesse/project/packages/core找到直接原因await execFileAsync(git, [init], { cwd: projectDir })问谁调用了它沿调用链上溯WorktreeManager.createSessionWorktree(projectDir, sessionId) → Session.initializeWorkspace() → Session.create() → 测试中的 Project.create()继续向上追踪发现传入的projectDir 空字符串空字符串作为cwd会被解析为process.cwd()——即源代码目录找到最初的触发点setupCoreTest()初始返回{ tempDir: }而测试在beforeEach之前就访问了它。添加堆栈跟踪当无法手动追踪时在危险操作之前注入诊断埋点用new Error().stack捕获完整调用链并记录directory、cwd、process.env.NODE_ENV等上下文// 在有问题的操作之前 async function gitInit(directory: string) { const stack new Error().stack; console.error(DEBUG git init:, { directory, cwd: process.cwd(), nodeEnv: process.env.NODE_ENV, stack, }); await execFileAsync(git, [init], { cwd: directory }); }两个关键技巧在测试中使用console.error()而非 loggerlogger 可能被抑制、不会显示运行时用npm test 21 | grep DEBUG git init捕获输出。分析堆栈跟踪时找测试文件名、找触发调用的行号、识别模式同一个测试同一个参数。找出导致污染的测试当测试期间出现诡异状态但不知道是谁造成时使用同目录下的二分查找脚本 find-polluter.sh./find-polluter.sh .git src/**/*.test.ts该脚本逐个运行匹配的测试文件在第一个污染者即创建了目标文件/目录的测试处停止并输出定位信息。脚本内部做了两处健壮性处理去除./前缀以兼容两种写法以及将**/折叠一次以匹配直接位于基础目录下的文件见 find-polluter.sh 注释。真实案例的最终复盘空 projectDir 事件的五层追踪链、根因顶层变量初始化时访问了空值、修复把tempDir改为 getter在beforeEach之前访问时抛出异常以及同时添加的四层纵深防御详见下文。文档给出实际效果5 层追踪找到根因、源头修复、4 层防御、1847 个测试通过且零污染见 root-cause-tracing.md。纵深防御校验defense-in-depthdefense-in-depth.md 回答一个问题找到根因、修完 bug 之后呢单点校验可能被不同的代码路径、重构或 mock 绕过因此核心原则是在数据经过的每一层都做校验让这个 bug 在结构上不可能发生。单层校验的语义是我们修了这个 bug多层校验的语义是我们让这个 bug 不可能再发生。文档给出四个层级各有分工第 1 层入口校验——在 API 边界拒绝明显无效的输入function createProject(name: string, workingDirectory: string) { if (!workingDirectory || workingDirectory.trim() ) { throw new Error(workingDirectory cannot be empty); } if (!existsSync(workingDirectory)) { throw new Error(workingDirectory does not exist: ${workingDirectory}); } if (!statSync(workingDirectory).isDirectory()) { throw new Error(workingDirectory is not a directory: ${workingDirectory}); } // ... 继续处理 }第 2 层业务逻辑校验——确保数据对当前操作是合理的如工作区初始化要求projectDir非空。第 3 层环境守卫——防止在特定环境中执行危险操作。示例为测试环境下拒绝在临时目录之外执行git initasync function gitInit(directory: string) { // 在测试中拒绝在临时目录之外执行 git init if (process.env.NODE_ENV test) { const normalized normalize(resolve(directory)); const tmpDir normalize(resolve(tmpdir())); if (!normalized.startsWith(tmpDir)) { throw new Error( Refusing git init outside temp dir during tests: ${directory} ); } } // ... 继续处理 }第 4 层调试埋点——记录目录、cwd、堆栈等上下文信息供其他层级失效时事后分析。应用模式发现 bug 后先追踪数据流错误值从哪里产生、在哪里被使用再标注所有检查点数据经过的每一个节点然后在每一层添加校验最后逐层测试尝试绕过第 1 层验证第 2 层能否捕获。文档用空 projectDir 案例说明了四层防御的实际落点Project.create()校验非空/存在/可写 →WorkspaceManager校验 projectDir 非空 →WorktreeManager在测试中拒绝在 tmpdir 之外执行 git init → git init 前记录堆栈跟踪。关键洞察是四层缺一不可不同代码路径绕过入口校验、mock 绕过业务逻辑检查、跨平台边界情况需要环境守卫、调试日志发现结构性误用——每一层都捕获过其他层遗漏的 bug见 defense-in-depth.md。基于条件的等待condition-based-waitingcondition-based-waiting.md 专门对付不稳定测试硬编码延迟setTimeout、sleep本质是在猜测时序会造成竞态条件——在快速机器上通过在高负载或 CI 环境下失败。核心原则等待你真正关心的条件而不是猜测它需要多长时间。适用场景测试中有硬编码延迟测试不稳定时而通过高负载下失败并行运行时测试超时等待异步操作完成。不适用场景测试实际的时序行为如防抖、节流间隔此时若必须用硬编码超时务必注释说明原因。核心模式对照// ❌ 之前猜测时序 await new Promise(r setTimeout(r, 50)); const result getResult(); expect(result).toBeDefined(); // ✅ 之后等待条件满足 await waitFor(() getResult() ! undefined); const result getResult(); expect(result).toBeDefined();常用模式速查场景模式等待事件waitFor(() events.find(e e.type DONE))等待状态waitFor(() machine.state ready)等待数量waitFor(() items.length 5)等待文件waitFor(() fs.existsSync(path))复合条件waitFor(() obj.ready obj.value 10)通用轮询函数实现带超时保护的 10ms 轮询超时即抛出带清晰描述的错误async function waitForT( condition: () T | undefined | null | false, description: string, timeoutMs 5000 ): PromiseT { const startTime Date.now(); while (true) { const result condition(); if (result) return result; if (Date.now() - startTime timeoutMs) { throw new Error(Timeout waiting for ${description} after ${timeoutMs}ms); } await new Promise(r setTimeout(r, 10)); // 每 10ms 轮询一次 } }三个常见错误与修正轮询太频繁setTimeout(check, 1)浪费 CPU改为每 10ms 一次没有超时条件永远不满足时无限循环必须始终设置超时并提供清晰错误信息数据过期在循环外缓存状态应在循环内调用 getter 获取最新数据。何时硬编码超时才是正确的先等待触发条件再基于已知时序而非猜测等待并注释说明原因。文档示例工具每 100ms tick 一次需要 2 次 tick 验证部分输出则先waitForEvent(manager, TOOL_STARTED)再setTimeout(200ms)并注释// 200ms 100ms 间隔的 2 次 tick——有文档说明且有充分理由。完整实现与领域专用辅助函数同目录下的 condition-based-waiting-example.ts 提供了源自真实调试过程Lace 测试基础设施改进的完整可运行实现包含三个带类型定义的领域专用函数waitForEvent(threadManager, threadId, eventType, timeoutMs 5000)——等待指定事件类型首次出现waitForEventCount(threadManager, threadId, eventType, count, timeoutMs 5000)——等待指定数量的事件如等待 2 次AGENT_MESSAGE初始回复 后续延续超时错误中会报告实际收到数量waitForEventMatch(threadManager, threadId, predicate, description, timeoutMs 5000)——按自定义谓词匹配事件数据而非仅匹配类型如等待TOOL_RESULT且e.data.id call_123。文件末尾附带了修复前后对比的真实用例修复前靠setTimeout(300)setTimeout(50)猜测工具启动与结果到达的时序导致expect(toolResults.length).toBe(2)随机失败修复后改用waitForEventCount(threadManager, threadId, TOOL_CALL, 2)等待工具启动、waitForEventCount(..., TOOL_RESULT, 2)等待结果断言稳定通过。文档记录的实际效果修复了 3 个文件中的 15 个不稳定测试通过率 60% → 100%执行时间快了 40%再无竞态条件见 condition-based-waiting.md。技能的诞生与验证从实战中提炼并经受压力测试理解这套方法论如何被打磨成防弹形态能帮助读者更正确地使用它。CREATION-LOG.md 记录了技能的来源从一份真实工程环境中的CLAUDE.md调试框架中提取、按技能创作规范结构化并通过三重手段防弹化语言选择用ALWAYS / NEVER取代应该/尽量用即使看起来更快/即使我似乎很赶时间等措辞封堵压力场景的合理化出口结构防御第一阶段强制前置、单一假设规则、显式失败模式第一次修复失败后的强制动作、反模式清单冗余强化根因命令在概述、使用时机、第一阶段与实施规则中反复出现绝不修症状在不同语境出现 4 次。该技能配套了 4 份验证测试位于同一目录分别覆盖不同压力场景test-academic.md无压力学术场景验证对四阶段流程的完整理解与引用准确性test-pressure-1.md生产故障紧急场景——API 宕机每分钟损失 1.5 万美元、管理者施压、快速修复看起来只需 5 分钟考察是否抵抗捷径test-pressure-2.md沉没成本 疲惫场景——已花 4 小时猜改超时仍不稳定考察能否放弃再试一次回到第一阶段test-pressure-3.md权威与社会压力场景——资深工程师与技术主管都主张直接修复考察是否坚持先查根因。CREATION-LOG 记录了四份测试的结果全部通过未发现合理化行为——包括在明显快速修复诱惑下仍坚持完整流程并找到真正根因、在多层系统失败中逐层追踪到源头、在首次假设失败后停下重新分析而非散弹枪式叠加见 CREATION-LOG.md。这些测试文件本身即可作为团队演练系统化调试的现成素材。实战落地建议把铁律挂在工作区可见处不做根因调查不许提修复方案——对 AI 编程助手与结对搭档同样生效遇到不稳定测试先替换硬编码等待直接复用 condition-based-waiting-example.ts 中的waitForEvent*模式改造现有断言深层调用栈错误先反向追踪再动手参考 root-cause-tracing.md 的五步追踪流程与new Error().stack埋点技巧必要时用 find-polluter.sh 定位污染测试修复完成后不要止步按 defense-in-depth.md 在入口、业务逻辑、环境、调试四个层级补上校验让 bug结构上不可能再发生守住止损线第 2 次修复失败就停止叠加第 3 次失败直接质疑架构——这是该技能最反直觉、也最省时间的一条规则。赞分享AI 技能AI 插件人工智能开发工具【免费下载链接】superpowers-zh AI 编程超能力 · 中文增强版 — superpowers250k ⭐完整汉化 4 个中国原创 skills让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 26 款 AI 编程工具真正会干活项目地址https://gitcode.com/gh_mirrors/su/superpowers-zh点击查看免费下载相关推荐OpenMetadata 系统化调试实战指南四阶段根因分析法OpenMetadata 系统化调试实战指南四阶段根因分析法 调试 OpenMetadata 时你是否经历过改一个地方碰运气、跑一次测试看结果的循环本数据目录数据血缘数据治理后端MCP 服务Agentic Awesome Skills 之 Systematic Debugging四阶段根因调试方法论实战指南Agentic Awesome Skills 之 Systematic Debugging四阶段根因调试方法论实战指南 本文以 AASAgentic AweAI 技能AI 插件Superpowers系统化调试技能4阶段根因分析方法论——快速定位并解决复杂代码问题的终极指南Superpowers系统化调试技能4阶段根因分析方法论——快速定位并解决复杂代码问题的终极指南 Superpowers是一款强大的Claude Code核心AI 技能AI 插件开发工具上一篇MetaTube让Jellyfin媒体库变得聪明起来的智能管家下一篇专业级NES模拟器Mesen深度解析从游戏怀旧到逆向开发的5大实战场景创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 superpowers-zh 系统化调试技能实战：四阶段根因驱动方法论与配套辅助技术全解
AI 技能AI 插件人工智能开发工具【免费下载链接】superpowers-zh AI 编程超能力 · 中文增强版 — superpowers250k ⭐完整汉化 4 个中国原创 skills让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 26 款 AI 编程工具真正会干活项目地址https://gitcode.com/gh_mirrors/su/superpowers-zh点击查看免费下载导读本文完整讲解开源仓库 superpowers-zh 中 systematic-debugging 技能 的核心方法论一套面向 AI 编程助手与人类工程师的四阶段调试流程——根因调查 → 模式分析 → 假设与验证 → 实施。文章将以该技能文档为骨架结合仓库内配套的根因追踪、纵深防御、条件等待三份辅助技术文档及其可运行的示例代码、二分查找脚本与压力测试用例深入剖析先找根因、再谈修复的工程原则。读完本文你将掌握一套可立即复用的系统化调试 SOP能在生产故障、不稳定测试、深层调用栈 bug 等场景中脱离猜改循环稳定定位真正的源头。技能定位与核心原则技能元信息该技能以标准 frontmatter 声明元数据见 SKILL.mdname: systematic-debugging description: 遇到任何 bug、测试失败或异常行为时使用在提出修复方案之前执行 version: 1.0.0 license: MIT metadata: hermes: tags: [debugging]触发条件遇到任何 bug、测试失败或异常行为时在提出修复方案之前执行适用范围既服务于 Claude Code / Copilot CLI / Hermes Agent 等 AI 编程工具通过 hermes tags 暴露也是供人类工程师对照执行的标准流程。核心原则只修症状就是失败技能的出发点是两条近乎严苛的约束核心原则在尝试修复之前务必先找到根本原因。只修症状就是失败。敷衍走流程等于违背调试的精神。并有一条铁律贯穿始终不做根因调查不许提修复方案在完成第一阶段根因调查之前不允许提出任何修复方案。这套设计刻意用ALWAYS / NEVER式的绝对措辞而不是应该/尽量来抵抗压力环境下的合理化倾向这一点在技能的 CREATION-LOG.md 中被明确记录为bulletproofing防弹化手段——它来自对真实工程中时间紧迫时最容易猜测式修复这一观察的系统性反制。何时使用覆盖全类型技术问题技能的何时使用部分定义了适用范围任何技术问题都应触发该流程测试失败生产环境 bug异常行为性能问题构建失败集成问题其中有三类高风险情形尤其必须使用时间紧迫紧急情况最容易让人猜测式修复觉得一个小修改就能搞定已经尝试了多种修复、上一次修复没有生效、或你完全没有理解问题。同时技能特别强调以下场景也不要跳过流程问题看起来很简单——简单的 bug 也有根本原因只是流程走得更快你很赶时间——越急越容易返工领导要求立刻修好——系统化调试比反复尝试更快。这份越简单越要查根因、越紧急越要按流程的设计正是针对日常工程中两个最大的诱因轻敌与焦虑。四个阶段详解完整调试 SOP技能要求必须按顺序完成每个阶段才能进入下一个阶段。下面结合仓库配套文档逐阶段展开。第一阶段根因调查在尝试任何修复之前本阶段唯一目标理解问题而不是解决问题。四个步骤缺一不可。1. 仔细阅读错误信息。不要跳过错误或警告——它们往往直接包含解决方案。要求完整阅读堆栈跟踪并记下行号、文件路径、错误码。2. 稳定复现。自问能可靠地触发它吗具体的复现步骤是什么每次都能复现吗如果无法复现则收集更多数据而不是猜测。这一步是后续一切验证工作的地基。3. 检查近期变更。什么变更可能导致了这个问题重点检查git diff、最近的提交、新依赖、配置变更和环境差异。4. 在多组件系统中收集证据。当系统有多个组件如 CI → 构建 → 签名或 API → 服务 → 数据库时在提出修复方案之前先添加诊断埋点按如下套路执行对每个组件边界 - 记录进入组件的数据 - 记录离开组件的数据 - 验证环境/配置的传递 - 检查每一层的状态 执行一次以收集证据确定断裂点在哪里 然后分析证据定位故障组件 然后针对该组件深入调查SKILL.md 给出了一个四层签名链路的诊断示例工作流 → 构建脚本 → 签名脚本 → 实际签名# 第 1 层工作流 echo Secrets available in workflow: echo IDENTITY: ${IDENTITY:SET}${IDENTITY:-UNSET} # 第 2 层构建脚本 echo Env vars in build script: env | grep IDENTITY || echo IDENTITY not in environment # 第 3 层签名脚本 echo Keychain state: security list-keychains security find-identity -v # 第 4 层实际签名 codesign --sign $IDENTITY --verbose4 $APP由此可以逐层定位断裂点例如secrets → workflow ✓, workflow → build ✗从而锁定故障组件。5. 跟踪数据流。当错误发生在调用栈深处时使用完整的反向追踪技术——技能指向 root-cause-tracing.md详见下文辅助技术章节。简要版三步走错误值从哪里产生的谁用错误值调用了这里持续向上追踪直到找到源头在源头修复而不是在症状处修复。第二阶段模式分析先找到模式再修复在确认根因方向后不要急于下手先做对照分析找到可正常工作的示例——在同一代码库中寻找类似的正常代码与出问题的代码作对比与参考实现对比——如果是实现某个模式完整阅读参考实现不要略读要逐行阅读在应用之前彻底理解该模式识别差异——列出正常代码与出问题代码之间的每一个差异无论多小不要假设那不可能有影响理解依赖关系——这个功能需要哪些其他组件需要哪些设置、配置、环境它有哪些隐含假设这一阶段直接对治两类常见错误一知半解照搬模式以及忽略隐含前提导致环境性失败。第三阶段假设与验证科学方法采用严格的科学方法循环提出单一假设——清晰地陈述我认为 X 是根本原因因为 Y写下来要具体不要含糊最小化测试——做出最小的改动来验证假设每次只改一个变量不要同时修复多个问题继续之前先验证——生效了进入第四阶段没生效则提出新假设不要在失败假设上叠加更多修复当你不确定时——直接说我不理解 X不要假装自己知道寻求帮助并做更多调研。单一假设 单变量验证的设计是为了强制思考、防止散弹枪式修复shotgun fixes这是技能防弹化设计的结构性防御之一见 CREATION-LOG.md。第四阶段实施修复根本原因而非症状1. 创建失败的测试用例。先做最简化的复现尽可能用自动化测试没有测试框架就写一次性测试脚本。修复前必须先有测试并建议使用仓库中的 test-driven-development 技能 来编写规范的失败测试。注意技能在 CREATION-LOG 中特别澄清TDD 的最简单的代码原则与调试的找根因原则是两套方法论不要混淆见 CREATION-LOG.md。2. 实施单一修复。只修复已定位的根本原因每次只改一处不做顺便改改的优化不捆绑重构。3. 验证修复。测试通过了吗其他测试没有被破坏吧问题真的解决了吗在宣称成功之前使用 verification-before-completion 技能 做完成前验证。4. 如果修复不起作用——止损规则停下来先数一数已经尝试了几次修复少于 3 次回到第一阶段用新信息重新分析3 次或以上停下来质疑架构见第 5 步没有经过架构讨论不要尝试第 4 次修复。5. 如果 3 次以上修复都失败了质疑架构。以下模式表明存在架构问题每次修复都暴露出新的共享状态/耦合/其他位置的问题修复需要大规模重构才能实现每次修复都在其他地方产生新的症状。此时应停下追问根本性问题这个模式从根本上合理吗我们是不是在惯性驱动下坚持了错误方案应该重构架构还是继续修补症状在尝试更多修复之前和你的搭档讨论。技能明确这不是假设失败——这是架构有误。红线停下来按流程走技能列出了一句式自检清单一旦发现自己正在想以下任何一句就必须停下并回到第一阶段先临时修一下以后再排查试着改改 X 看看行不行一次性改多个地方跑测试看看跳过测试我手动验证大概是 X 的问题让我修一下我不完全理解但这应该能行模式说的是 X但我换个方式用主要问题有这些[未经调查就列出修复方案]没有追踪数据流就提出解决方案再试一次修复已经尝试了 2 次以上每次修复都暴露出不同地方的新问题红线部分是技能防弹化的核心——它把当下感觉完全合理的偷懒瞬间逐字列出制造认知摩擦cognitive friction让使用者看见即止损见 CREATION-LOG.md。搭档发出的信号说明你的方法不对在结对调试或人与 AI 搭档协作中同伴的提醒往往是流程偏离的早期警报信号含义难道不是这样吗你在没有验证的情况下做了假设它能告诉我们……吗你应该先收集证据别猜了你在没有理解的情况下提出修复深入想想要质疑根本性问题而不只是症状我们卡住了沮丧的语气你的方法没有奏效看到这些信号时停下来回到第一阶段。常见借口与对应现实技能以表格形式逐条驳斥了调试中最常见的合理化借口借口现实问题很简单不需要走流程简单问题也有根本原因。对于简单 bug流程很快就能走完。紧急情况没时间走流程系统化调试比反复猜测式修复更快。先试一下再排查第一次修复就定下了基调。从一开始就做对。确认修复有效后再写测试没有测试的修复留不住。先写测试才能证明修复有效。一次修多个问题省时间无法隔离哪个生效了。还会引入新 bug。参考实现太长了我自己改改一知半解必然出 bug。完整阅读。我看出问题了让我修一下看到症状 ≠ 理解根因。再试一次在 2 次以上失败后3 次以上失败 架构问题。质疑模式不要继续修。四阶段速查表阶段关键活动通过标准1. 根因阅读错误、复现、检查变更、收集证据理解了什么出了问题以及为什么2. 模式找到正常示例、对比识别出差异3. 假设提出理论、最小化验证假设被验证或产生新假设4. 实施创建测试、修复、验证bug 已修复测试通过当流程显示找不到根因时如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的则你已经完成了流程记录你排查了什么实施适当的处理措施重试、超时、错误提示添加监控/日志以便后续排查。但技能给出了一个清醒的警告95% 的找不到根因其实是排查不充分。换句话说先怀疑自己的调查深度再归因于外部环境。配套辅助技术同一目录下的深度资料系统化调试不是一个孤立的 SKILL仓库在 skills/systematic-debugging/ 目录下配套了三份可单独引用的技术文档与一份可运行示例分别是根因追踪、纵深防御校验、基于条件的等待。下面逐一展开。根因追踪root-cause-tracingroot-cause-tracing.md 解决Bug 出现在调用栈深处的典型困境如git init在错误目录执行、在错误位置创建文件、用错误路径打开数据库。其核心原则沿着调用链反向追踪直到找到最初的触发点然后在源头修复并配有决策流程图。适用场景错误发生在执行深处不在入口点堆栈跟踪显示很长的调用链不清楚无效数据从哪里来需要找出是哪个测试/代码触发了问题。追踪流程以一个真实的 TypeScript 案例完整演示观察症状Error: git init failed in /Users/jesse/project/packages/core找到直接原因await execFileAsync(git, [init], { cwd: projectDir })问谁调用了它沿调用链上溯WorktreeManager.createSessionWorktree(projectDir, sessionId) → Session.initializeWorkspace() → Session.create() → 测试中的 Project.create()继续向上追踪发现传入的projectDir 空字符串空字符串作为cwd会被解析为process.cwd()——即源代码目录找到最初的触发点setupCoreTest()初始返回{ tempDir: }而测试在beforeEach之前就访问了它。添加堆栈跟踪当无法手动追踪时在危险操作之前注入诊断埋点用new Error().stack捕获完整调用链并记录directory、cwd、process.env.NODE_ENV等上下文// 在有问题的操作之前 async function gitInit(directory: string) { const stack new Error().stack; console.error(DEBUG git init:, { directory, cwd: process.cwd(), nodeEnv: process.env.NODE_ENV, stack, }); await execFileAsync(git, [init], { cwd: directory }); }两个关键技巧在测试中使用console.error()而非 loggerlogger 可能被抑制、不会显示运行时用npm test 21 | grep DEBUG git init捕获输出。分析堆栈跟踪时找测试文件名、找触发调用的行号、识别模式同一个测试同一个参数。找出导致污染的测试当测试期间出现诡异状态但不知道是谁造成时使用同目录下的二分查找脚本 find-polluter.sh./find-polluter.sh .git src/**/*.test.ts该脚本逐个运行匹配的测试文件在第一个污染者即创建了目标文件/目录的测试处停止并输出定位信息。脚本内部做了两处健壮性处理去除./前缀以兼容两种写法以及将**/折叠一次以匹配直接位于基础目录下的文件见 find-polluter.sh 注释。真实案例的最终复盘空 projectDir 事件的五层追踪链、根因顶层变量初始化时访问了空值、修复把tempDir改为 getter在beforeEach之前访问时抛出异常以及同时添加的四层纵深防御详见下文。文档给出实际效果5 层追踪找到根因、源头修复、4 层防御、1847 个测试通过且零污染见 root-cause-tracing.md。纵深防御校验defense-in-depthdefense-in-depth.md 回答一个问题找到根因、修完 bug 之后呢单点校验可能被不同的代码路径、重构或 mock 绕过因此核心原则是在数据经过的每一层都做校验让这个 bug 在结构上不可能发生。单层校验的语义是我们修了这个 bug多层校验的语义是我们让这个 bug 不可能再发生。文档给出四个层级各有分工第 1 层入口校验——在 API 边界拒绝明显无效的输入function createProject(name: string, workingDirectory: string) { if (!workingDirectory || workingDirectory.trim() ) { throw new Error(workingDirectory cannot be empty); } if (!existsSync(workingDirectory)) { throw new Error(workingDirectory does not exist: ${workingDirectory}); } if (!statSync(workingDirectory).isDirectory()) { throw new Error(workingDirectory is not a directory: ${workingDirectory}); } // ... 继续处理 }第 2 层业务逻辑校验——确保数据对当前操作是合理的如工作区初始化要求projectDir非空。第 3 层环境守卫——防止在特定环境中执行危险操作。示例为测试环境下拒绝在临时目录之外执行git initasync function gitInit(directory: string) { // 在测试中拒绝在临时目录之外执行 git init if (process.env.NODE_ENV test) { const normalized normalize(resolve(directory)); const tmpDir normalize(resolve(tmpdir())); if (!normalized.startsWith(tmpDir)) { throw new Error( Refusing git init outside temp dir during tests: ${directory} ); } } // ... 继续处理 }第 4 层调试埋点——记录目录、cwd、堆栈等上下文信息供其他层级失效时事后分析。应用模式发现 bug 后先追踪数据流错误值从哪里产生、在哪里被使用再标注所有检查点数据经过的每一个节点然后在每一层添加校验最后逐层测试尝试绕过第 1 层验证第 2 层能否捕获。文档用空 projectDir 案例说明了四层防御的实际落点Project.create()校验非空/存在/可写 →WorkspaceManager校验 projectDir 非空 →WorktreeManager在测试中拒绝在 tmpdir 之外执行 git init → git init 前记录堆栈跟踪。关键洞察是四层缺一不可不同代码路径绕过入口校验、mock 绕过业务逻辑检查、跨平台边界情况需要环境守卫、调试日志发现结构性误用——每一层都捕获过其他层遗漏的 bug见 defense-in-depth.md。基于条件的等待condition-based-waitingcondition-based-waiting.md 专门对付不稳定测试硬编码延迟setTimeout、sleep本质是在猜测时序会造成竞态条件——在快速机器上通过在高负载或 CI 环境下失败。核心原则等待你真正关心的条件而不是猜测它需要多长时间。适用场景测试中有硬编码延迟测试不稳定时而通过高负载下失败并行运行时测试超时等待异步操作完成。不适用场景测试实际的时序行为如防抖、节流间隔此时若必须用硬编码超时务必注释说明原因。核心模式对照// ❌ 之前猜测时序 await new Promise(r setTimeout(r, 50)); const result getResult(); expect(result).toBeDefined(); // ✅ 之后等待条件满足 await waitFor(() getResult() ! undefined); const result getResult(); expect(result).toBeDefined();常用模式速查场景模式等待事件waitFor(() events.find(e e.type DONE))等待状态waitFor(() machine.state ready)等待数量waitFor(() items.length 5)等待文件waitFor(() fs.existsSync(path))复合条件waitFor(() obj.ready obj.value 10)通用轮询函数实现带超时保护的 10ms 轮询超时即抛出带清晰描述的错误async function waitForT( condition: () T | undefined | null | false, description: string, timeoutMs 5000 ): PromiseT { const startTime Date.now(); while (true) { const result condition(); if (result) return result; if (Date.now() - startTime timeoutMs) { throw new Error(Timeout waiting for ${description} after ${timeoutMs}ms); } await new Promise(r setTimeout(r, 10)); // 每 10ms 轮询一次 } }三个常见错误与修正轮询太频繁setTimeout(check, 1)浪费 CPU改为每 10ms 一次没有超时条件永远不满足时无限循环必须始终设置超时并提供清晰错误信息数据过期在循环外缓存状态应在循环内调用 getter 获取最新数据。何时硬编码超时才是正确的先等待触发条件再基于已知时序而非猜测等待并注释说明原因。文档示例工具每 100ms tick 一次需要 2 次 tick 验证部分输出则先waitForEvent(manager, TOOL_STARTED)再setTimeout(200ms)并注释// 200ms 100ms 间隔的 2 次 tick——有文档说明且有充分理由。完整实现与领域专用辅助函数同目录下的 condition-based-waiting-example.ts 提供了源自真实调试过程Lace 测试基础设施改进的完整可运行实现包含三个带类型定义的领域专用函数waitForEvent(threadManager, threadId, eventType, timeoutMs 5000)——等待指定事件类型首次出现waitForEventCount(threadManager, threadId, eventType, count, timeoutMs 5000)——等待指定数量的事件如等待 2 次AGENT_MESSAGE初始回复 后续延续超时错误中会报告实际收到数量waitForEventMatch(threadManager, threadId, predicate, description, timeoutMs 5000)——按自定义谓词匹配事件数据而非仅匹配类型如等待TOOL_RESULT且e.data.id call_123。文件末尾附带了修复前后对比的真实用例修复前靠setTimeout(300)setTimeout(50)猜测工具启动与结果到达的时序导致expect(toolResults.length).toBe(2)随机失败修复后改用waitForEventCount(threadManager, threadId, TOOL_CALL, 2)等待工具启动、waitForEventCount(..., TOOL_RESULT, 2)等待结果断言稳定通过。文档记录的实际效果修复了 3 个文件中的 15 个不稳定测试通过率 60% → 100%执行时间快了 40%再无竞态条件见 condition-based-waiting.md。技能的诞生与验证从实战中提炼并经受压力测试理解这套方法论如何被打磨成防弹形态能帮助读者更正确地使用它。CREATION-LOG.md 记录了技能的来源从一份真实工程环境中的CLAUDE.md调试框架中提取、按技能创作规范结构化并通过三重手段防弹化语言选择用ALWAYS / NEVER取代应该/尽量用即使看起来更快/即使我似乎很赶时间等措辞封堵压力场景的合理化出口结构防御第一阶段强制前置、单一假设规则、显式失败模式第一次修复失败后的强制动作、反模式清单冗余强化根因命令在概述、使用时机、第一阶段与实施规则中反复出现绝不修症状在不同语境出现 4 次。该技能配套了 4 份验证测试位于同一目录分别覆盖不同压力场景test-academic.md无压力学术场景验证对四阶段流程的完整理解与引用准确性test-pressure-1.md生产故障紧急场景——API 宕机每分钟损失 1.5 万美元、管理者施压、快速修复看起来只需 5 分钟考察是否抵抗捷径test-pressure-2.md沉没成本 疲惫场景——已花 4 小时猜改超时仍不稳定考察能否放弃再试一次回到第一阶段test-pressure-3.md权威与社会压力场景——资深工程师与技术主管都主张直接修复考察是否坚持先查根因。CREATION-LOG 记录了四份测试的结果全部通过未发现合理化行为——包括在明显快速修复诱惑下仍坚持完整流程并找到真正根因、在多层系统失败中逐层追踪到源头、在首次假设失败后停下重新分析而非散弹枪式叠加见 CREATION-LOG.md。这些测试文件本身即可作为团队演练系统化调试的现成素材。实战落地建议把铁律挂在工作区可见处不做根因调查不许提修复方案——对 AI 编程助手与结对搭档同样生效遇到不稳定测试先替换硬编码等待直接复用 condition-based-waiting-example.ts 中的waitForEvent*模式改造现有断言深层调用栈错误先反向追踪再动手参考 root-cause-tracing.md 的五步追踪流程与new Error().stack埋点技巧必要时用 find-polluter.sh 定位污染测试修复完成后不要止步按 defense-in-depth.md 在入口、业务逻辑、环境、调试四个层级补上校验让 bug结构上不可能再发生守住止损线第 2 次修复失败就停止叠加第 3 次失败直接质疑架构——这是该技能最反直觉、也最省时间的一条规则。赞分享AI 技能AI 插件人工智能开发工具【免费下载链接】superpowers-zh AI 编程超能力 · 中文增强版 — superpowers250k ⭐完整汉化 4 个中国原创 skills让 Claude Code / Copilot CLI / Hermes Agent / Cursor / Windsurf / Kiro / Gemini CLI / Qoder 等 26 款 AI 编程工具真正会干活项目地址https://gitcode.com/gh_mirrors/su/superpowers-zh点击查看免费下载相关推荐OpenMetadata 系统化调试实战指南四阶段根因分析法OpenMetadata 系统化调试实战指南四阶段根因分析法 调试 OpenMetadata 时你是否经历过改一个地方碰运气、跑一次测试看结果的循环本数据目录数据血缘数据治理后端MCP 服务Agentic Awesome Skills 之 Systematic Debugging四阶段根因调试方法论实战指南Agentic Awesome Skills 之 Systematic Debugging四阶段根因调试方法论实战指南 本文以 AASAgentic AweAI 技能AI 插件Superpowers系统化调试技能4阶段根因分析方法论——快速定位并解决复杂代码问题的终极指南Superpowers系统化调试技能4阶段根因分析方法论——快速定位并解决复杂代码问题的终极指南 Superpowers是一款强大的Claude Code核心AI 技能AI 插件开发工具上一篇MetaTube让Jellyfin媒体库变得聪明起来的智能管家下一篇专业级NES模拟器Mesen深度解析从游戏怀旧到逆向开发的5大实战场景创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考