与 AI 编程助手协同调试的实战策略

用 LLM 调试不是魔法，而是一场协作。模型能力很强，但它们需要清晰的框架和批判性的监督。遵循这些步骤，你能在调试过程中更加高效：

先打快照（git commit / git checkout -b）。

小 bug 直接复制粘贴重复来。

复现问题、加日志、收集证据和数据、形成假设、搜索，最后把它们记到 markdown 文件里。

对每个假设做合理性校验。

证明根本原因。

引入第二双眼睛。

把经验教训记录到 AGENTS.md。

1. 先打快照 -- git commit / git checkout -b

在做任何事情之前，先提交当前状态或创建一个新分支。不是脑子里想想，而是实际执行一次 Git 提交。

为什么？因为 Claude 的 rewind（回退）功能只会撤销直接的文件编辑。它无法撤销运行脚本、安装包或其他非文件变更带来的副作用。Git 提交才是你真正的安全网。

git add . && git commit -m "chore: checkpoint before debugging"

这是最重要的一条建议。说起来简单，但在调试的热头上，跳过这一步太容易了。有一个干净的快照，你才能放心让 AI 大胆尝试，因为你知道随时可以回退。

2. 快速粗糙：复制、粘贴、重复

对于小问题，那些感觉只是轻轻撞了一下墙的情况。把堆栈跟踪或错误信息复制过来，直接粘贴到编程 Agent 里。不需要上下文，不需要解释，只要错误本身。

这对于简单问题效果出奇地好。编程 Agent「懂了这个梗」（俗话说的），从你的代码库中理解上下文，通常一两轮就修好了。

效率优先：复制 → 粘贴 → 重复。别想太多。

如果成功了：很好！几秒钟搞定。

如果变得更糟：回退到你的提交，进入第 3 步。

3. 有条不紊的方法 -- DEBUG.md

当问题复杂了，或者你完全不知道为什么会失败，或者 LLM 反而把事情搞得更糟了。是时候转换思路了。这才是真正调试 discipline（纪律）开始的地方。

创建一个名为 DEBUG.md 的 markdown 文件：引导编程 Agent 进行结构化调查：

持续复现：要求 LLM 每次都能复现问题，并把具体步骤记录到 DEBUG.md。

深入调查：要求 LLM 添加额外日志、检查日志、收集所有可用数据。

形成假设：要求 LLM 提出可能的原因并写下来。

网上搜索：让编程 Agent 搜索类似的在线问题，但要用批判性眼光。

当 LLM 说「找到了，这是个已知问题」时，质疑它！

因为有时候它信誓旦旦说找到了问题，但当你要求它给出信息来源的链接时，它给你的只是一个多年前某个开发者遇到类似问题的 Stack Overflow 问答 🤦。更糟的是，它可能在编造事实或者凭空捏造。

4. 对每个假设做合理性校验

这是你需要成为「房间里的大人」的时刻。LLM 喜欢抓住第一个看似合理的解释然后就跑。它会以惊人的自信说出完全错误的结论。

要证据，追问它：

  Is this a common issue? How many people reported it?

要求证明，问它：

  Can you demonstrate that this is actually the root cause?

警惕虚构，LLM 可能编造出不存在的限制，然后围绕这个虚假前提重构整个代码库。

如果你发现它掉进了兔子洞，停下来，回退到上一个提交，然后告诉它：

This is not the problem. Try again.

5. 证明根本原因

一旦 LLM 有了一个它相信的假设，让它证明。把证明过程记录到 DEBUG.md。这不是可选的，这是「猜测」和「确认」之间的区别 😉。

持续复现：展示在特定条件下问题每次都会发生。

应用修复：做出修改并确认问题已解决。

验证一致性：证明修复可以稳定复现，而不是仅仅一次有效。

6. 引入第二双眼睛

如果这些都做了你还在卡着，是时候叫救兵了。救兵指的是另一个 LLM / 同事。

启动 Codex、Antigravity 或任何你能用的其他模型。把同样的任务给它，走一遍同样的纪律化流程。每个模型训练经验不同，偏见也不同。Claude 漏掉的，另一个模型可能一眼就看出来。

每个模型训练经验不同，偏见也不同。

Claude 漏掉的，另一个模型可能一眼就看出来。

如果这样也不行，而且你有同事，试着咨询他们。或者干脆去「橡皮鸭」一下！

通常来说，只要保持开放的心态，引入不同的 LLM 就能解决大部分问题。

7. 把经验教训记录下来 -- AGENTS.md

这是最多人跳过的一步，包括我以前也是这样，这是一个巨大的错误。问题修复后，让 LLM 在 AGENTS.md 里写一个经验教训部分。这就像是 AI 的记忆银行。包括：

根本原因是什么。

如何发现的。

下次会怎么做不同。

任何可以避免重蹈覆辙的项目特定提示。

为什么？因为一旦你清空对话或者发生压缩，编程 Agent 就忘了。它会再次犯同样的错误。把它记录下来就打破了这个循环。

系统化调试 Skill

试着把这个 skill 安装到你的编程 Agent 里并使用它。它把我在这里描述的大部分内容公式化了，并且额外强调了网络搜索和「铁律」——证明根本原因。