Agent 走偏了怎么办：Agentic 编程实战课 11

本文是「Agentic 编程实战课」系列的调试篇。哪怕规格写得再细、任务拆得再准，Agent 还是会走偏：你让它做 A，它做了 B；或者中途报错卡住；或者越改越烂。这一篇讲怎么冷静应对：怎么诊断问题、怎么纠偏、什么时候该回退而不是硬修。读完这篇，Agent 卡壳时你会有一套固定的处理动作，不会再因为反复失败而崩溃。

先调整心态：Agent 走偏是常态

先说一个反预期的事实：即使是顶级工程师，每天也要花三到五成时间在纠偏上。Agent 走偏不是你做错了什么，而是 Agentic Coding 的常态。新手遇到走偏的反应是慌、乱试、越搞越烂；高手的反应是冷静、诊断、精准修复。区别不在技术水平，在于有没有一套应对流程。

走偏通常分三种典型场景：

• 类型 A，理解偏差：你说画一只猫，Agent 画了老虎，产出能跑但不是你想要的。
• 类型 B，循环卡死：Agent 反复改同一个文件，改了二十次还是不对，陷入死循环。
• 类型 C，越改越烂：修了 bug A 引入 bug B，修 B 又引入 C，雪崩式恶化。

三种走偏的应对策略各不相同，下面分开讲。

类型 A：理解偏差，先让它复述

症状是 Agent 的产出能跑，但和你想要的不一样。诊断动作只有一步：让 Agent 复述它的理解。

停。先别改了。请用三句话告诉我：一、你理解的完成是什么样；二、你刚刚做了什么；三、你为什么这么做。

典型发现是 Agent 会回答：我理解你要的是 X。这时你意识到不，我要的是 Y。偏差就此定位完成，问题出在理解层，不是实现层。

纠正有三招。第一招补全规格：偏差往往是规格没说清，把这次的误解点补进规格，比如写明要的是家猫不是老虎、要写实风格不要卡通、背景要纯白方便做素材。第二招用反例：有时候说是什么很难，说不是什么更有效，直接列出不要红色按钮、不要弹出 alert 窗、不要拆成多个 HTML 文件。第三招给参考样本，这是最强的纠偏：给它看一个对的样子，让它参考目标网站的布局和交互重新实现。

类型 B：循环卡死，四个步骤

症状是 Agent 改同一个地方改了五次以上，每次都说修好了，跑起来还是错。根因是它陷入了局部死循环：用同一种思路反复试，而那条路根本走不通。

处理分四步。

第一步紧急刹车。输入一句「停。先不要继续改」，按 Esc 或 Ctrl+C 强制中断，不让它继续空转。

第二步让它放下代码分析：

不要写代码。请分析：一、这个 bug 的根本原因是什么，不是表象；二、你之前尝试的三种方法为什么都没成功；三、有没有完全不同的思路。

第三步换思路。如果它还在死胡同，就换会话重来：在新会话里描述 bug，列出已经失败过的方向，要求给出两三个全新思路。换会话等于换一位工程师看问题，新会话没有之前的思维包袱，更容易跳出死循环。

第四步退回上一个好版本。如果项目用 Git 做了版本管理，先翻提交历史找到还能跑的节点，回退之后从干净版本重新开始：

git log --oneline
git reset --hard <commit-id>

一位学员做图表组件时，Agent 改了八次数据还是不显示。这位学员喊停，让 Agent 先分析为什么显示不出来。Agent 深入检查后发现：之前的尝试都假设是数据格式问题，真正原因是图表初始化时机错了，DOM 还没渲染就被调用。换用延迟初始化的思路，一次成功。教训很简单：停下来分析，比埋头改快得多。

类型 C：越改越烂，立刻停止加回退

症状是修 A 坏 B，修 B 坏 C，最后整个项目都跑不起来。根因是项目失去了一致性：每次改动都在破坏之前建立的逻辑。这是最危险的情况，不要继续修了。

操作四步。第一，立刻 Ctrl+C 停止 Agent。第二，用 Git 回退到上一个稳定版本。第三，分析为什么会雪崩，常见原因有四个：任务太大没有分解；修改之前没跑测试；没有清理上下文，旧的错误思路一直在污染后续会话；没理解全貌就乱改。第四，用任务分解的方法重新拆解，一次只做一个小任务，每个小任务完成后立刻提交并跑测试，确认通过再做下一个。

一个反面教材：有位学员晚上十点开始修一个 bug，越改问题越多，到凌晨两点项目彻底跑不起来。复盘他的错误：项目没有 Git，想回退也没得退；不停加新代码而不是回退；累了硬扛不休息；没有测试，不知道到底改坏了哪里。正确做法本可以是：十点发现异常就翻提交历史，十点十分回退到下午的稳定版本，十点二十重新分解任务并补上测试，十一点修好睡觉。心法只有一句：永远保留一个能跑的版本，这也是 Git 版本管理如此重要的原因。

