AI 辅助调试实战

调试是工程师每天花时间最多、又最不被承认价值的工作。一个 bug 可能耗你两小时,其中一小时半在"找它在哪、为什么",真正改代码可能就两分钟。AI 把这两小时压缩到二十分钟,前提是你得会用——用错了,它只会对你说"请检查一下网络连接"。

下面是我用 Claude Code、IDE 内 AI 调试几百个 bug 后沉淀下来的实战方法。

一、AI 调试的真正机会,以及它为什么总给你废话

AI 在调试链路上真正能加速的是三件事:读日志、分析堆栈、快速定位。这三件事的共同点是——信息密度高、需要跨文件关联、但推理路径不长。一个 200 行的报错日志,人脑要花五分钟扫一遍,AI 两秒就能告诉你"第 47 行那个 Cannot read property 'id' of undefined 才是根因,源头在 getUser 返回了 null"。

但大多数人对 AI 调试的体验是"废话连篇"。原因不在于模型不行,而在于你给的信息不够。你只说"我的登录接口报错了,帮看看",它当然只能回你"请检查:1. 网络连接 2. 接口地址 3. 请求参数 4. 后端日志"。这不是 AI 在敷衍你,是它在没有上下文时只能输出"通用排查清单"。

金句:AI 不是算命先生,你给什么它算什么。

二、贴对信息:上下文决定诊断质量

调试 Prompt 的黄金公式是五件套:完整报错 + 完整堆栈 + 相关代码 + 最小复现步骤 + 你已经试过什么。少任何一样,诊断质量都会断崖式下降。

反面教材:

"我的 server action 报错了,帮忙看看。"

这种 prompt 换来的只能是"建议您检查一下数据库连接"。正面教材:

Next.js 15 的 server action,调用 Prisma 创建用户时报错。

完整报错:

Error: Unique constraint failed on the (email)
    at PrismaClientKnownRequestError
    at handle (src/app/actions/user.ts:23:16)

相关代码:

export async function createUser(input: UserInput) {
  return db.user.create({ data: input })
}

已试过: input.email 不为空,数据库里也查不到这条 email。

期望: 重复 email 应返回友好错误,而不是抛 500。

同样的 AI,第二个 prompt 给出的答案会直接指向"你的 schema 里 email 字段可能有旧数据/大小写不一致/空格,建议先 TRIM 再查询,并加上 catch 区分 P2002"。差距全在上下文。

已试过什么这一条尤其重要。它能把 AI 从"让你检查数据库连接"这种废话里拽出来,逼它往更深的假设走。否则它会一直在你已经走过的路上打转。

三、适合交给 AI 的 bug 类型

实战中我发现,AI 处理得好的 bug 有个共同特征:真相藏在代码和日志里,不需要真实运行环境。具体五类:

1. 独立的逻辑错误 —— 一个纯函数算错了、条件写反了、off-by-one、边界没处理。把函数贴给它,它一眼就能看出 i <= arr.length 应该是 i < arr.length。

2. API 误用 —— React Hooks 违反规则、Promise 没 await、Prisma 传错了 where 结构、Array.map 里返回了 undefined。这类 bug AI 见过几万次,闭着眼睛能认出来。

3. 配置/环境问题 —— .env 没加载、Docker 端口冲突、Next.js 的 output: 'export' 和 server-side API 冲突、TypeScript 的 moduleResolution 配错了。把配置文件和报错一起贴,AI 通常能精准命中。

4. 第三方库的用法 —— "我用了 zod 的 .refine 但异步校验不生效"。AI 对主流库的 API 比大多数人都熟。

5. 报错信息明确 —— TypeScript 编译错误、ESLint 报错、构建失败的明确信息。这是 AI 的主场,基本秒答。

四、AI 搞不定的:把时间花在人工上

但有一类 bug,AI 不仅帮不上忙,还会把你带偏。这些 bug 的共同点是——真相不在代码静态文本里,而在运行时的时序、状态、资源里。

• 并发竞态:两个 async 请求同时写同一个 key,AI 看代码是"正确"的,因为它默认顺序执行。它会给你一堆"看起来合理"的修复,但都没复现过真实场景。
• 性能瓶颈:CPU 飙高、响应慢。AI 会猜"是不是 N+1 查询",但它看不到 profiler 的火焰图,只能给出通用建议清单。
• 内存泄漏:AI 看代码很难判断哪个闭包持有引用、哪个 EventListener 没解绑。需要 heap snapshot 才能定位。
• 分布式系统级:跨服务的数据不一致、网络分区、消息重复。AI 对单服务内的代码理解强,对跨服务时序弱。
• 需要真实环境复现:只在生产/Staging 才出现的 bug,数据敏感、环境复杂,AI 看不到也跑不了。

金句:并发 bug 是 AI 的盲区,因为它的训练数据里也没有真相。

这五类 bug,别把希望寄托在 AI 上。让它帮你列假设清单可以,但定位和验证必须你亲自来。

