AI辅助调试实战：用Claude Code高效定位日志与代码问题

调试这事，干过几年开发的人都懂，最花时间的往往不是写代码，而是找出“为什么这里会炸”。有时候一个 bug 能在日志里藏三天，你盯着屏幕换着姿势猜，最后发现是初始化顺序错了一位。我用 Claude Code 写代码有段日子了，本来以为它最大的价值是生成代码，直到有一次线上问题排查，我拿着它一步步追一个诡异的内存问题，才发现这工具在调试场景里才是真正的高价值用法——它能像坐在旁边的老同事一样，帮你看日志、理逻辑、定位可疑点，而不是像个搜索引擎一样只给你贴文档。

这篇文章想把我在实际项目里用 Claude Code 做调试的完整思路、具体操作和踩过的坑写清楚，包括它适合处理什么类型的问题、怎么给它“喂”上下文、怎么设计调试指令、怎么跟传统调试工具配合，以及哪些场景千万别指望它。如果你是写代码时遇到报错只会复制粘贴到搜索引擎的人，或者团队里频繁被拉去“帮忙看看这个 bug”的人，这篇应该能给你一些新思路。

1. 为什么调试是 Claude Code 的高价值场景

先说结论：Claude Code 这类大模型工具，在“生成新代码”这件事上，能力上限其实是肉眼可见的——它能帮你写模块、补函数、起项目骨架，但真正复杂到需要全局架构认知的代码，它还是会露怯。但调试不同，调试的本质是“从一堆已知信息里找出异常的因果关系”，这恰好是语言模型最擅长的事。

1.1 调试的核心痛苦：信息太多，上下文碎片化

任何一个稍微有点规模的项目，排查问题时的信息量都极其庞大：报错堆栈、日志文件、配置文件、系统状态、代码逻辑……我见过很多开发者排查问题的姿势是这样的：先看报错信息，然后去代码里搜相关函数，看完一段再去翻日志，日志翻完又得回来看数据结构定义，来回横跳几个小时，大脑的“工作内存”早就爆炸了。更别提多人协作的项目里，那段出问题的代码可能压根不是你写的，你连设计意图都得猜。

而 Claude Code 的价值恰恰在于，它的上下文窗口足够大（尤其是支持长上下文以后），你可以把报错堆栈、日志片段、相关源文件全部丢给它，让它在一个“全局视图”下帮你分析。人脑的工作记忆大概只能同时装 4-7 个信息块，模型可以轻松处理几十个文件的相关片段，这种信息整合能力是天然优势。

1.2 模型适合做“假设-验证”循环

调试本质上是一个反复提出假设、验证假设的过程：怀疑是空指针，去看初始化；怀疑是内存越界，去查数组长度；怀疑是并发问题，去看锁的粒度。Claude Code 特别适合做这个循环里的“假设生成器”——你提供现象，它基于代码上下文列出所有可能性，并按概率排序。很多时候，我们自己排查问题会陷入思维定势，眼里只有一种可能性，这时候让模型用另一个角度列一下“你还漏了什么”，往往有奇效。

我自己最常用的一个调试 prompt 模板是这样的：

[粘贴报错信息或异常现象] 这是项目里的相关文件： [文件A路径及内容] [文件B路径及内容] 请帮我列出可能导致这个问题的所有原因，按可能性从高到低排列。 每条原因请说明：判断依据、如何进一步验证、大概涉及哪个文件哪一行。

实测下来，这个模板比直接问“为什么报错”好用得多，因为它在引导模型输出“排查路径”而不是“一个答案”。模型列出的低概率原因里，经常藏着真正的坑。

1.3 写代码是生成，调试是理解，理解是模型的强项

我后来想明白了一件事：写代码要求模型从零构造一个“确定性的、符合所有约束的逻辑结构”，这本质上是一个组合爆炸问题，容易翻车。但调试是给模型一堆“已经存在的、确定的代码”，让它去理解、归纳、找异常点，这是一个纯理解任务。语言模型的训练目标本来就是“理解文本”，你在让它理解代码文本时，它发挥的是最强项。

