🎯 学 gstack 的铁律驱动调试系统：不是"改改试试看"的随机实验，而是 Iron Law（Iron Law：根因分析铁律，不找到根因绝不动代码）驱动的四阶段系统性调查——从日志分析、模式匹配到假设验证，在 3 次盲试后自动升级，scope lock 防止失控的"顺便重构"。 ⏱️ 预计时间：35 分钟

[!quote]- 📖 原Skill精要 技能名称：investigate 核心功能：系统化调试与根因分析。四阶段管道：调查→分析→假设→实现。铁律：不找到根因绝不动代码。通过日志分析、模式匹配和假设验证进行系统性调查，3 次盲试后自动升级，scope lock 防止失控重构。 所属体系：gstack 虚拟工程团队 协作关系：发现 Bug 后在修复前使用；修复完成后交给 [[L6-20-自动化测试修复|qa]] 验证

§1 课程概览

investigate 是 gstack 调试体系的核心——它用 Iron Law（不找到根因绝不动代码）替代了开发者"改改试试看"的本能反应。四阶段调查管道（Investigate → Pattern Analysis → Hypothesis Testing → Implement）提供了从证据收集到根因确认的系统化路径。6 种 Bug 模式（竞态条件、状态损坏、边界错误等）作为诊断框架加速问题分类。3-Strike Rule 在 3 次假设失败后强制升级而非继续猜测。Scope Lock 防止调查扩散为"顺便重构"。最终产出结构化 Debug Report，与 /qa、/review、/log、/retro 形成"发现→根因→预防"的闭环。

[!tip] 白话小课堂 investigate 不是"改改试试看"的随机实验——它的 Iron Law 保证了每次修复都有因果逻辑支撑。你得像福尔摩斯一样：先收集所有证据、匹配已知模式、验证假设，确认根因后才动手。3 次猜不中就升级求助，别死磕。

§2 Iron Law——调试的第一原理

"绝不修复你不理解的问题"

Iron Law of gstack investigate:

在没有找到根因（root cause）之前，绝不修改任何一行代码。

为什么需要 Iron Law？

随机修复的问题： → "试试把这个条件改成 >="——为什么？ → "加个 setTimeout 延迟一下"——医不好，只是掩盖症状 → "直接 catch 掉这个异常"——治标不治本 → 每一次盲试都是对代码库的积累性破坏

Iron Law 的价值： → 修复基于理解，不基于猜测 → 每个修复背后有一个已验证的假设 → 代码库的每次修改都有因果逻辑支撑 → 如果发现不了根因——升级而不是猜测

Iron Law 的推论

→ 如果你不能解释为什么 bug 出现 → 你不应该修复它 → 如果你不能解释为什么你的修复有效 → 你不应该提交它 → "It works now" 不是充分的理由——需要 "It works because..."

💡 白话小课堂：你有没有过这种经历——bug 出现了，你不知道为什么，于是试着改了一行代码，诶好了！于是提交。

§3 四阶段调查流程

Phase 1: Investigate（调查——收集所有证据）

目标：建立 bug 的完整事实图景，不做任何判断。

收集清单： → 错误信息（完整、不被截断） → 堆栈跟踪（逐帧，标注应用代码 vs 第三方库） → 日志（错误发生前 30 秒到后 10 秒） → 环境信息（OS / Node 版本 / DB 版本 / 时间） → 复现步骤（或复现尝试记录） → 最近的 git log（错误出现时间窗口内的变更） → 相关 PR / Issue / Slack 讨论（如有）

输出：Investigation Report → 时间线：bug 首次出现 → 发现 → 调查开始 → 证据清单：上面所有项 → 未知项：标记为 TODO——不影响调查继续

Phase 2: Pattern Analysis（模式分析——这是什么类型的 bug？）

将观察到的现象与 6 种已知 bug 模式匹配：

模式	症状特征	常见原因
Race Condition	间歇性、时间相关、并发下出现	缺失锁/原子操作
State Corruption	正确操作后状态错误、积累性恶化	可变全局状态/副作用
Boundary Error	特殊输入值触发、边缘情况	缺少输入验证
Assumption Violation	"这不可能发生"但发生了	隐藏的依赖约束
Resource Lifecycle	连接、文件、内存泄漏	缺失 close/dispose
Environmental	只在特定环境出现	环境差异/配置漂移

