gstack /investigate 调试方法论指南“不调查不修复”铁律与 3 次失败止损机制【免费下载链接】gstackUse Garry Tans 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.未先完成根因调查禁止任何修复。这条铁律被写进技能的指令层意味着只要触发/investigateAI 就被强制要求先调查、后修复——这正是 gstack 自称“23 位有主见的专家工具”之一Debugger的原因。一键安装与触发 /investigate 技能gstack 是 Y Combinator CEO Garry Tan 公开分享的 Claude Code 完整配置集/investigate是其中负责调试的技能。克隆安装步骤需先安装 Claude Codegit 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 guess3-strike rule三次出局规则连续 3 个假设全部落空必须 STOP不再自行硬试转而向你呈现三个选项3-strike ruleA) 继续调查——我有个新假设需描述清楚B) 升级给人类审查——需要熟悉系统的人C) 加日志埋点等下次复现时捕获配套还有三条“危险信号”自检Red flags冒出“先快速修一下”的念头——没有“暂时修一下”这回事要么修对要么升级还没追踪数据流就提出修复——这是在猜每修一处就冒出另一处新问题——说明修错了层次不是修错了代码。阶段四最小化实现修根因不修症状根因确认后修复同样有纪律Phase 4最小 diff改最少的文件、最少的行抵制“顺手重构旁边代码”的冲动回归测试双向证明新测试必须在修复前失败证明测试有意义、修复后通过证明修复有效爆炸半径告警如果修复涉及超过 5 个文件AI 必须先停下来向你确认——继续、拆分、还是重新想个更聚焦的方案。阶段五验证与结构化报告“修复完成”不等于“修好了”。阶段五Phase 5要求新鲜验证重新复现原始 bug 场景确认真的修好了然后输出一份 DEBUG REPORTSymptom: 用户观察到了什么 Root cause: 实际错误原因 Fix: 改了什么附 文件:行号 Evidence: 测试输出、复现验证 Regression test: 新测试的 文件:行号 Status: DONE / DONE_WITH_CONCERNS / BLOCKED三条收尾铁律Important Rules3 次以上修复尝试失败 → 停下来质疑架构而不是换第 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锁住再开查爆炸半径最小认真对待 STOP3-strike 触发时选 C加日志埋点往往性价比最高——间歇性 bug 硬猜十个假设不如埋点等一次真实复现。总结gstack 的/investigate把“怎么调试”从一种个人手感变成了一套可审计的流程铁律不调查不修复修复必须可验证止损3 个假设失败即停手升级给人类或转向埋点隔离自动冻结调试作用域杜绝手滑改飞复利每次根因调查沉淀为项目记忆越用越懂你的代码库。想继续了解 gstack 的完整技能体系与项目结构可以阅读 README.md、ARCHITECTURE.md以及调试相关的测试用例 test/investigate-freeze-path.test.ts。【免费下载链接】gstackUse Garry Tans 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辅助生成（AIGC），仅供参考