调试决策树与症状速查

遇到问题，先对号入座再动手。按这棵决策树排查：

常见症状速查表：

学会读错误信息

报错不可怕，错误信息是 Agent 和系统在跟你说话，学会读它就能定位大部分问题。以一段典型的 Python 报错为例：

Traceback (most recent call last):
  File "main.py", line 42, in <module>
    result = calc_total(data)
  File "main.py", line 18, in calc_total
    return sum(numbers)
TypeError: unsupported operand type(s) for +: 'int' and 'str'

读的顺序是从下往上：最后一行告诉你错误类型，这里是类型错误，int 和 str 不能相加；倒数第二段告诉你错在哪个文件第几行；再往上是调用链，告诉你谁调用了这段代码。

最快的三步诊断：看最后一行，确定错误类型；看倒数第二段，定位文件和行号；把整段错误信息原样贴给 Agent，让它分析。给 Agent 报错的正确姿势是贴完整堆栈，并且明确要求它先告诉你原因，再动手修复，不要直接改代码。先分析再修，能避免草率改动，方案也更靠谱。

常见错误类型对照：SyntaxError 是语法错，常见于少了括号或冒号；TypeError 是类型错，数据类型不对；NameError 是变量没定义；FileNotFoundError 是路径错了；KeyError 是字典里没这个键；IndexError 是数组越界；ImportError 是库没装；PermissionError 是没有读写权限。

调试时的心态管理

调试最大的敌人不是技术，是情绪。三条心态铁律：第一，Agent 不是我，它错不等于我笨，把它当工具，别把它的失败当成对自己的否定；第二，改不动就退，退回上一个版本永远是最优解之一，不要执念于再试一次；第三，累了就停，凌晨两点不要调 bug，睡一觉往往第二天十分钟就解决。

一个反直觉的建议：当你改了三十分钟还没解决，立刻停下来。不是因为你笨，是你陷入了沉没成本陷阱，舍不得放弃前面三十分钟的改动，但继续下去只会更糟。正确动作是：先 commit 保存当前状态，哪怕是坏的；起立走五分钟；回来后回退到稳定版本重新想。多数卡了两个小时的问题，睡一觉或散个步回来十分钟就解决了。

一个完整的调试案例

场景：销售看板突然不显示数据，整个调试过程八分钟。

第一步冷静：深呼吸，先看提交历史，找最近一次能跑的版本。第二步复现：让 Agent 跑 main.py 确认问题，并检查控制台有什么错误信息。Agent 报告：TypeError: NoneType object is not subscriptable，出现在 chart.py 第 67 行。第三步诊断，明确要求它先分析再动手：

不要急着改。请分析：一、第 67 行在做什么；二、为什么这里的变量是 None；三、这个 bug 是什么时候引入的，看一下 Git diff。

Agent 分析出：第 67 行是 title = data[0]['name']，data 来自 load_csv()，而 load_csv() 返回了 None，因为读不到文件；读不到文件是因为前一天改了目录结构，路径失效了。根因找到：不是图表的问题，是路径的问题。第四步精准修复：指定修复 load_csv() 的文件路径，改成相对路径 os.path.join(os.path.dirname(file), 'data.csv')，修完跑一遍。第五步回归：跑所有测试，确认没有破坏其他功能，全部通过，收工。

关键在于：全程没有让 Agent 埋头乱改。先诊断、找根因、再精准修，这是调试的高效节奏。

动手练习

练习一：找一个你做过的项目，故意让 Agent 改一处明显不对的地方制造 bug，然后按本文的方法读错误信息，让 Agent 先诊断再修复。

练习二：在你的 CLAUDE.md 里加一节调试规则：

## 调试规则
- 修 bug 前先复现，写一个失败的测试
- 先告诉我原因，再改代码
- 修完跑全量测试
- 改了三十分钟没好，停下回退

练习三：回忆你过去一次卡壳的经历，按上面的调试决策树重新走一遍，看看当时你走对了没有。

要点回顾

1. Agent 走偏是常态，高手的区别在于应对。
2. 三种走偏：理解偏差、循环卡死、越改越烂。
3. 通用对策：先停，再诊断，精准修，最后回归。
4. 读错误信息从下往上看：先看类型，再看位置。
5. 给 Agent 报错：让它先分析根因再修。
6. 改三十分钟没进展立刻停，避开沉没成本陷阱。
7. 永远保留一个能跑的版本，这是调试的底气。

最后补一句：这篇反复出现的动作是回退到稳定版本，前提是项目有版本管理。如果你的项目还没有用上 Git，先补上这一课，再放手让 Agent 干活。本文的调试方法论参考了 David Agans 的《Debugging》与一线实战经验。