gstack /investigate 调试方法论指南：“不调查不修复”铁律与 3 次失败止损机制-创锋一号

gstack /investigate 调试方法论指南：“不调查不修复”铁律与 3 次失败止损机制

【免费下载链接】gstackUse Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA项目地址: https://gitcode.com/GitHub_Trending/gs/gstack

在 AI 辅助编程时代，gstack 的/investigate 技能把系统化调试（Systematic Debugging）变成了一条可执行的流水线：核心铁律是“不调查不修复”（No Fixes Without Root Cause），并配有3 次假设失败即止损的 3-strike rule，外加自动锁定调试作用域，让 AI 智能体像资深工程师一样做根因分析，而不是盲目试错改代码。本文面向新手完整拆解这套调试方法论。

为什么 AI 调试需要“铁律”？

很多 AI 编程工具遇到报错时的第一反应是“猜一个修复、跑一遍、再猜”。短期看似乎有效，长期看却制造了 whack-a-mole（打地鼠式）调试：每个没触及根因的修复，都会让下一个 bug 更难定位。

gstack 对这个问题开出的药方写在 investigate/SKILL.md 的 Iron Law 一节：

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.（未先完成根因调查，禁止任何修复。）

这条铁律被写进技能的指令层，意味着只要触发/investigate，AI 就被强制要求先调查、后修复——这正是 gstack 自称“23 位有主见的专家工具”之一（Debugger）的原因。

一键安装与触发 /investigate 技能

gstack 是 Y Combinator CEO Garry Tan 公开分享的 Claude Code 完整配置集，/investigate是其中负责调试的技能。

克隆安装步骤（需先安装 Claude Code）：

git clone --single-branch --depth 1 https://gitcode.com/GitHub_Trending/gs/gstack.git ~/.claude/skills/gstack cd ~/.claude/skills/gstack && ./setup

安装后，以下自然语言即可触发调试技能（定义在技能触发词 triggers）：

“debug this”（调试一下这个）
“fix this bug”（修复这个 bug）
“why is this broken”（为什么坏了）
“root cause analysis”（根因分析）

更妙的是，gstack 支持主动触发：当你报告 500 错误、贴出堆栈、说“昨天还好好的”时，AI 会自动调用/investigate而不是直接动手改代码。

/investigate 五阶段调试流水线

整个方法论分为五个阶段，每个阶段都有明确产出物，AI 不允许跳步。

阶段一：根因调查（先收集证据，不许有假设）

这是铁律的执行层。AI 必须按顺序完成 5 件事（Phase 1）：

收集症状：读报错信息、堆栈、复现步骤；上下文不够时，一次只问你一个问题；
追踪代码路径：用 Grep 找所有引用，Read 理解逻辑，从症状一路回溯到可疑代码；
检查近期变更：对受影响文件跑git log看最近 20 条提交——回归类 bug 的根因往往就藏在 diff 里；
确定性复现：无法稳定触发就先继续收集证据；
查历史调查记录：同一块代码反复出 bug，是架构异味（architectural smell），不是巧合。

本阶段的强制产出是一句“Root cause hypothesis: ...”（根因假设）——一个具体的、可被证伪的论断，说明哪里坏了、为什么坏。

阶段二：模式分析（对照 6 种经典 bug 模式）

技能内置了一张模式速查表（Phase 2），帮 AI 快速归类问题：

模式	特征签名	排查方向
竞态条件	间歇性、依赖时序	共享状态的并发访问
空值传播	NoMethodError、TypeError	可选值缺少守卫
状态损坏	数据不一致、部分更新	事务、回调、钩子
集成故障	超时、意外响应	外部 API、服务边界
配置漂移	本地正常、预发/线上失败	环境变量、特性开关、数据库状态
陈旧缓存	清缓存后恢复	Redis、CDN、浏览器缓存

如果都对不上，AI 会用 WebSearch 搜索“{框架} {错误类型}”——但有一条安全细则：先脱敏再搜索，剥离主机名、IP、文件路径、客户数据，只搜错误类别，不搜原始报错，防止内部信息外泄。

阶段三：假设检验 + 3 次失败止损 ⚠️

这是整个方法论的精华。铁律不只约束“修复前”，也约束“修复中”：

