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 验收。