3.8 Agent 跑偏、报错、卡住时如何恢复¶
阅读完本节后，你应该能处理本地 Agent 常见失败：理解错需求、改错文件、测试失败、上下文漂移、陷入反复修补。
会用 Agent 的关键，不是它永远不犯错，而是你能把它拉回可控轨道。
常见失败类型¶
| 类型 | 表现 | 根因 |
|---|---|---|
| 需求跑偏 | 做了你没要求的功能 | Goal / Out of Scope 不清楚 |
| 文件跑偏 | 改了无关模块 | Context Pointers 不足，没先 research |
| 风格跑偏 | 写法和项目不一致 | 没要求复用现有模式 |
| 修补循环 | 修一个错引入另一个错 | 没先定位根因 |
| 验证逃避 | 不跑测试就说完成 | Done Definition 太弱 |
| 上下文污染 | 把废案当需求 | 长对话里历史信息冲突 |
| 破坏用户改动 | 回滚或覆盖已有 diff | 没检查工作区状态 |
恢复第一原则¶
不要在混乱状态下继续让 Agent “再试试”。
先停下来，做三件事：
1. 冻结当前改动。
2. 重新建立事实。
3. 再决定修复、回退还是重做。
恢复提示词¶
停止继续实现。现在进入恢复模式。
请先不要修改文件，完成以下分析：
1. 当前任务原目标是什么。
2. 当前 diff 改了哪些文件。
3. 哪些改动和目标相关，哪些可能无关。
4. 当前失败的具体现象是什么。
5. 最可能的根因是什么。
6. 你建议保留、修改、撤销哪些改动。
注意：不要回滚用户已有改动，只讨论本次任务相关 diff。
这会把 Agent 从“继续写”切回“读和判断”。
测试失败时¶
不要让 Agent 盲修。
错误流程：
测试失败了，修一下。
正确流程：
测试失败了。先不要修改文件。
请分析失败日志：
- 哪个测试失败。
- 失败断言是什么。
- 是本次改动导致，还是环境/旧问题。
- 需要看哪些文件来确认根因。
- 给出最小修复计划。
如果它没有完整日志，把完整错误贴进去。不要只贴最后一行。
改错文件时¶
先让它识别无关改动。
请检查当前 diff，列出所有可能无关的文件和原因。
不要执行回滚。先告诉我哪些改动应该保留，哪些应该撤销。
确认后再让它用补丁方式撤销自己的无关改动。
只撤销你刚才列出的无关改动，保留用户已有改动和本任务必要改动。
不要让 Agent 用粗暴命令清空工作区，除非你非常确定且已经备份。
上下文漂移时¶
长会话里，Agent 可能混入旧目标。处理方式是重新压缩上下文。
请把当前会话压缩成一份继续任务所需的状态摘要：
- 原始目标。
- 已确认的约束。
- 已完成改动。
- 当前失败或阻塞。
- 下一步计划。
- 不要再考虑哪些废案。
然后开启新会话，把摘要和当前 diff 状态交给新的 Agent。
修补循环时¶
如果 Agent 连续修三次还失败，停止。
进入根因分析：
你已经连续修复多次但问题仍未解决。现在不要继续改代码。
请做 root cause analysis：
1. 我们实际观察到的事实是什么。
2. 哪些假设被验证过，结果是什么。
3. 哪些假设还没验证。
4. 最小复现是什么。
5. 下一步应该先加测试、打日志、读代码，还是回退方案。
修补循环通常说明缺的是事实，不是更多代码。
什么时候换工具¶
| 情况 | 换什么 |
|---|---|
| 需要重新思考产品方案 | 网页 Claude / GPT |
| 需要长文档对照 | Gemini CLI 或长上下文工具 |
| 需要真实读仓库和改文件 | Claude Code / Codex / OpenCode |
| 需要浏览器复现 | Playwright / Browser MCP |
| 需要查最新框架用法 | 文档 MCP / 官方文档 |
| 需要多人并行探索 | 多 Agent / worktree |
| 需要切换模型或本地模型 | OpenCode |
换工具不是逃避，而是承认当前工具上下文不合适。
恢复检查表¶
- [ ] 当前失败现象已经具体化。
- [ ] 当前 diff 已经看过。
- [ ] 无关改动已识别。
- [ ] 没有使用破坏性回滚命令。
- [ ] 根因假设至少验证一个。
- [ ] 新改动有对应测试或验证。
- [ ] 如果开启新会话，已准备状态摘要。