所以如果你跟我一样，一开始只把 Claude Code 当代码生成器用，可能有点浪费——它在 Debug 场景的稳定性和准确率，明显比生成新功能时要高。我现在的工作流是：让 Claude 写新功能时保持谨慎、人工 review 为主；但排查问题时，大胆把原始信息投给它，它的“调试直觉”很多时候比我这个写了十几年代码的人还敏锐，因为它见过的 bug 模式实在太多了。

2. 用 Claude Code 调试的正确打开方式

工具再好，用错了姿势也是白搭。我见过不少同事把 Claude Code 当聊天机器人用，在对话框里贴一段报错，问“这什么意思”，得到的答案永远停留在“这个错误表示空指针引用”这种层面——正确，但毫无用处。真正的调试用法需要把它嵌入到你的工程环境里，给它足够的上下文和明确的身份。

2.1 把 Claude Code 跑在项目目录里，而不是网页对话框

网页对话框和项目内跑起来的 Claude Code，调试效率差了一个量级。在网页里粘代码，你需要手动复制粘贴、手动同步文件内容，对话一长就混乱。而在项目目录下跑claude，它能直接读文件、查目录结构、甚至执行命令，等于把一个“懂代码的助手”直接拉进了你的项目环境。

我的习惯是：遇到问题，就在出问题的模块所在目录启动一个 Claude 会话，先跟它简单说一句“帮我看看这个项目的结构”，让它建立对项目的整体认知，然后再贴具体的报错信息。这一步虽然看起来废话，但能让后续的分析有依据，而不是凭空猜。

2.2 给 Claude Code 配置好读取和搜索权限

如果你用 Claude Code 的终端版本，建议在调试场景下放权给它读取工程内的核心文件。默认配置里有些文件是被忽略的（比如 .gitignore 里的一大堆目录），但调试时日志文件、临时配置、构建产物反而可能藏着线索。我一般会让它读取：

• 构建日志、运行日志（忽略大小，让模型自己翻）
• 配置文件、启动参数
• 最近改动的几个源文件（配合 git diff）

这里有个实用技巧：如果你用的是 Claude Code 的 VS Code 扩展，可以直接选中工程里几个可疑文件，让它加入上下文；如果是命令行版本，用@文件路径的方式显式引用文件，比让它自己猜要准得多。

2.3 先喂现象，再喂代码，最后要求推理过程

我给 Claude Code 投递调试信息时，信息顺序有讲究：先说“现象”，再说“相关代码”，最后要求“推理”。为什么这个顺序重要？因为模型是逐字生成回复的，它看到前面的内容后，后续生成会受前面信息的影响。你如果先贴了一大段代码，开头没说现象，模型很容易被代码带偏，陷入“逐行解释这段代码”的模式，而忘了你是来解决问题的。

推荐的格式：

## 现象 服务启动 5 秒后崩溃，日志最后几行是： [粘贴日志] ## 相关代码 初始化逻辑在 src/main.py 里，核心代码如下： [粘贴代码] ## 任务 请从代码和日志出发，逐步推理可能的崩溃原因，先列出推理过程，再给结论。

注意最后那句“先列出推理过程，再给结论”。我一开始直接让它给结论，发现它总是给一个听起来很靠谱但细节经不起推敲的答案，答案还特别自信。让它先推理、把每一步依据写出来，准确率会明显提升——其实跟面试时要求候选人“讲思路”是一个道理。

2.4 给它“试错”的接口，而不是让它一次猜中

真正排查过复杂问题的人都明白：调试很少是一步到位的，大多数时候是一步步逼近真相。Claude Code 的对话式交互在这里有天然优势，你可以跟它连续讨论，每次拿到新信息再反馈给它。

