CLAUDE.md 出现一行错误 为何 Agent 全程偏离方向

我之前一直以为 Agent 在项目里频繁改错文件、无限循环跑单测是模型不够聪明。后来排查了三天，我才发现，真正的问题居然是因为我在 CLAUDE.md 里写错了一行模糊的规则。

当时我重构一个视频项目的布局，为了省事，在项目主规则里写了句：“优化整体界面排版，确保移动端显示正常”。

结果，我喝杯茶的功夫，AI 终端 Agent（Claude Code）不仅改了移动端布局，还自作主张帮我重构了桌面端逻辑、改写了 package.json 引入了新的排版依赖，并把半个仓库的 CSS 全修改成了 diff。一跑构建，满屏报错。AI 还在终端里发了疯似的一边道歉一边继续盲目乱改，直到把我的 Token 额度彻底烧光。

【此处配图：一行红色的配置代码在 IDE 中高亮，下方指示箭头指向一个由齿轮和代码崩塌组成的废墟，代表一行配置错误导致的连锁跑偏】

作为一个每天全靠 AI 敲代码的独立开发者（一人 AI 公司），我踩过了无数次 Agent“鬼打墙”的坑。今天咱们不讲概念，只聊实操：为什么你写的规则文件总是起反作用？如何通过项目规则、任务单和验收清单，驯服你的 AI Agent？

一、 为什么你的 Agent 总是越改越乱？

大模型在做 Agent 执行任务时，有几个天然的心智弱点。如果你的项目配置规则（.cursorrules / CLAUDE.md / AGENTS.md）写得不够严密，它一定会踩进这三个泥潭：

1. 临时指令与长期规则混淆

很多程序员习惯在项目规则里写：“修复本模块的 Timeout Bug，不要使用外部依赖。” 这是一个典型的“临时指令”。一旦你把它固化进项目规则，在接下来的所有对话和开发任务里，Agent 每次启动都会被强行喂入这个旧指令。这不仅严重污染了 Context（上下文），还会导致 AI 产生逻辑错乱，在做别的事情时依然在死磕旧模块。

2. 缺乏“物理边界”的约束

你对 AI 说：“帮我优化一下这个支付接口。” 在 AI 的认知里，“优化”是一个没有物理边界的词。大模型会为了“让代码看起来更好”，去修改底层的通用工具类、改动外部的路由配置。因为你没有告诉它“只许修改 target_file 里的内容”，它就会默认自己拥有全仓库的所有权，最终越界修改，把无辜的代码改崩。

3. 没有“物理熔断”的验收标准

当 AI 修改完代码，发现编译报错时，它的本能是自我纠错。它会在终端里自动执行 npm test，根据报错继续改。但如果此时测试代码写得有歧义，AI 就会在没有人类干预的情况下，陷入“修改-测试-报错-再修改”的无限死循环。直到把你的 Token 烧到熔断，它才会停下来。

二、 避坑指南：三种写法的常见结果对比

在软件工程中，暧昧的表达是 Bug 的温床。以下是我们在实战中整理出来的规则写法对比：

三、 解决方案：一套可复制的防跑偏套件

要想让 Agent 规规矩矩干活，你必须在项目根目录下，补齐这三件套：

1. 项目主规则（以AGENTS.md为例）

主规则用于规定 Agent 的“人设”与“禁忌物理边界”。不要往里写具体的业务逻辑，只写硬性准则：

# 核心执行准则
- 物理边界：除任务单指定的 TargetFile 外，禁止修改任何其他文件。
- 行为守则：禁止进行任何范围外的重构。发现无关 Bug 仅记录，严禁顺手修改。
- 终端限制：若连续 3 次跑测试报错且无法定位，必须立即停止执行并向用户报告，禁止空转。

2. 执行任务单（Task Sheet）

每次安排 Agent 干活，必须给它下发一份格式化、边界清晰的任务单。你可以把它保存在本地，让 AI 优先读取：

# 执行任务单
- 日期：2026-06-16
- 目标：修复登录超时无重试的 Bug
- 指定对象（物理边界）：`/src/auth/login.ts`
- 必须完成：在 `login` 函数内实现最多 3 次重试，每次间隔 1000ms
- 禁止事项：严禁修改 `/src/utils/http.ts` 下的通用拦截器逻辑

3. 明确的验收清单（Checklist）

告诉 Agent，只有满足哪些物理条件，任务才算真正结束：

## 验收清单
- [ ] `/src/auth/login.ts` 代码无编译报错
- [ ] 本地运行 `npm run test:auth` 单测且 100% 通过
- [ ] 将改动点与测试输出记录至项目目录下的 `当前任务结果.md`

四、 实战改造案例：从“越改越乱”到“一步到位”

改造前（聊天式无边界）

• 人类指令：“帮我优化下支付超时重试。”
• Agent 动作：全仓库扫描 -> 发现 http.ts 命名不顺眼 -> 顺手重构了通用 HTTP 类 -> 修改了支付逻辑 -> 通用类重构导致全局路由崩塌 -> Agent 陷入 12 轮循环调试 -> 烧掉 25 刀 Token 后宣告失败。

改造后（约束式任务单）

• 人类指令：“先确认项目根目录下的 AGENTS.md。然后读取 任务单.md，开始执行。”
• Agent 动作：读取主规则（确立物理边界）-> 读取任务单（锁定只能修改 login.ts）-> 精准修改 3 行重试逻辑 -> 跑特定单测 -> 通过验收 -> 自动写入 当前任务结果.md -> 提示用户检查，停止运行。全程耗时 40 秒，Token 账单 0.15 刀。

五、 马上抄去用的 5 条落地动作

1. 物理隔离规则：立刻把你的 .cursorrules 或 CLAUDE.md 瘦身，把具体的“临时开发指令”删干净，只保留全局的编码规范和物理隔离禁令。
2. 锁死修改权限：给 Agent 的第一条指令永远是：“除了指定的修改文件，禁止碰其他任何文件。”
3. 设置单次步骤上限：在调用 Agent（如 Claude Code）时，设定最大运行步数限制，防止死循环跑单测烧钱。
4. 测试闭环：在让 AI 修改代码前，先让它写出对应的单元测试。通过测试来约束它的输出，而不是用大白话跟它辩论。
5. 结果落到文件：不要让 Agent 在聊天框里给你发周报。强制要求它将修改结果写成项目内可见的 Markdown 文件（如 当前任务结果.md），确保你可以随时 Diff 验收。