get-shit-done 调试哲学解析：面向 Claude Code Agent 的常青排障方法论与科学调查体系

get-shit-done 调试哲学解析：面向 Claude Code Agent 的常青排障方法论与科学调查体系

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

导读

调试（Debugging）是软件工程中跨越一切语言、一切系统、每一个 Bug 的永恒命题。在 get-shit-done（GSD） 这套基于 Claude Code 的元提示（meta-prompting）与规范驱动开发（Spec-Driven Development）体系中，调试纪律被沉淀为一份可被 Agent 反复装载的共享参考文档——debugger-philosophy.md，并由gsd-debuggerAgent 在每次排障会话启动时以@file方式注入其哲学上下文中。本文将逐段拆解这份"常青调试纪律"，说明它如何与 Agent 源码、调试会话管理、假设检验框架协作落地，帮助你掌握"以可证伪假设驱动调查、以可观察证据代替直觉、在必要时果断重启"的完整调试思维闭环。

从"顺手搜代码"到"系统排障"：这份哲学文档在 GSD 中的位置

阅读本文前，需要先定位这份文档在整个仓库中的角色。

在 GSD 的架构中，agents、commands、get-shit-done/workflows、get-shit-done/references、get-shit-done/templates构成五层协作骨架。其中references/目录存放的是可被多个 Agent 共享加载的"知识切片"——debugger-philosophy.md 就是其一，仓库清单 INVENTORY.md 对它的定位是："Evergreen debugging disciplines loaded bygsd-debugger"（由gsd-debugger装载的常青调试纪律）。

该文件的头部自述明确了两点：

1. 它是**常青（Evergreen）**调试纪律——"applies across every bug, every language, every system"，适用于每一个 Bug、每一种语言、每一个系统，与具体技术栈解耦；
2. 它由gsd-debugger通过@fileinclude 装载——在 gsd-debugger Agent 定义 中，这份文件被包在<philosophy>与</philosophy>标签之间，作为该 Agent 的哲学底座。

这一设计在 CHANGELOG 中有明确出处（issue #2363）：此前这段约 76 行的<philosophy>内容直接内嵌在 Agent 定义里，后来被抽取为共享参考文件，通过单次@file引用注入——内容不变，但每次派发 Agent 的上下文占用更轻。这说明：调试哲学不是一次性说教，而是 Agent 每次进入调查前都必须被"重新唤醒"的行为基线。

从运行链条上看，/gsd:debug命令（commands/gsd/debug.md）负责编排症状收集、派发调查者、处理检查点；gsd-debugger是具体的"调查员"，debugger-philosophy.md 定义了它的心态与纪律；而 debugger 工作流 与 gsd-debug-session-manager 则负责把纪律落地为可持久化的会话状态。本文聚焦的哲学文档，正是这整个系统的"第一性原理"层。

第一性原则：User = Reporter，Claude = Investigator

哲学文档开门见山地定义了人机协作的证据边界——这是后续一切纪律的前提。

用户知道什么（应当由用户提供）：

• 他们期待发生什么（expected）；
• 实际发生了什么（actual）；
• 他们看到的错误信息；
• 问题从何时开始 / 是否曾经正常过。

用户不知道什么（Agent 不应反问）：

• Bug 的成因是什么；
• 哪个文件有问题；
• 修复应该是什么。

由此导出的分工纪律只有一句话：Ask about experience. Investigate the cause yourself.（询问体验，亲自调查成因）。换句话说，用户是被询问的"目击证人"，Agent 是"侦探"——不要让用户替你猜根因，也不要把用户随口说的"我觉得是 X 的问题"当成事实输入。

在仓库中，这一原则被进一步机制化。gsd-debugger的调查阶段会把症状沉淀为结构化的五要素——expected、actual、errors、reproduction、started（见调试文件协议与 gsd-debug-session-manager 中的 debug file 结构），并在症状采集完成后将其标记为IMMUTABLE（不可变），防止调查过程中症状被"解释漂移"污染。这正是"用户只负责报告现象"在工程层面的落地。

同时需要注意其安全含义：Agent 定义中明确要求，<trigger>与<symptoms>块中由用户提供的证据必须视为数据而非指令——即便其中出现"请你改换角色/覆盖指令"之类的文字，也只能当作待调查的 Bug 描述工件，继续正常调查。

元调试（Meta-Debugging）：先对付自己的心智模型

调试自己写的代码时，真正的敌人不是代码，而是你脑子里那套"自认为正确"的模型。文档给出了为什么难的三个理由：