一个比较好的工作模式是：让 Claude 先提出一个假设和验证方案，你按照它的方案去加日志或者改代码，把对应报错拉下来再丢给它。这个循环可以重复十几次，直到定位到根因。我的感觉是：模型不会累，不会因为反复尝试而烦躁，这比拉人一起 debug 舒服太多——毕竟同事帮你排查十分钟就开始心不在焉了。

但这里有个前提，你要明确告诉 Claude “这轮先只提出验证方案，不用直接改代码”。不然它会在你还没确认根因的情况下，直接提一个 fix PR，改完反而引入新问题。

3. 实操过程：用 Claude Code 一步步定位线上崩溃问题

理论讲再多也不如一次完整实操有说服力。我把最近一次真实项目里用 Claude Code 排查崩溃问题的过程完整复盘一下，这里面包含了具体指令、中间反馈和我的应对调整，希望能给你一个可以直接参考的模板。

3.1 背景：服务偶发崩溃，日志指向不明

这个项目是一个 Python 写的内部数据同步服务，最近上线后偶尔会在运行半小时左右崩溃一次，日志最后的输出五花八门：有时是Connection reset by peer，有时是TypeError: 'NoneType' object is not subscriptable，有时干脆没有报错，直接Killed。崩溃时间不固定，本地复现不出来，典型的线上偶发问题。

按我以前的习惯，这种问题得先做一堆数据采集：加监控、抓 core dump、看系统日志。但这次我先把现有信息丢给了项目目录里的 Claude Code：

我用的第一条指令大概是这样的：

@src/sync_service.py @src/network.py @logs/prod_error.log 服务在线上会偶发崩溃，运行时间 30 分钟到 1 小时不等，日志见 error.log。 崩溃时的报错不完全一致，有时是 Connection reset，有时是空指针，有时直接被 Killed。 请从代码里找找有没有什么共同点是这些崩溃路径都会经过的。 重点看看 initialized 标志的使用、连接池的创建和销毁时机。

这里我特别加了一句“重点看看 initialized 标志的使用”，是因为我心里其实有个模糊的怀疑——服务里有个懒加载初始化逻辑，我怀疑它在并发场景下会被重复执行或踩到未初始化状态。但我没有直接说结论，而是让模型去代码里验证。

3.2 Claude Code 的分析与我的追问

Claude Code 很快给出了分析，核心观点是：所有这些崩溃路径都指向同一个入口函数_get_connection()，这个函数判断self._pool is None时就会创建连接池，但创建连接池的过程中没有加锁，如果并发进来两个请求，两个请求都会发现_pool is None，然后各自创建一个连接池，后创建的覆盖先创建的，先创建的连接池连接无人管理和释放，连接数持续增长，最终被系统 OOM Killer 干掉——这就解释了Killed，也解释了后面的连接异常和空指针，因为覆盖过程中旧连接池还在被引用。

说实话，这个推理方向跟我原本的猜测接近，但更完整。我原本只想到“初始化可能被执行了两次”，没往“连接池被覆盖+无人释放导致 OOM”这个链条上想。模型把散落的线索拼成了一条完整因果链。

不过我没有直接采信，而是追问了一句：

这个结论能解释“Connection reset by peer”吗？如果能，请解释具体机制。

这一步很关键。因为一个假设如果只能解释部分现象，那它不是根因，只是若干并发问题之一。Claude Code 的回答是：连接池被覆盖后，旧连接池里的连接仍在处理请求，当操作系统回收文件描述符或对端服务主动断开时，这些残留连接就会报 Connection reset；新连接池连接数暴涨到系统上限时，新的建连请求直接失败，表现因时机不同而各异。

3.3 让 Claude Code 给出验证方案，但不急着让它改代码

确认逻辑链后，我让 Claude Code 给出最小化验证方案，明确要求“先给出验证步骤，不要直接改代码，改动方案最后再给”。它给出的验证方案：