五、上下文工程:给 trace,别给描述

调过试的人都明白一句话:"我以为"是 bug 最大的伪装。你描述问题时,大脑会自动补全、自动美化、自动跳过你以为是无关的细节。你跟 AI 说"这个函数返回了空数组",但真实 trace 里函数返回的是 undefined,被你下意识"翻译"了。

所以上下文工程的第一原则是:给原始 trace,不给你的描述。

• ❌ "这个函数好像返回了 undefined" —— 这是你的二手描述
• ✅ 贴 console.log 的原始输出、贴 node --inspect 抓到的实际返回值

第二原则:给相关代码,不给全仓库。Claude Code 这类工具能自己 grep,但你自己圈定范围会让它更聚焦。贴上"我怀疑是这几个文件"的 hint,比让它满仓库找快十倍。

第三原则:隔离变量。一个 bug 涉及 5 个函数、3 个 API 调用时,别把整个链路一次性甩给 AI。先把问题压到一个最小复现:只调这一个函数、只传这一个输入、只观察这一个输出。最小复现本身就是调试的一半,AI 在最小复现上的命中率会高一个数量级。

我调试过一个 Next.js 路由的问题,整个页面 300 行,传给 AI 它给了一堆"可能是 hydration 不匹配"。我把页面砍成一个空组件 + 一行 fetch,bug 还在——这下 AI 一眼就指出是 middleware.ts 里的 redirect 逻辑问题。变量没隔离之前,AI 看不清;隔离之后,它一眼就懂。

六、工具用法:Claude Code / IDE / 断点配合

工具形态决定了 AI 调试的上限。

Claude Code 这类能读文件、能跑命令的 agent,是质变。你不用再 copy-paste 一堆代码,直接说"看一下 src/app/actions/user.ts 的 createUser,报错信息在 /tmp/error.log,帮我定位"。它会自己读、自己 grep、自己跑 pnpm tsc --noEmit、自己看 schema。这种"它有手有眼"的调试,比纯对话式 AI 强一个台阶。

IDE 内 AI(Cursor / Copilot Chat / Windsurf) 适合"边写边问"。选中一段代码报错,直接 Cmd+I 问"这里为什么 TS 报错"。它的优势是上下文自动带上当前文件、光标位置、打开的 tab,你几乎不用手动喂上下文。

但无论哪种工具,最高效的模式是 AI + 断点/日志配合,而不是 AI 替代它们:

1. 先用 AI 读报错、读堆栈,得到一个"最可能的根因假设"
2. 在那个位置打 console.log 或断点,跑一次真实复现
3. 看 trace 是不是支持 AI 的假设
4. 不支持就回到第 1 步,把新观察喂给 AI 让它重新假设

这个循环里,AI 负责"快速生成高质量假设",你负责"用真实运行时数据验证假设"。这才是人机协作的正确分工。AI 单独干会瞎猜,你单独干会慢——合起来就是降维打击。

七、AI 调试的纪律:它的假设要验证,别当真理

最后一条,也是最容易翻车的一条:AI 的诊断是假设,不是结论。

AI 有一种危险倾向——它会用非常自信的语气说出一个没验证过的猜测。它说"这个问题是因为 useState 的 setter 是异步的",听起来有理有据,引经据典,你照着改了半天发现根本不是这个原因。这种"自信的错误"比无知更危险,因为它会消耗你的时间、动摇你的判断。

我的纪律是:

• AI 的每一条结论,都要能对应到一段真实的 trace 或文档。它说"这个 API 行为是这样的",去查官方文档确认。
• AI 给的修复方案,改完一定要跑一次复现,而不是"看起来对就提交了"。
• AI 连续两次猜错,立刻切回人工模式。别指望它第三次能猜对,也别陷入"我描述得更详细它就能答对"的陷阱——可能这个 bug 根本就不在它能力圈内(回到第四节)。
• 保留你自己的判断。如果 AI 的诊断和你的工程直觉冲突,先信直觉去验证,别盲信 AI。

金句:AI 是资深工程师时能把你提速三倍,是新手盲信 AI 时能把你拖进泥潭三小时。

小结

1. 上下文是 1,其他是 0。没有完整报错/堆栈/代码/复现/已试过,AI 只能给废话。
2. 适合 AI 的 bug:信息在代码和日志里。独立逻辑、API 误用、配置、库用法、明确报错。
3. 不适合的:信息在运行时。并发、性能、内存、分布式、需真实复现——AI 只能列假设,定位靠你。
4. 给 trace 不给描述,给相关代码不给全仓库,先做最小复现再喂 AI。这是上下文工程的三板斧。
5. AI + 断点/日志的循环才是高效模式:AI 出假设,你用真实数据验证;每条结论都要回到 trace 确认,别把自信当正确。

调试的尽头不是"AI 帮我找到了 bug",而是"AI 帮我更快地验证了我的假设"。工具越强,工程师的判断力越值钱。