CLAUDE.md 写错一行：为什么 Agent 会全程跑偏
许多人最初认为，AI Agent在项目中频繁改错文件、陷入测试循环，是模型本身不够智能。经过三天排查，我才发现真正根源，竟是CLAUDE.md中一行模糊规则引发的连锁反应。
当时我正在重构一个视频项目的布局，为图省事，在项目主规则中写下：“优化整体界面排版，确保移动端显示正常”。
结果，仅喝杯茶的功夫，AI终端Agent（Claude Code）不仅修改了移动端布局，还自作主张重构了桌面端逻辑，改写了package.json引入新排版依赖，并将半个仓库的CSS全部改得面目全非。一运行构建，满屏报错。AI在终端里发了疯似的一边道歉，一边继续盲目修改，直至彻底耗尽我的Token额度。
【此处配图：一行红色的配置代码在IDE中高亮，下方指示箭头指向一个由齿轮和代码崩塌组成的废墟，代表一行配置错误导致的连锁跑偏】
作为一个每天依赖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注意力涣散并开始瞎猜 | 先通过全局符号搜索，精简上下文 |
| “做完在终端里告诉我一声” | 聊天框内虚报完成，本地无记录且无法追踪 | 强制要求将任务结果以当前任务结果.md格式写入文件 |
三、 解决方案：一套可复制的防跑偏套件
要想让Agent规规矩矩工作，必须在项目根目录下配置以下三件套：
1. 项目主规则（以AGENTS.md为例）
主规则用于规定Agent的“人设”与“禁忌物理边界”。不写入具体业务逻辑，仅包含硬性准则：
# 核心执行准则 - 物理边界：除任务单指定的TargetFile外，禁止修改任何其他文件。 - 行为守则：禁止进行任何范围外的重构。发现无关Bug仅记录，严禁顺手修改。 - 终端限制：若连续3次跑测试报错且无法定位，必须立即停止执行并向用户报告，禁止空转。
2. 执行任务单
每次安排Agent任务时，须下发一份格式化、边界清晰的任务单。可将其保存在本地，让AI优先读取：
# 执行任务单 - 日期：2026-06-16 - 目标：修复登录超时无重试的Bug - 指定对象（物理边界）：`/src/auth/login.ts` - 必须完成：在`login`函数内实现最多3次重试，每次间隔1000ms - 禁止事项：严禁修改`/src/utils/http.ts`下的通用拦截器逻辑
3. 明确的验收清单
告知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时设定最大运行步数限制，防止死循环跑单测烧钱。
- 测试闭环：让AI修改代码前，先要求它写出对应单元测试，通过测试约束其输出，而非用大白话辩论。
- 结果落到文件：避免Agent在聊天框发周报。强制要求将修改结果写入项目内可见的Markdown文件，便于随时Diff验收。
通过系统化配置规则、任务单与验收清单，你便能将AI Agent彻底“关进笼子”，让每一次代码修改都精准高效，彻底告别“鬼打墙”式的资源浪费。