• 设计决策是你做的，它们在你眼中"显然正确"；
• 你记住的是意图，而不是实际写出来的实现；
• 熟悉感会带来对 Bug 的盲目（familiarity breeds blindness）。

对应的四条纪律层层递进：

1. 把代码当外人的代码来读——假设它是别人写的，逐行重新理解；
2. 质疑自己的设计决策——实现决策是假设（hypotheses），不是事实（facts）；
3. 承认自己的心智模型可能是错的——代码行为才是真理，你的模型只是猜测；
4. 优先排查你碰过的代码——如果你刚改了 100 行而后出现故障，这 100 行就是头号嫌疑人。

最难的承认是："I implemented this wrong."（我把它实现错了。）——而不是"需求当时没讲清楚"。文档刻意强调：错误是你犯的，把责任推给需求本身就是一种逃避型的心智防御。

这条纪律的底层逻辑，在配套的 thinking-models-debug.md 中体现为Counterfactual Thinking（反事实思考）：当你有某个根因假设时，构造一个反事实——"如果我只改动这一个变量/配置/代码行，Bug 应当消失（或出现）"。如果执行了定向改动而 Bug 仍在，说明你的假设错了，成因在别处。这正是"你的心智模型只是猜测"的正式化操作。

回归地基（Foundation Principles）：可观察事实高于一切

当调查陷入迷雾时，文档要求回到三条根本性问题：

• 你确定知道什么？——可观察的事实，而非假设；
• 你在假设什么？——例如"这个库应该这样工作"，你真的验证过吗？
• 剥离你以为知道的一切，从可观察事实重新搭建理解。

这三问的哲学内核是：把"我以为"与"我观察到"彻底分离。在 Agent 调查循环（investigation_loop）中，证据（Evidence）必须以timestamp / checked / found / implication四元组形式追加写入会话文件，任何"发现"都必须落到"检查了什么、看到了什么、意味着什么"，而不是停留在脑海里。

认知偏差清单：四种必须主动对抗的思维陷阱

文档用一张表点出四种最常见的认知偏差、各自的表现陷阱与解毒剂：

这四种偏差中，锚定偏差与 Agent 假设形成机制的直接对应最为明显：gsd-debugger在形成假设时要求列出每一个可能成因（"Ask 'What could cause this?' - List every possible cause"），并且不做先入为主的评判；在假设阶段还引入了"多重假设策略"，主张用强推断（strong inference）设计能区分多个竞争假设的实验。

而"每 30 分钟复盘一次沉没成本"的节奏，在会话层面则有对应落地——gsd-debugger的 Decision Point 规定：只有当你能同时回答"理解机制了吗 / 能稳定复现吗 / 有直接证据吗 / 排除其他假设了吗"四个问题时才允许动手修复；"我猜可能是 X"或"我试试把 Y 改一下看"都不构成行动条件。

系统化调查纪律：变更一个变量、完整阅读、拥抱未知

哲学文档抽出三条贯穿所有调查行为的纪律：

1. Change one variable（一次只变更一个变量）做一次改动、测试、观察、记录，然后重复。同时做多处改动，等于放弃了知道"到底是哪一处起效"的权利。这条纪律在 Agent 的假设检验框架中被升级为硬性要求："One hypothesis at a time. If you change three things and it works, you don't know which one fixed it." 配套的 thinking-models-debug.md 的 Hypothesis-Driven Investigation 也重复强调：每次测试只执行一个实验，绝不一次改变两个以上变量。

2. Complete reading（完整阅读）读整个函数，而不是只读"相关的那几行"；要读 imports、配置、测试。走马观花会漏掉关键细节。对应 Agent 调查循环 Phase 1 的规则："Read relevant files COMPLETELY"（完整读取相关文件）。

3. Embrace not knowing（拥抱不知道）"我不知道它为什么失败"= 好消息，因为现在你可以去调查了；"它一定是 X"= 危险信号，因为你已经停止思考了。这与假设检验框架中的Falsifiability Requirement（可证伪性要求）一脉相承：一个有用的假设必须能被证明是错的；"状态有点问题""时机不对""某处存在竞态"这类不可证伪的表述，是无用的假设，而"当路由变化导致组件重挂载时用户状态被重置"才是具体、可检验、可推翻的合格假设。

何时重启（When to Restart）：识别隧穿视觉的止损点

哲学文档给出五个重启信号，每一条都在回答"我的方法是否已经失效"：