1. 在_get_connection()入口加一个threading.current_thread().name和self._pool状态的日志输出，确认是否有线程在已有 pool 的情况下重复进入创建分支；
2. 在连接池创建处打印调用栈（用traceback.format_stack()），确认是哪个入口触发的；
3. 为验证 OOM 假设，连续跑压力测试并监控进程 RSS 内存曲线。

这三条我照着做了一遍，实测第二条效果最好——打印调用栈后，果然发现了两个不同的入口函数都调用了_get_connection()，其中一个入口在调用之前重置了self._pool = None，这就是竞态条件的源头。

3.4 修复阶段：让 Claude Code 给方案，我亲自改

到这一步，根因已经清楚了：某个异常处理逻辑里，为了强制重连，把self._pool直接置成了None，而这个操作和另一个请求里的建池操作存在竞态。修复方案其实很简单：加一个threading.Lock，把对self._pool的检查和创建放进同一个锁保护下，同时把“强制重置”改成“通过一个 flag 标记重连，而不是直接把 pool 置空”。

我让 Claude Code 用“最小改动原则”给了 diff，我 review 后手动改了上去。这里我说说为什么不让它直接改：因为这涉及线上核心链路，我需要完全确定在“什么条件下”逻辑会被触发，而不是只看到“改完可能就好了”。AI 给出的修复可能在测试环境没问题，但线上并发模型复杂得多，我宁愿自己逐行理解改了什么。

3.5 这个案例给我的三个启示

复盘整个排查过程，对比传统手工排查，有几个体会比较深：

第一，Claude Code 把“从现象到根因”的路径压缩了。以前这类偶发崩溃，我需要把所有报错日志按时间线整理、看监控图、画时序图，才能推测出是初始化竞态。现在模型直接把这个推理过程做了，而且会主动关联多个看似无关的报错。

第二，追问机制是调试质量的保证。模型第一轮给出的结论往往只是“一个可能的解释”，不是“确定答案”。多轮追问、拿新数据验证、让模型解释中间机制，才能真正逼近根因。

第三，让 Claude Code 先出验证方案，比直接让它出修复方案更安全。验证方案出错了，最多是白折腾一轮；修复方案出错了，可能直接把问题扩大化。先验证后修复，这个顺序不要乱。

4. 在传统调试场景里给 Claude Code 找个位置

很多人看到 Claude Code 做调试，第一反应是“它能替代 gdb、IDE 断点这些传统工具吗”。我的答案很直接：替代不了，也不应该替代。它不是跟断点调试器竞争，而是补位在断点调试器不太擅长的部分。

4.1 断点调试管的是“运行时状态”，Claude Code 管的是“代码逻辑关系”

以 gdb、IDE 断点为代表的传统调试工具，核心能力是查看“某个时刻的内存状态、变量取值、调用栈”。这个东西 Claude Code 做不了，也不该做——它没有运行时视角。但它擅长的是另一件事：把报错信息、源码逻辑、配置文件、官方文档放在一起，建立“跨文件的因果链”。

我实际项目里最常用的组合拳是：先用 Claude Code 从报错堆栈和源码里缩小可疑范围，锁定到某个函数后，再在那个函数里打日志或加断点，用传统工具确认运行时状态。前者管广度，后者管精度，互补关系非常明显。

举一个实际例子：有一次 C 语言的崩溃问题，core dump 里的调用栈指向了一个库函数，但看不出是哪行调用进来的。按传统做法，我得反复bt、frame、info locals去逆向。但那天我先把调用栈贴给了 Claude Code，它结合源码直接指出：这个库函数被两个不同的调用点使用，其中一个调用点没有做参数合法性检查，而崩溃时的参数特征（一个负数）只有那个调用点会产生。我再回去用 gdb 验证，果然如此。整个过程从一小时缩短到十分钟。

4.2 嵌入式、硬件调试场景怎么用 Claude Code

