3.13 调试与排错
预计耗时：12 分钟
本关任务简报
Claude Code 大多数时候工作良好，但它不是不会出问题：有时候会陷入循环、坚持错误方案、消耗完上下文还没搞定任务、或者工具调用一直报错。
这类情况不是 Claude 变笨了，而是工作流出了问题——上下文污染、任务边界不清、错误的反馈方式。知道如何诊断和修复这些问题，你才能在出问题时快速止损，而不是干等或者放弃。
开始前先检查装备
| 前置知识 | 说明 |
|---|---|
| 进阶使用前几节 | 这一关是"出了问题怎么处理"，需要你先有实际使用经验，否则这里的信号和场景对你来说还是抽象的 |
| 2.6 会话管理 → | /compact、/clear、/cost 等命令是这一关的核心工具 |
通关奖励：解锁以下技能
- 🔍 能识别 Claude Code 常见的失控信号
- 💰 会用
/cost监控 token 消耗，在合适的时机干预 - 🔄 掌握"上下文污染"的处理方法
- 🛑 知道什么时候该中断、什么时候该重来、什么时候该换策略
机制解析
识别失控信号
Claude Code 出问题时，通常有几个可识别的信号：
| 信号 | 含义 | 处理方向 |
|---|---|---|
| 同一个错误反复出现 3 次以上 | Claude 在循环，没有真正理解根本原因 | 中断，重新描述问题 |
| 改了 A，又改了 B，又改回了 A | 上下文矛盾，Claude 在不同指令间摇摆 | 中断，明确一个方向 |
| 工具调用数量异常多（10 次以上没有明显进展） | 探索没有聚焦 | 中断，缩小问题范围 |
| 回复开始变短、变模糊、重复之前说过的内容 | 上下文接近上限，Claude 开始丢信息 | /compact 或 /clear |
| 开始给出"建议你考虑..."但不实际执行 | 任务对当前上下文来说太复杂 | 拆分任务，新会话处理 |
工具一：/cost 监控消耗
/cost/cost 显示当前会话已消耗的 token 和估算费用。有几个判断标准：
- Context 使用率 < 50%：没问题，继续工作
- Context 使用率 > 70%：考虑
/compact，否则后续回复质量下降 - Context 使用率 > 90%：必须
/compact或开新会话，再不处理会直接出错
养成习惯：每隔 15-20 轮对话看一次 /cost，在出问题之前主动干预。
工具二：中断和倒回
Escape 中断：Claude 的回答方向不对，或者正在做错误的事，立刻按 Escape。不用等它说完，说完了反而更难纠正，因为那时候错误的内容已经进了上下文。
双击 Escape 倒回：如果 Claude 做了几步错误操作，用倒回功能撤销到问题出现之前的那一轮。倒回菜单会让你选恢复范围——代码和对话一起回、只回对话、或只还原代码。它能还原 Claude 用编辑工具改的文件，但管不了 bash 命令（rm/mv 等）造成的改动，也不替代 Git。完整说明见 2.6 会话管理 →。
工具三：上下文污染处理
"上下文污染"是指会话里积累了过多错误的信息、矛盾的指令、或者跑偏方向的内容，导致 Claude 后续的表现越来越差。
判断方法：让 Claude 复述它当前的理解：
停一下。告诉我你现在对这个任务的理解是什么，
你打算怎么做，目前完成了哪些步骤。如果它的复述里有明显的误解，说明上下文已经污染了。
处理方法（按严重程度）：
- 轻微污染：直接纠正，明确说"之前我说的 X 是错的，正确的应该是 Y"
- 中度污染：
/compact压缩后继续，压缩会保留核心信息但去掉无用对话 - 严重污染：
/clear清空上下文，新会话里用更好的方式重新描述任务
工具四：工具调用失败的排查
当 Claude 的某个工具调用一直报错，不要只是反复让它"再试一次"：
第 1 步：让 Claude 解释它打算怎么做
先不要执行，告诉我你接下来打算运行什么命令，理由是什么。有时你会发现 Claude 计划做一件根本不存在的事。
第 2 步：自己手动运行命令验证
在 Claude Code 里用 !命令 手动执行，直接看错误信息：
!npm run test -- --testFile=auth.test.ts把真实的错误信息贴给 Claude，比让它猜要高效得多。
第 3 步：缩小范围
工具失败时，缩小范围比扩大范围更有用：
❌ 帮我运行所有测试并修复所有错误
✅ 帮我只运行 auth.test.ts，只修复第一个失败的测试常见失控场景及处理
场景：Claude 反复给出相同的错误答案
我注意到你连续三次给出了类似的方案，但都没有解决问题。
先不要再给方案。帮我做一件事：
列出你认为这个 bug 可能的根本原因（3-5 个），
每个可能性说明你的推理依据。
我来判断哪个方向值得继续探索。把"给答案"改成"列假设"，强迫 Claude 重新推理而不是重复同一个方向。
场景：Claude 一直在修改代码但没有越来越好
每次修改后都要求验证：
在继续改下一个地方之前，先运行一次测试，确认这次修改没有引入新问题。让每一步有验收标准，避免"改了一大堆，最后哪里出问题都不知道"。
场景：任务进行到一半，Claude 说"这个任务太复杂了，需要更多信息"
这通常意味着任务边界不清楚。不要试图"补充信息"，而是重新拆任务：
好，我们只做这个任务里最小的、最独立的一步：[具体说是哪步]
其他的下一个会话再处理。开始闯关
目标：主动制造一个"失控场景"，然后用这关的工具把它处理掉。
第 1 步：运行 /cost，记录当前状态
在一个已经工作了一段时间的会话里运行 /cost，记下 Context 使用率。
第 2 步：让 Claude 复述当前任务理解
停一下。告诉我你现在认为我们正在做什么任务，
你已经完成了哪些步骤，接下来计划做什么。如果复述有偏差，练习用"直接纠正"的方式校正而不是重新开会话。
第 3 步：练习主动 /compact
Context 使用率超过 60% 时，主动运行 /compact，观察压缩后 Claude 的状态有没有变化。
通关检定
- [ ] 能识别至少 3 种 Claude Code 失控信号
- [ ] 用过
/cost查看 token 消耗，知道什么时候该干预 - [ ] 知道上下文污染的判断方法（让 Claude 复述当前理解）
- [ ] 知道 Escape / 双击 Escape 各自能做什么
- [ ] 遇到工具反复失败时，知道缩小范围比扩大范围更有用
全部点亮就算通关 ✓
卡关了？翻车指南在这
任务工程量大、逻辑复杂，Claude 屡次出错，感觉越改越乱
这是正常的，不是 Claude 变笨了——复杂任务本来就需要调试。应对方法：逐步定位，不要试图一次修完。先让 Claude 描述它对问题的当前理解，确认它抓住了正确的根本原因；每次只修一个地方，修完立刻验证；如果 N 次修改之后还在绕圈子，说明上下文已经被错误信息污染，果断开新会话重新描述问题。
有时候重来一次的成本远低于继续在一个污染会话里死磕。
Claude 说任务太复杂、工具调用次数达到上限、或者突然停止执行
Claude Code 对单次会话有处理边界：工具调用轮次有上限，上下文窗口也有限。如果 Claude 停在中途说"任务太大"或不再执行操作，说明你碰到了这个边界。
解决方法：
- 记录当前完成了哪些步骤（让 Claude 总结一下进度）
- 提交当前的 git 状态，建一个干净的检查点
- 开新会话，告诉 Claude"我们已经完成了 X，现在只需要做 Y"
把大任务拆成多个小会话是处理这类边界最有效的方法，详见 3.11 大型代码库处理 →。
Claude 做了很多工具调用，但文件改得一团糟，怎么恢复
首先检查 git 状态：
git diff
git status如果代码在 git 追踪范围内，git checkout . 可以还原所有未提交的改动。好习惯是在每次开始重要任务前先 git add && git commit，这样随时有干净的回滚点。
/compact 之后 Claude 忘了很多重要信息
/compact 会保留核心内容，但确实会丢失细节。遇到这种情况，在 /compact 之后主动把关键信息补充给 Claude：
/compact 之后，提醒你几个重要的约定：
- 我们正在修复的是登录超时的 bug
- 已经确认问题在 session.service.ts 第 47 行
- 解决方案是延长 TTL 而不是修改刷新逻辑Claude 一直不停地执行，不暂停等我确认
这通常是因为切到了 accept edits on 模式。按 Shift+Tab 切回默认模式（无标记），这样每步工具调用都会暂停等你确认。对复杂任务，默认模式才能保持你的控制权。
下一关
学会从失控状态恢复后，最后一关讲一个很实用的新能力——让电脑上跑着的会话能用手机随时接管，干活不必守在电脑前。