多模式可能共存——列出所有匹配的模式及其置信度。

Phase 3: Hypothesis Testing（假设验证——找到真正的根因）

对每个 bug 模式（按置信度排序）：

形成假设："Bug 是由 X 引起的，因为 Y"
设计验证方法： → 添加临时日志到可疑路径 → 写最小复现脚本（不是测试，是诊断工具） → 用工具检查（race detector, memory profiler, etc.） → 代码追踪——从错误点反向追踪调用链
执行验证
确认或排除假设
确认的假设 → 记录为 ROOT CAUSE FOUND
所有假设排除 → 进入 Phase 4（Implement with escalation）

Phase 4: Implement（实现修复——基于已验证的根因）

仅在 ROOT CAUSE FOUND 后才能进入此阶段。

修复原则： → 修复只解决根因，不涉及其他 → 修复是最小化的——只改必要的代码 → 修复包含为什么有效的注释 → Scope Lock 生效——不趁机扩大变更范围 → 提交信息格式：fix: <根因> — <修复方式>

回归验证： → 验证原始复现步骤不再触发 bug → 验证相关测试仍然通过 → 如有必要 → 添加回归测试

🔑 核心秘诀：四个阶段中，Phase 1（调查）被新手严重低估。

§4 6 种 Bug 模式深度解读

Race Condition（竞态条件）

症状：同样操作有时成功有时失败，多用户环境更频繁验证：用 race detector / 并发压力测试 / 逻辑时钟分析关键检查：读-改-写序列是否原子化？共享状态是否有保护？

State Corruption（状态损坏）

症状：操作正确但后续操作读取到错误状态，累积性恶化验证：状态快照对比 / 状态变更日志 / 状态所有权追踪关键检查：是否存在隐式的状态共享？是否有副作用在预期之外？

Boundary Error（边界错误）

症状：正常输入没问题，特殊值崩溃 / 空/零/负/超长/Unicode 验证：边界值注入 / fuzz testing / 输入空间映射关键检查：所有外部输入是否都经过验证？假设是否显式？

Assumption Violation（假设违反）

症状：代码中声明"绝不可能"的情况发生了验证：追溯假设的来源——文档？测试？口头约定？关键检查：这个假设在当前系统架构中仍然成立吗？变了吗？

Resource Lifecycle（资源生命周期）

症状：随运行时间增加而恶化的性能或功能问题验证：资源泄漏检测器 / 监控内存/文件描述符/连接数关键检查：每次获取资源后是否都有对应的释放？异常路径呢？

Environmental（环境差异）

症状：开发环境没问题，生产环境有问题（或反之）验证：环境变量对比 / 依赖版本对比 / 配置对比关键检查：CI 环境与生产环境的差异点列表

§5 3 次推测规则——何时放弃自己修

3-Strike Rule（三次推测规则）

当 Phase 3 中假设验证无法确认根因时：

Strike 1: 第一个假设被排除 → 继续调查，形成第二个假设

Strike 2: 第二个假设被排除 → 扩大调查范围，读取更多相关代码

Strike 3: 第三个假设被排除 → 停止。不再形成第四个假设。 → 进入升级流程。

为什么是 3 次？

→ 每次假设形成都消耗认知资源 → 3 次猜测都不对 → 你的心智模型有根本性错误 → 继续猜测 = 基于错误的模型做更多错误预测 → 需要外力——换一个视角、换一个模型

升级流程（3 次后）

生成 Debug Report（见下文）
建议： → 添加更详细的日志到关键路径 → 缩小复现范围（二分法排除） → 寻求领域专家帮助 → 使用更专业的调试工具
永不继续猜测

⚠️ 避坑指南： 3 次猜测规则最难遵守的地方——当你已经投入了 2 个小时调查时，第 3 次猜到"差不多对"的时候，你会想"再猜一次也许就对了"。但这种心态和赌徒的"下一把一定赢"没有本质区别。

§6 Scope Lock——调查不变成重构

Scope Lock Mechanism