热词里有一大堆嵌入式调试相关的内容——串口调试、keil5、STM32、ADB 调试之类的。这类场景用 Claude Code 调试的方式又不一样，核心在于：嵌入式调试的痛点往往不是“代码逻辑”，而是“环境配置、寄存器配置、时序问题、工具链问题”。

我之前调过一块开发板的摄像头驱动，报错是 I2C 通信超时。按老办法，得翻芯片 datasheet、查驱动里寄存器配置顺序、用示波器看时序。但那次我直接把驱动代码里初始化那一段和报错日志丢给了 Claude Code，它一眼看出配置顺序里有一个 reset 引脚的时序不对——代码里先拉高了 reset，再配置 I2C 地址，但芯片文档要求必须“拉低 reset → 延时 → 拉高 reset → 延时 → 配置地址”。这种问题，纯粹靠看代码很难发现，因为光看每行代码都是合法的，只有把它和芯片手册的时序要求对比，才能看出问题。

嵌入式调试里 Claude Code 的另一个作用是用来“翻译”芯片手册。现场工程师最烦的就是几百页的 datasheet 里搜一个寄存器的含义，把相关段落丢给模型，它可以直接总结成“这个寄存器必须在什么条件下设置，跟哪个中断相关”。这些虽然 IDE 和调试器做不了，但其实都是排查时序问题时的高频动作。

4.3 日志分析是 Claude Code 的主场

如果只能选一个调试场景让 Claude Code 发挥价值，我首推日志分析。一个线上服务跑一天能产生几万行日志，人眼扫描的效率低得可怕。Claude Code 可以直接读日志文件（前提是文件别太大，超出上下文窗口就分段喂），让它做这几类事：

• 按时间线归纳关键事件，找出崩溃前 30 秒内所有异常日志；
• 对比多次崩溃的日志共同点；
• 把日志里的时间戳和代码里的关键节点对应起来，指出最可疑的时间间隙。

有一次我处理一个“每天早上 8 点准时服务卡顿”的问题，日志量巨大，我直接把早上 7:50 到 8:10 的日志丢给 Claude Code，让它列出所有跟往常不同的行为。它很快提到一个定时任务日志异常：有一个清理任务在 8:00 整启动，但迟迟没有结束日志，后续其他任务都在等它持有的锁。真相是那个清理任务的数据量在夜里积累到某个阈值后，执行时间暴涨。这种分析如果自己从日志里翻，没有几个小时下不来。

4.4 移动端调试：ADB、无线调试这些场景能帮上什么

另一个高频调试场景是移动端和 Android TV 的 ADB 调试。热词里有 “ADB 驱动需要 USB 调试模式吗”“MatePad 11 USB 调试弹窗”“Android TV ADB 远程调试全攻略” 这类，这些场景多数是环境问题，而不是代码问题，Claude Code 的作用更像是一个“配置百科全书”。

比如新手问“红米 Note 9 Pro 怎么开启 ADB 调试”，传统做法是去论坛翻帖子，版本不同、步骤略有差异，翻半天可能还是一头雾水。直接问 Claude Code，它会给出通用步骤：设置 → 关于手机 → 连点版本号 7 次打开开发者模式 → 进入开发者选项 → 打开 USB 调试。对于这类流程明确的步骤，模型回答得很准。

不过我在这类场景里对 Claude Code 的使用更偏重“排错思路”，比如：“ADB 已经开启，但 fastboot 连不上，可能是什么原因？”它会列出：驱动没装对、端口被占用、设备授权弹窗没点确认、USB 线不支持数据传输（最常见的坑，很多线只能充电不能传数据）。这种清单式排查思路，模板化但实用。

5. 常见问题与避坑指南：调试时别踩这些坑

工具好用，但不代表没有坑。我在用 Claude Code 调试的过程中踩过不少雷，有些问题几乎每个新手都会遇到，集中写出来，免得你重复我走过的弯路。

5.1 问题一：上下文塞太多，模型反而“看不到”重点

