为什么你的 AI Agent 总是在同一个文件上反复出错

在使用 AI 编程 Agent 时，有一种特定的故障模式经常出现：Agent 对同一个文件连续编辑两次、三次，有时甚至四次。每一次编辑要么撤销了上一次修复的内容，要么引入了新的问题，或者做出的修改显然不是你所要求的。

当这种情况发生时，直觉会让你去责怪模型。但在实践中，模型几乎从来不是根本原因。问题几乎总是出在会话的结构方式上。

三大原因

在多次处理这种模式后，我发现它源于三个不同的方面：

1. Agent 在编辑文件前没有读取它。

这是最常见的原因。Agent 基于其先前的上下文（它在会话早期读取的内容、从相关文件中推断出的内容、从错误信息中假设的内容）进行编辑，而不是基于文件的当前状态。如果文件已经被部分编辑过，Agent 对它的心理模型就是过时的。

你通常可以通过观察工具调用来发现这一点。如果 Agent 在没有预先读取同一个文件的情况下调用了编辑工具，那么它就是在基于缓存的假设工作。

2. 指令在冲突点含糊不清。

Agent 理解大致意图，但在遇到特定的决策点时，指令没有说明该怎么做。它没有停下来询问，而是进行猜测。猜测错了，你纠正它，然后 Agent 在下一次尝试时又做出不同的猜测——通常会退回到原来的方法，因为那是指令所暗示的。

这表现为一种来回拉锯，Agent 在同一修改的两个版本之间摇摆不定。

3. 上下文窗口中存在矛盾。

在会话的早期，Agent 读取了一些内容（注释、类型定义、测试），这些内容与你现在要求它做的事情相冲突。Agent 试图同时满足这两个约束，但失败了。每次编辑都试图对同一个潜在冲突进行不同的解决。

如何诊断你的情况

首先查看工具调用的顺序，而不是输出结果。大多数 Agent 编程工具都会向你展示 Agent 一步步做了什么。

• 如果你看到没有预先读取就进行了编辑：原因 1。停止，告诉 Agent 先读取文件，然后再尝试。
• 如果编辑在两个相似的状态之间摇摆：原因 2。编写更具体的指令，涵盖确切的决策点。不要只是换个说法——要加上 Agent 缺失的约束条件。
• 如果编辑一直在变，但都不是你想要的：原因 3。这是会话中途最难修复的问题。最可靠的解决方案是开启一个上下文更干净的新会话。

无需重头开始的修复方法

对于原因 1 和 2，你通常可以在不重启的情况下恢复：

停止。读取 middleware/auth.go 从第 1 行到最后一行。
然后告诉我当前的 validAPIKey 函数做了什么。
先不要编辑任何内容。

在下一次编辑之前强制执行一个显式的“读取-解释”步骤，让 Agent 有机会将其模型与实际文件状态同步。一旦它能准确描述当前内容，下一次编辑通常就是正确的。

对于原因 2，修复方法是添加一个具体的约束：

bearerToken 函数应该先检查 API 密钥，然后再回退到 JWT。
不要更改函数签名。不要添加新参数。
JWT 解析块应保持不变。

你对“不应该改变什么”描述得越具体，Agent 猜测的空间就越小。

何时该重新开始

如果你已经尝试了上述针对性的修复方法，但 Agent 仍然在循环，说明会话中积累了太多冲突的上下文，无法干净地恢复。开启一个新会话比继续调试现有的会话要快得多。

在关闭之前，请记录：

• 一直出错的确切文件和函数
• Agent 一直忽略的约束条件
• 以具体术语描述的正确最终状态

带着这些描述开启新会话。你会比试图挽救那个混乱的会话更快地得到正确的编辑结果。

基本原则

AI Agent 不会在同一个文件上循环是因为它们在人类意义上“坏了”或“困惑了”。它们循环是因为它们正在优化以使其与上下文窗口中的所有内容保持一致，而该上下文中的某些内容指向了错误的方向。

修复方法几乎总是改变上下文中的内容——通过强制重新读取、使指令更精确，或者从头开始。在相同的上下文中重试相同的提示词很少能产生不同的结果。