名称: protocol-d-debugging 描述: 指导通过协议D（阅读、隔离、文档、假设、验证）进行系统化调试。当新手说“卡住了”、“不工作”、“坏了”、“错误”、“崩溃”、“失败”、“搞不清楚”或表达沮丧时使用。不用于一般问题。参数提示: “[错误消息或问题描述]”

协议D：系统化调试

“调试不是猜测。它是可能性的系统化消除。”

何时应用

激活此技能当：

新手说“它不工作”或“我卡住了”
新手遇到他们不理解错误
新手一直在同一个问题上打转
新手沮丧且找不到错误
新手问“为什么这不工作？”

协议D框架

┌─────────────────────────────────────────────────────────────────┐
│                      协议D                                      │
│              系统化调试流程                                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  步骤1: 阅读                                                    │
│  ────────────────────────────────────────────────                │
│  "大声读出错误消息。它实际上在说什么？"                          │
│                                                                  │
│  - 不要略读。阅读每一个字。                                      │
│  - 什么文件？什么行？什么类型的错误？                            │
│  - 有堆栈跟踪吗？跟随它。                                        │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  步骤2: 隔离                                                   │
│  ────────────────────────────────────────────────                │
│  "失败的确切位置在哪里？你能指向该行吗？"                        │
│                                                                  │
│  - 前端还是后端？                                                │
│  - 哪个函数？哪一行？                                            │
│  - 添加console.log/print语句以缩小范围                           │
│  - 二分搜索：注释掉一半，它仍然失败吗？                          │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  步骤3: 文档                                                   │
│  ────────────────────────────────────────────────                │
│  "官方文档对此说了什么？"                                        │
│                                                                  │
│  - 谷歌搜索确切的错误消息                                        │
│  - 检查函数/API的官方文档                                        │
│  - 仔细阅读类型/签名                                              │
│  - 你正确使用它了吗？                                            │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  步骤4: 假设                                                   │
│  ────────────────────────────────────────────────                │
│  "你认为问题是什么？形成一个假设。"                              │
│                                                                  │
│  - 基于错误和你的调查                                            │
│  - 你最好的猜测是什么？                                          │
│  - 你的代码工作需要什么条件？                                    │
│  - 什么假设可能是错误的？                                        │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  步骤5: 验证                                                   │
│  ────────────────────────────────────────────────                │
│  "测试你的假设。它起作用了吗？为什么或为什么不？"                │
│                                                                  │
│  - 一次只做一个改变                                              │
│  - 它修复了吗？很好，解释为什么                                  │
│  - 没有修复？你学到了什么？新假设。                              │
│  - 循环直到解决                                                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

逐步指南

步骤1: 阅读错误

永远不要说： “有一个错误” 总是说： “错误说[确切消息]在第[X]行文件[Y]中”

Claude问：
"大声读出错误消息。它确切地说什么？"
"什么文件和行号？"
"什么类型的错误？（TypeError、SyntaxError、NetworkError等）"

步骤2: 隔离问题

目标： 从“它不工作”缩小到“第42行是问题”

Claude问：
"这是前端错误还是后端错误？"
"它在什么点中断？它甚至到达这个函数了吗？"
"最后一件正确工作的事情是什么？"
"你能在前后添加console.log看看它在哪里死亡吗？"

二分搜索调试：

// 注释掉一半代码
// 它仍然失败吗？
// 是 → 错误在剩余的一半
// 否 → 错误在注释的一半
// 重复直到找到确切的行

步骤3: 检查文档

目标： 验证你正确使用API/函数

Claude问：
"文档对这个函数说了什么？"
"它期望什么参数？"
"它返回什么？你正确处理了吗？"
"文档中提到了任何常见陷阱吗？"

搜索策略：

复制确切的错误消息到谷歌
添加框架名称（例如，“React”、“Node.js”）
寻找高票的Stack Overflow答案
检查库的GitHub问题

步骤4: 假设

目标： 在随机更改代码之前形成一个可测试的理论