问题场景： → 你在调查一个缓存失效 bug → 发现缓存模块的代码组织有点乱 → "我顺便重构一下缓存模块..." → 30 分钟后你不记得原来的 bug 是什么了

Scope Lock 防止这种失控：

锁定规则

调查开始时冻结 scope： → 记录当前调查的 bug 签名（症状描述） → 记录涉及的初始文件/模块列表 → 这个 scope 在调查期间不变
扩大 scope 需要显式声明： → "扩大 scope 到 <新模块>，因为 <与根因的逻辑关系>" → 每扩大一次记一次 scope 扩张日志
"顺便"原则： → 发现了与当前 bug 无关的问题？ → 不修。记录到后续追踪清单。 → 输出格式：[FOLLOW-UP] <文件>:<行> — <发现> → 这些条目不会丢失——它们在 Debug Report 中

Scope Lock 的价值

→ 保持焦点——你只有一个任务 → 不引入新的变量——修复后可以确定是哪个改动解决了问题 → 不制造新的 bug——每个"顺便"都可能引入新的问题 → 让你的 PR 可以审查——一个清晰目的的改动

§7 Debug Report 结构

Standard Debug Report Format

调查完成后生成结构化报告：

Debug Report: <bug 简短标题>

Symptom（症状）

<用户/系统观察到的具体异常行为>

Evidence（证据）

错误信息 + 完整堆栈
日志片段（时间窗口）
环境信息
复现步骤（或复现失败记录）
触发条件（什么输入/状态/时间）

Pattern Match（模式匹配）

Primary: <最匹配的 bug 模式> (confidence: X%)
Secondary: <次匹配的模式> (if any)
Reason: <为什么匹配>

Root Cause（根因）

[如果找到] <具体代码位置 + 因果链> Cause: <直接原因> Why it wasn't caught: <为什么测试/审查没发现>

[如果未找到] ROOT CAUSE NOT FOUND after 3 strikes Hypotheses tested:

<假设 1> — excluded because <证据>
<假设 2> — excluded because <证据>
<假设 3> — excluded because <证据> Recommendation: <升级建议>

Fix（修复——如果找到根因）

Commit:
Change: <文件:行> — <做了什么>
Why it works: <因果解释>
Verification: <回归测试结果>

Follow-ups（后续追踪）

<与调查中发现但应单独处理的问题>

§8 与其他 gstack 系统的协同

/qa 集成

→ /qa 发现复杂失败 → 建议 /investigate → /investigate 找到根因并用 /qa 验证修复 → /qa 生成的回归测试保护修复

/review 集成

→ /review 的审查清单帮助预防未来同类 bug → /investigate 发现的 root cause 模式反馈给审查清单 → 形成"发现→根因→预防"的闭环

/log 集成

→ 每个 Debug Report 写入项目日志 → 累积的 Debug Reports 形成 bug 模式知识库 → 未来类似 bug 可以参考历史 Debug Reports

/retro 集成

→ Debug Report 中的 root cause 分类汇总 → 跨项目的 bug 模式趋势 → 为团队回顾提供数据

§9 结构拆解

investigate 结构模板

核心特征

管理对象: Bug 的根因（root cause）与已验证的修复方案
核心原则: Iron Law——在没有找到根因之前，绝不修改任何一行代码
关键设计: 四阶段调查管道 + 6 种 Bug 模式匹配 + 3-Strike Rule 升级机制 + Scope Lock 防失控

通用结构

证据收集层 (Phase 1): 错误信息 → 堆栈跟踪 → 日志 → 环境信息 → 复现步骤 → git log
模式匹配层 (Phase 2): 6 种 Bug 模式诊断框架（Race Condition / State Corruption / Boundary Error / Assumption Violation / Resource Lifecycle / Environmental）
假设验证层 (Phase 3): 形成假设 → 设计验证方法 → 执行验证 → 确认/排除 → 3 次失败后强制升级
修复实现层 (Phase 4): 最小化修复 → 因果注释 → Scope Lock → 回归验证 → fix: <根因> — <修复方式>
报告归档层: Debug Report（Symptom → Evidence → Pattern → Root Cause → Fix → Follow-ups）
协同闭环: /qa 验证修复 → /review 反馈预防 → /log 积累知识库 → /retro 趋势分析