调试的时候，人容易走极端——要么贴的信息太少，模型全靠猜；要么一股脑把整个项目源码都拖进去，模型淹没在细节里。我见过有人把整个src目录几十个文件全喂给 Claude Code，然后问“哪里有问题”，结果模型只能泛泛而谈，给出一些永远正确的废话。

正确做法是控制上下文的“信噪比”：先贴报错信息和日志片段，让模型初步判断涉及哪些模块，再把对应模块的文件贴进去。如果你不确定涉及哪些文件，可以让它先搜索：@src/ 请搜索与报错关键词相关的文件。这个过程相当于人工排查时的“看目录结构 → 定位文件 → 读代码”，只是速度更快。

注意：日志文件如果太大，别完整贴进去。可以先截取崩溃前 200 行、崩溃后 20 行，保留时间戳和异常关键字。日志的“最近上下文”往往比完整日志更有价值。

5.2 问题二：模型“幻觉”出一个合理但错误的根因

这是最危险的情况。Claude Code 非常擅长编造一个听起来逻辑闭环、细节丰富、但实际错误的原因。它不会告诉你“我不确定”，而是自信地推演一套因果链，看着每一步都对，起点却是错的。

我应对这个问题有两个策略。第一，关键结论要追一句“这是你从哪一行代码判断出来的，请引代码”。如果模型的依据引不出来，基本可以判定是幻觉。第二，让 Claude Code 给你“可以验证这个结论的测试方法”，如果它给出的验证方案能真正区分“这个原因”和“其他原因”，那可信度大幅提升；如果验证方案是泛泛的操作（比如“检查网络状态”），那就只是大概率在猜。

5.3 问题三：它改代码后引入新问题，你还不知道

这是调试场景里最容易翻车的环节。前面案例里我特意强调了“先验证方案，后让 Claude 改代码”，但很多初用者会让模型“直接修好”，模型改了代码，看起来修好了，实际上因为上下文不完整，它可能只修了表面现象，或者改了 A 函数影响了 B 函数。

我的建议很明确：让 Claude Code 负责分析和方案，修改动作自己来，或者至少逐行 review 它的 diff。如果你的流程是“发现问题 → 让 Claude 分析 → 自己动手改 → 用 Claude 复测”，整体风险是最低的。

另外，如果确实要让它直接改，改完一定要让它解释“每一行改动是为了解决什么”。改完说不出理由的，基本可以判定为无效改动或负优化。

5.4 问题四：模型卡在旧假设里，换角度能力弱于思维正常的人

用多了你会发现，Claude Code 在调试时也有“惯性”——如果第一轮分析时它认定是某个原因，后续即使你贴了新证据，它可能还是在原来的框架里打转。你问“会不会是内存问题”，它顺着说；你问“会不会是网络问题”，它也顺着说，本质上是没跳出最初的推理路径。

这种情况下，最有效的方法是新开一个会话，不带之前的讨论上下文，重新从零把现象、日志、代码贴一遍。因为新会话没有“记忆负担”，模型的推理会更发散，很可能提出一个跟上一轮完全不同、但更符合实际的方向。这就好比一个人思路卡死了，换个人来看，或许一眼就是新答案。

5.5 调试过程本身要注意的信息安全

把代码贴给 AI 工具这件事，不同公司有不同政策。如果你的项目涉及商业机密、未公开的算法、客户数据，建议在代码里提前脱敏。调试时要贴日志，日志里可能带个人身份信息或其他敏感内容，也建议先做替换。另外，如果公司的安全规则不允许把代码发给外部 AI 服务，就别硬来。

我个人的做法是：如果只是问“这类报错一般是什么原因”，不带具体代码，就不用脱敏；如果需要贴具体代码，先把项目里敏感的配置项、密钥占位符替换掉。别觉得麻烦，出事才叫麻烦。

5.6 调试提示词速查表