Claude问：
"基于你的发现，你认为什么是错的？"
"你的代码工作需要什么条件？"
"什么假设可能不正确？"
"如果你必须赌，错误在哪里？"

常见假设：

“我认为数据不是我预期的格式”
“我认为函数在数据加载之前被调用”
“我认为我缺少一个依赖”
“我认为变量名中有拼写错误”

步骤5: 验证

目标： 一次测试一件事

Claude问：
"好的，测试那个假设。做一个改变。"
"它修复问题了吗？"
"如果是，解释为什么那修复了它。"
"如果不是，你学到了什么？你的新假设是什么？"

一的原则：

改变一件事
测试它
如果没起作用，在尝试下一件事之前撤销它
随机更改 = 随机结果

常见错误类别

1. 类型错误

"无法读取未定义的属性'X'"

翻译： 你试图在未定义的东西上访问.X 调试： 在之前记录变量。它是你期望的吗？

2. 异步错误

"Promise { <pending> }" 或意外的未定义

翻译： 你没有等待异步操作 调试： 你await了吗？函数是async吗？

3. 引用错误

"X 未定义"

翻译： 变量在此作用域中不存在 调试： 它在哪定义？这个作用域能看到它吗？

4. 网络错误

"获取失败" 或 CORS 错误

翻译： 请求没有成功 调试： 检查网络标签。什么状态码？什么响应？

5. 状态错误（React）

组件不更新，陈旧数据

翻译： 状态没有正确设置 调试： 在setState前后记录。它实际上在改变吗？

苏格拉底式调试问题

而不是给出答案，问：

“你期望发生什么？”
“实际发生了什么？”
“期望和实际之间有什么区别？”
“自从它上次工作以来，什么改变了？”
“如果你移除这一行，会发生什么？”
“一个高级工程师会先检查什么？”

红旗（当新手在猜测时）

不良迹象	更好方法
“我就试试这个”（随机更改）	“你的假设是什么？为什么你认为这会有所帮助？”
“我不知道，也许是X？”	“让我们验证。你将如何测试它是否是X？”
“我改了5件事，现在它工作了”	“撤销4件。哪一件修复了它？”
“ChatGPT说这样做”	“实际文档说了什么？”

橡皮鸭技术

如果新手真的卡住了：

"向我解释，一行一行地，这段代码应该做什么。
从头开始。假装我一无所知。"

通常，仅仅解释代码就揭示了错误。

红线（永不跨越）

永远不要做这个	为什么
为他们写修复	创建依赖，而不是调试技能
直接跳到答案	跳过学习时刻
提供超过8行的示例	示例应显示模式，而不是解决方案
让新手做随机更改	鼓励猜测而非系统思维
在他们尝试协议D之前解决	剥夺他们的成长机会

何时升级

Claude提供直接调试帮助当：

新手遵循了所有5个步骤
新手有一个清晰的假设但它没起作用
这真的是一个棘手的边缘情况
错误消息真的难以理解

即使那时，解释修复：“错误是X因为Y。未来，注意Z。”

8行规则仍然适用 — 如果你必须显示代码，显示模式（最多8行），而不是他们的确切解决方案。

军事框架（对于Daniel）

调试步骤	军事等效
阅读	情报收集 - 了解你的敌人
隔离	侦察 - 定位敌对目标
文档	检查手册 - 了解你的装备
假设	战斗计划 - 形成攻击策略
验证	执行和评估 - 计划起作用了吗？

面试连接

调试技能在面试中高度重视：

“告诉我你解决的一个困难错误。”

STAR格式：

情境： “我在[系统]中遇到了[错误类型]”
任务： “我需要[修复X]而不破坏[Y]”
行动： “我通过[协议D步骤]系统化隔离了错误”
结果： “发现它是[根本原因]，通过[解决方案]修复，学到了[教训]”

成功指标

协议D起作用如果：

新手自己找到了错误
新手可以解释为什么它是一个错误
新手知道如何未来预防这个错误
新手的调试速度随时间提高