§9.5 电商 Skill 案例：双11秒杀超卖线上故障排查

🛒 实战案例：双11当天凌晨00:05，某电商平台爆发秒杀超卖故障——1000件库存的限量商品被卖出了1123件。运维团队已紧急下线秒杀功能止损，但根因未知。使用/investigate启动四阶段调查流程，追查超卖的根因。

Phase 1 证据收集：收集所有证据——错误日志（inventory-service在00:03-00:05间输出47次"Stock validation failed after deduction"警告）、数据库查询（SELECT COUNT(*) FROM orders WHERE product_id=8888 AND created_at BETWEEN '2026-11-11 00:00:00' AND '2026-11-11 00:06:00'→返回1123行，超卖123件）、git log（最近一次库存模块变更为3天前PR #2045 "优化库存扣减性能"）、Redis库存键（GET flash-sale:8888:stock→返回0，但Redis DECR从未返回负数——说明扣减操作确实减到了0但没有保护）。关键证据：47次"Stock validation failed after deduction"警告的时序——00:03:00开始出现，到00:05:00达到峰值（每秒12次）。

Phase 2 模式匹配：匹配6种Bug模式——特征"同时发生的操作互相干扰"→Race Condition（竞态条件，置信度HIGH）。进一步分析：Redis DECR flash-sale:8888:stock是原子操作（返回扣减后的值），但代码在DECR和写入订单数据库之间没有事务保护——流程是const remaining = await redis.decr(key)→if (remaining >= 0) { await createOrder(...) } else { await redis.incr(key); throw new Error("Sold out") }。在高并发下（同一毫秒数百个请求）——多个请求同时DECR→所有请求的remaining都>=0（因为没有请求看到负值——每个DECR是独立的原子操作，1000个库存可能被1500个DECR操作同时消耗）→都执行createOrder→最终1123个订单创建成功。

Phase 3 假设验证：假设"PR #2045中的‘性能优化’引入了竞态条件"→验证：git diff PR #2045显示原代码使用的是Redis Lua脚本（EVAL "if redis.call('get', KEYS[1]) > '0' then return redis.call('decr', KEYS[1]) else return -1 end"——在单个原子操作中同时检查+扣减），但被替换为独立DECR操作以"减少Redis往返次数"——但丧失了检查+扣减的原子性。在staging环境复现——模拟1000并发请求/秒→原Lua脚本超卖0件，新独立DECR超卖120件（与生产环境1123件吻合）。根因确认：PR #2045将原子检查+扣减操作拆分为独立DECR，引入了check-then-act竞态窗口。

Phase 4 修复实现与验证：回退到Redis Lua脚本方案→EVAL "local stock = redis.call('get', KEYS[1]); if tonumber(stock) > 0 then return redis.call('decr', KEYS[1]) else return -1 end" 1 flash-sale:8888:stock→在staging验证1000并发请求→超卖0件✓。修复commit fix: Race Condition in flash sale stock deduction — Redis DECR lacks atomic check-before-deduct, restored Lua script for atomicity。同时添加补偿机制——SELECT COUNT(*) FROM orders WHERE product_id=X在秒杀结束后自动校验库存一致性。Debug Report归档到/log供后续防止类似模式出现。

🔑 启示：超卖故障的根因诊断揭示了一个普遍陷阱——"性能优化"如果将原子操作拆分为独立操作，必须在新的粒度层重新建立原子性保证。PR #2045的优化初衷是合理的（减少Redis往返次数），但它不理解原代码使用Lua脚本的原子性意图——在旧的原子范围内拆出DECR后，必须在新的DECR层建立新的原子性保证（但开发者没有）。Iron Law"在不理解根因之前不修复任何代码"在这里的对应推论是"在不理解原代码设计意图之前不进行性能优化"。

[!info] 参考来源 Bug 调查方法论参考了 Google SRE Workbook 的事后故障分析文化和 Brendan Gregg's Systems Performance 的系统诊断方法。

§10 掌握检验

Q1：Iron Law 的核心要求是什么？

A) 在没有找到根因之前不修改任何代码
B) 至少读 3 遍堆栈跟踪才能开始修复
C) 所有 bug 必须由资深工程师确认
D) 修复后必须运行性能测试