先验证假设，再写任何修复：在疑似根因处加临时日志、断言，跑复现，看证据是否吻合；
假设错了就回阶段一：收集更多证据，“不要猜”（Do not guess）；
3-strike rule（三次出局规则）：连续 3 个假设全部落空，必须 STOP，不再自行硬试，转而向你呈现三个选项（3-strike rule）：
- A) 继续调查——我有个新假设（需描述清楚）
- B) 升级给人类审查——需要熟悉系统的人
- C) 加日志埋点，等下次复现时捕获

配套还有三条“危险信号”自检（Red flags）：

冒出“先快速修一下”的念头——没有“暂时修一下”这回事，要么修对，要么升级；
还没追踪数据流就提出修复——这是在猜；
每修一处就冒出另一处新问题——说明修错了层次，不是修错了代码。

阶段四：最小化实现（修根因，不修症状）

根因确认后，修复同样有纪律（Phase 4）：

最小 diff：改最少的文件、最少的行，抵制“顺手重构旁边代码”的冲动；
回归测试双向证明：新测试必须在修复前失败（证明测试有意义）、修复后通过（证明修复有效）；
爆炸半径告警：如果修复涉及超过 5 个文件，AI 必须先停下来向你确认——继续、拆分、还是重新想个更聚焦的方案。

阶段五：验证与结构化报告

“修复完成”不等于“修好了”。阶段五（Phase 5）要求新鲜验证：重新复现原始 bug 场景，确认真的修好了，然后输出一份 DEBUG REPORT：

Symptom: 用户观察到了什么 Root cause: 实际错误原因 Fix: 改了什么（附 文件:行号） Evidence: 测试输出、复现验证 Regression test: 新测试的 文件:行号 Status: DONE / DONE_WITH_CONCERNS / BLOCKED

三条收尾铁律（Important Rules）：

3 次以上修复尝试失败 → 停下来质疑架构，而不是换第 4 个假设；
永远不应用无法验证的修复——不能复现确认，就不要上线；
永远不许说“这样应该能修好”——跑测试，拿出证据。

调试作用域自动锁定：防止“手滑改飞”

调试时 AI 最大的风险之一是：修着修着，顺手改了无关代码。gstack 用/freeze 技能解决它——把 Edit/Write 操作限制在指定目录内，越界修改不是警告，而是直接拦截（freeze/SKILL.md）。

/investigate内置了 Scope Lock 机制：形成根因假设后，AI 会自动找到包含受影响文件的最窄目录并冻结编辑范围（Scope Lock）。比如 bug 在src/auth/，本次调试会话就只能改src/auth/下的文件。想解除限制，跑/unfreeze即可。

也就是说，一条“为什么这个接口报 500？”背后，是根因调查 + 作用域隔离 + 假设止损三重防线在同时运转。

经验复利：每次调查都会被记住

/investigate的最后一环是把本次调查记入学习日志（Capture Learnings）：根因摘要、置信度（1-10 分）、受影响文件列表，全部落盘到本地。

下次在同一块代码调试时，技能启动时会自动检索历史调查记录与近期学习，命中时你会看到一行提示：

Prior learning applied: auth-cookie-expiry (confidence 9/10, from 2026-08-12)

同一区域反复出 bug、历史上修过的问题形态，都会直接浮现在新调查里。文件列表还用于陈旧检测——如果相关文件被删了，对应经验会被标记失效。调试经验因此变成了项目级的复利资产。

新手上手：3 个实用建议

直接说症状，让 gstack 自己路由：贴报错 + 一句“昨天还能跑，今天 500”，主动触发机制会帮你进入/investigate，不必记命令；
配合 /freeze 手动锁范围：如果你已经知道问题大概在哪个模块，先/freeze锁住再开查，爆炸半径最小；
认真对待 STOP：3-strike 触发时选 C（加日志埋点）往往性价比最高——间歇性 bug 硬猜十个假设，不如埋点等一次真实复现。

总结

gstack 的/investigate把“怎么调试”从一种个人手感变成了一套可审计的流程：

铁律：不调查不修复，修复必须可验证；
止损：3 个假设失败即停手，升级给人类或转向埋点；
隔离：自动冻结调试作用域，杜绝手滑改飞；
复利：每次根因调查沉淀为项目记忆，越用越懂你的代码库。

想继续了解 gstack 的完整技能体系与项目结构，可以阅读 README.md、ARCHITECTURE.md，以及调试相关的测试用例 test/investigate-freeze-path.test.ts。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析