CLAUDE.md 写错一行，为什么 Agent 会全程跑偏？

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

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

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

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

对于每天全靠 AI 敲代码的独立开发者（一人 AI 公司）来说，踩过无数次 Agent“鬼打墙”的坑。今天咱们不讲概念，只聊实操：

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

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

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

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

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

如果对 AI 说：“优化一下这个支付接口。” 在 AI 的认知里，“优化”是一个没有物理边界的词。大模型会为了“让代码看起来更好”，去修改底层的通用工具类、改动外部的路由配置。因为没有告诉它“

”，它就会默认自己拥有全仓库的所有权，最终越界修改，把无辜的代码改崩。

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

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

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

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

错误写法	常见跑偏结果	正确工程做法
“帮我优化一下这个类”	Agent 自由发挥，越界重构半个项目	给定具体的执行任务单和物理边界
“直接读取全仓库找出 Bug”	Token 快速烧光，AI 注意力涣散并开始瞎猜	先通过全局符号（LSP）搜索，精简上下文
“做完在终端里告诉我一声”	聊天框内虚报完成，本地无记录且无法追踪	强制要求将任务结果以 当前任务结果.md 格式写入文件

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

要想让 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 验收。