CLAUDE.md 写错一行，为什么 Agent 会全程跑偏？
EA同学
我之前一直以为 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 自由发挥，越界重构半个项目 | 给定具体的执行任务单和物理边界 |
| “直接读取全仓库找出 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 条落地动作
- 物理隔离规则：立刻把你的
.cursorrules或CLAUDE.md瘦身，把具体的“临时开发指令”删干净，只保留全局的编码规范和物理隔离禁令。 - 锁死修改权限：给 Agent 的第一条指令永远是：“除了指定的修改文件，禁止碰其他任何文件。”
- 设置单次步骤上限：在调用 Agent（如 Claude Code）时，设定最大运行步数限制，防止死循环跑单测烧钱。
- 测试闭环：在让 AI 修改代码前，先让它写出对应的单元测试。通过测试来约束它的输出，而不是用大白话跟它辩论。
- 结果落到文件：不要让 Agent 在聊天框里给你发周报。强制要求它将修改结果写成项目内可见的 Markdown 文件（如
当前任务结果.md），确保你可以随时 Diff 验收。
到此这篇关于CLAUDE.md 写错一行，为什么 Agent 会全程跑偏？的文章就介绍到这了,更多相关CLAUDE.md 写错内容请搜索脚本之家以前的文章或继续浏览下面的相关文章，希望大家以后多多支持脚本之家！