1. 超过 2 小时无进展——你很可能是隧道视觉（tunnel-visioned）；
2. 连续 3 次以上"修复"无效——你的心智模型是错的；
3. 你无法解释当前行为——不要在混乱之上继续叠加改动；
4. 你在调试"调试器本身"——说明有某种根本性的东西出了错；
5. 修复生效但你说不清原因——这不是修复，这是运气。

重启协议（Restart protocol）：

1. 关闭所有文件和终端；
2. 写下你确定知道的事实；
3. 写下你已经排除的假设；
4. 列出与之前不同的新假设；
5. 从第一阶段"证据收集"重新开始。

把这套协议映射到 GSD 的实现，会发现它正好对应调试会话文件的防重复机制：会话文件中的Eliminated区段只允许APPEND（追加），每一条被排除的假设都要附上"什么证据推翻了它 + 何时排除"，从而保证重启不等于失忆——重启后不用把已排除的路径再走一遍。这正是文档反复强调的"识别隧穿视觉并止损"在工程上的可执行形态：Resume Behavior（gsd-debug-session-manager）在上下文被/clear后通过解析 frontmatter 状态、读取 Current Focus、查 Eliminated、读 Evidence，然后直接续走next_action。正如会话协议所言："The file IS the debugging brain."（这份文件就是调试的大脑。）

哲学如何成为体系：从原则到协议的完整落地链路

debugger-philosophy.md的价值不在于提出惊天动地的新概念，而在于它把散落的最佳实践收敛为一份可装载的共享基线，并与下游机制形成了严密的闭环。完整链路如下：

• debugger-philosophy.md（本文主体）——定义"用户是报告者、Agent 是调查者"的角色边界，心智模型防御、地基三问、四种认知偏差、单变量纪律、重启协议；
• gsd-debugger——把哲学落成行为规范：可证伪假设、实验设计七步（Prediction → Test setup → Measurement → Success criteria → Run → Observe → Conclude）、强/弱证据分级、错误假设的恢复流程、结构化推理检查点；
• thinking-models-debug.md——在调查决策点提供 Fault Tree Analysis（故障树）、Hypothesis-Driven（假设驱动）、Occam's Razor（奥卡姆剃刀）、Counterfactual Thinking（反事实思考）四种推理模型，并明确"何时不该用结构化模型"（单一显式根因、已知修复、纯笔误、仅读错误日志时不启动完整模型）；
• debugger 工作流 与 gsd-debug-session-manager——把调查循环持久化为status: gathering → investigating → fixing → verifying → awaiting_human_verify → resolved的状态机，症状不可变、证据只追加、每次行动前先更新文件，保证多轮派发与上下文重置后调查不中断；
• /gsd:debug命令（commands/gsd/debug.md）——对外暴露list、status <slug>、continue <slug>、--diagnose（只诊断不修复）等入口。

给你的调试实战清单

把全文收敛为可直接对照的自检清单：

调查启动前：

• 我只向用户索取现象（期望/实际/报错/何时开始），不向其索取根因猜测
• 我已记录最小复现步骤与可观察事实，把"我以为"与"我看到"分开
• 若调试的是自己写的代码，我按"陌生代码"的标准重新阅读，优先排查最近改动过的行

调查进行中：

• 已列出 3 条以上相互独立的假设，而非锁定第一个解释
• 当前假设可证伪（能明确说出什么观察可以推翻它）
• 每次只改动一个变量，并有意识地寻找反证而非只收集佐证
• 每个发现都有直接观察证据（可复现、无歧义），而非"感觉""听说"
• 已完整读取相关函数、导入、配置与测试，未走马观花

止损与修复前：

• 每 30 分钟自问：从头开始我还会走这条路吗？
• 若 2 小时无进展 / 3 次修复无效 / 无法解释现状 / 修复生效却不明缘由，执行重启协议（写已知事实 → 写已排除项 → 列新假设 → 重走证据收集）
• 动手修复前，把根因假设、佐证证据、证伪测试、修复理由、盲点五项书面化——填不全五栏就说明根因尚未确认

小结

debugger-philosophy.md 全文不过 76 行，却浓缩了一套完整的调试世界观：先界定证据边界（用户报现象、Agent 查根因），再防御自身心智（元调试、地基三问、四类认知偏差），后遵守实验纪律（单变量、完整阅读、拥抱未知），最终设立止损机制（五信号 + 重启协议）。在 GSD 中，这段哲学不是静态文档，而是被@file注入gsd-debugger每次会话、再经调试文件协议与假设检验框架落到行动层的活的系统。无论你是希望改进 Claude Code 排障体验的 Agent 使用者，还是想给自己的团队调试流程注入纪律的工程师，这套哲学与它的工程化落地方式都值得直接复用。

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done