Q2：以下哪个症状最符合"Resource Lifecycle"类型的 bug？

A) 用户 A 和用户 B 同时下单，一个订单被覆盖
B) 系统运行 72 小时后响应变慢，重启后恢复正常
C) 输入用户名为空字符串时系统崩溃
D) 只在生产环境出现，开发环境无法复现

Q3：3-Strike Rule 中，为什么第 3 次猜测失败后应该进入升级流程而非继续猜第 4 次？请从认知心理学和工程资源两个角度解释。

Q4：Scope Lock 中，如果调查一个缓存失效的 bug 时发现缓存模块存在代码组织混乱的问题，Scope Lock 的处理方式是什么？请具体描述从"发现"到"记录"到"后续处理"的完整流程。

Q5：Debug Report 中 "Why it wasn't caught" 部分的价值是什么？请具体说明这个信息如何反馈到 review 审查清单、QA 测试流程、和 CI/CD 门禁中——形成"发现→根因→预防"的闭环。

Q6：你接手了一个遗留系统的 bug：订单金额有时会随机变成 0。Phase 1 调查发现 bug 出现的时间点周围没有相关代码变更（git log 显示最近修改是 3 个月前）。基于这个信息，你应该优先匹配哪种 bug 模式？为什么排除"最近代码变更引入"的可能性后，调查方向应该如何调整？

§11 答案

点击查看答案

Q1：A —— Iron Law 是 investigate 的第一原理：在没有找到根因之前，绝不修改任何一行代码。

Q2：B —— Resource Lifecycle 的特征是"随时间恶化、重启恢复"——这正是资源泄漏（连接未关闭、内存未回收）的典型症状。

Q3：认知心理学角度——人的前 3 个假设通常覆盖了 80% 的可能原因空间。如果 3 个都不对，说明你的心智模型有根本性盲区——继续猜只是在这个盲区内重复错误预测，每次猜错的概率在递增而非递减。工程资源角度——每次假设验证需要写诊断代码、跑测试、等结果，平均耗时 20-40 分钟。3 次已经花了 1-2 小时——如果此时代码还没找到，继续的边际收益急剧下降。升级引入新的视角（同事、更专业工具）的成本低于继续盲目猜测的机会成本。

Q4：发现后：①不修缓存模块的问题，立即记录为 [FOLLOW-UP] src/cache/invalidator.ts:45-87 — 缓存失效逻辑和缓存策略耦合在一个函数中，圈复杂度 22，应拆分为失效触发+策略执行；②在 Debug Report 的 Follow-ups 章节中保留这条记录；③回到原 bug 的调查中，将 scope 严格限制在"为什么这个具体请求的缓存没失效"——不扩大到"如何重构整个缓存模块"。后续处理：Follow-up 记录不会丢失——它们在 Debug Report 中，可以在修复完这个 bug 后单独开 PR 处理。

Q5："Why it wasn't caught" 桥接了调试和流程改进：①如果根因是并发竞争但单元测试没发现 → 反馈给 review 审查清单：增强"并发操作必须有并发测试"的检查项。②如果根因是边界值零输入但测试没用零测试 → 反馈给 QA 流程：自动生成的测试用例必须包含零/空/负值。③如果根因是 CI 环境与生产环境配置不一致 → 反馈给 CI/CD 门禁：增加配置漂移检查。"发现→根因→预防"闭环的价值在于：修了一个 bug 只能堵住这个具体的洞，但升级了流程能堵住未来所有类似的洞。

Q6：排除"最近代码变更引入"后，优先匹配 Environmental（环境差异）或 Assumption Violation（假设违反）。Environmental——可能是生产环境的数据库配置、中间件版本、或某个服务的定时任务在 3 个月前没有但在当前条件下触发了。Assumption Violation——代码中可能假设"订单金额计算后不会为 0"，但这个假设在某些组合条件下被打破（如优惠券覆盖全额 + 运费为 0 的特殊场景）。调查方向调整：从"最近改了什么"转到"什么环境/输入组合能让金额变成 0"——变时间线调查为因果链调查。

（5/6 通过）