整理几个我日常调试时固定用的提示词模板，直接复制改改就能用：

这些模板的共同点：要求模型“给原因 + 给验证方法”，而不仅仅是“给结论”。这是我反复强调的核心。

6. 一套顺手好用的 Claude Code 调试工作流

讲了这么多，最后总结一套我目前每天都在用的调试工作流。它不一定适合所有场景，但对我来说效率提升很明显，你可以按自己的习惯调整。

第一步，启动会话时先声明角色：

你是一个有 15 年经验的后端开发专家，擅长通过日志和代码快速定位问题。现在我会给你提供现象、日志和代码，请先做分析，再给结论。不要直接修改代码，除非我明确要求。

这一句看着简单，但能把 Claude Code 从“代码生成器模式”切到“调试专家模式”，后面回答的侧重点和措辞都不一样。

第二步，贴“现象 + 相关日志”，先别贴代码，要求模型先基于日志给出方向。这一步是为了让模型在没有代码干扰的情况下，先建立对问题的“时间线感”。

第三步，根据模型指出的方向，贴上对应代码，让模型在代码层面验证。如果你不确定该贴哪些文件，用关键词让它搜索。

第四步，指定“验证方法”比指定“解决方案”优先级更高：

基于你的判断，请给出 2-3 种验证方法，按照验证成本从低到高排列。我先执行第一种验证，结果出来后再继续讨论。

这一步是让 Claude Code 帮你设计排查实验，而不是直接跳去修复。实验驱动的调试方式比纯推理可靠得多。

第五步，验证完拿到新信息，继续对话。反复这个循环，直到确认根因。注意：如果三轮讨论后毫无进展，果断新开会话重新描述，别在旧会话里死磕。

第六步，根因确认后，才进入修复。要么让 Claude Code 给出 diff 你 review，要么让它解释思路、你自己改。改完把新代码和改动说明反馈给它，让它检查是否可能引入其他问题。

这套流程的本质，是把 Claude Code 当成一个“不累的结对调试搭档”，你控制方向和节奏，它提供分析、假设、验证方案和代码 review。调试效率的提升不是来自它“替你做事”，而是来自“它帮你把注意力集中在最值得看的地方”。

7. 最后再分享一个我自己琢磨出来的小技巧

正文内容已经比较多，最后分享一个我坚持用很久的小技巧，在调试场景里特别好使：每次排查完一个问题，让 Claude Code 把“根因 + 判断依据 + 防止复发的检查点”写进一个 DEBUG_NOTES.md 文件里，丢到项目 docs 目录下。

这个习惯一开始只是为了防止自己忘了“上次那个诡异的 bug 是怎么查出来的”，后来发现价值远超预期：新同事接手项目时，直接看这份笔记，能避开我们趟过的绝大多数坑；过几个月自己忘了某个模块的“历史遗留问题”，翻笔记比重新查一遍快太多；而且 Claude Code 之后调试同一个项目时，你把这个文件喂给它，它能直接继承“项目的经验记忆”，分析问题时会主动排除已经排查过的方向。

你可以让 Claude Code 按固定格式写：

## Bug 记录模板 - 问题表现：(一句话描述现象) - 根因：(一句话描述本质原因) - 排查路径：(当时的推理链和关键证据) - 修复方案：(具体改动和文件) - 复发检查点：(未来观察什么指标可以提前发现同类问题)

坚持半年下来，这个文件就是这个项目的“人体 debug 记忆库”。我自己有不少项目，靠这份笔记把平均排查时间从几个小时压缩到了半小时以内。

调试这件事，工具永远在变，但“定位问题本质”的能力永远是核心。Claude Code 谈不上神奇，它就是一个比搜索引擎更聪明、比同事更有耐心的信息整合者——把它放在你的调试工作流里，让它帮你扫清“信息碎片化”的障碍，你会发现，很多以前要熬到凌晨的线上故障，现在真的能用一杯咖啡的时间解决。