Debugging 是一个用于系统化排查缺陷的技能,其口号是“假设、测试、学习、重复”。它的目标不是凭直觉乱改代码,而是通过可追踪的假设与测试,逐步收敛到根本原因。
用途
当出现以下情况时适合使用该技能:某件事没有按预期工作;出现难以解释的神秘行为;需要诊断性能问题;遇到“在我机器上是好的”这类环境相关情况。
调试循环
核心流程为:OBSERVE(观察)→ HYPOTHESIZE(假设)→ TEST(测试)→ LEARN(学习)→ 重复或进入 FIX(修复)。终止状态有三种:FIX 表示缺陷已解决;WONTFIX 表示该行为是有意为之;DEFER 表示当前不处理。
观察阶段
在猜测之前先收集事实。观察记录包含:symptom(可观察的问题)、context(何时发生)、expected(本应发生什么)、evidence(错误信息原文、相关日志、复现步骤)、constraints(确定已知的事实)、ruled_out(已排除的可能性)。
假设跟踪
每个假设使用唯一编号,例如 hyp-001,包含 claim(认为问题由什么引起)、confidence(high/medium/low)、if_true(若假设成立应观察到什么、修改 X 应能修复)、test(要尝试的动作与预期结果)、result(confirmed/refuted/inconclusive 及实际观察)、learned(由此得到的认识)。
测试记录
每个测试使用唯一编号,例如 test-001,关联到具体假设,记录 action(做了什么)、before(测试前系统状态)、after(测试后系统状态)、result(confirmed/refuted/inconclusive)、learned(现在知道了什么)。
结构化模式
观察模式字段包括:symptom(必填,可观察问题)、expected(必填,本应发生什么)、error_message(错误原文)、logs(相关日志)、steps_to_reproduce(如何触发)、constraints(已知事实)、ruled_out(已排除项)。
假设模式字段包括:id(必填,唯一标识)、claim(必填,认为哪里出错)、test(必填,如何验证)、confidence(高/中/低)、if_true(预期观察)、result(测试结果)、learned(获得的洞见)。
测试模式字段包括:id(必填,唯一标识)、hypothesis(必填,对应哪个假设)、action(必填,尝试了什么)、result(必填,confirmed/refuted/inconclusive)、before(之前状态)、after(之后状态)、learned(洞见)。
核心文件
DEBUG.yml 保存当前调试会话;HYPOTHESES.md 记录所有假设及其状态;TESTS.md 是测试日志;ROOT_CAUSE.md 保存最终分析。
命令
DEBUG [symptom] 启动调试会话;OBSERVE [fact] 记录观察;HYPOTHESIZE [claim] 提出假设;TEST [action] 记录测试;LEARN [insight] 记录所学;ROOT-CAUSE [explanation] 记录根本原因。
面向缺陷的科学方法
其步骤为:观察到底发生了什么;提问为什么会发生;形成可检验的解释;预测若假设成立会看到什么;通过测试确认或反驳;分析学到了什么;迭代产生新假设或修复。
调试技巧
二分查找:在较大范围内定位缺陷,先找已知正常状态与已知异常状态,检查中间点,重复直至找到。橡皮鸭:在卡住时详细解释问题,把详细观察写入 DEBUG.yml,迫使自己阐明假设。最小复现:在复杂系统中原因不明时,简化直到缺陷被隔离。Git Bisect:当缺陷是回归问题时,找出引入缺陷的提交。打印调试:需要理解执行流程时,添加日志追踪执行。
工作集
上下文中始终应包含 DEBUG.yml 与 HYPOTHESES.md。
集成关系
与 play-learn-lift 的关系是“调试即学习”;向 session-log 记录所有调试活动;向 research-notebook 说明复杂缺陷需要研究;向 honest-forget 压缩调试智慧;与 adventure 互为“调试即冒险”;与 room 互为“调试会话即房间”;与 card 互为“Git Goblin 🧌、Index Owl 🦉 同伴”。
限制
资料未提供该技能的具体安装方式、运行环境要求、收费或价格信息、平台支持范围,也未提供实际效果数据或使用步骤示例,这些内容暂未提供。