我之前一直以為 Agent 在項目里頻繁改錯文件、無限循環(huán)跑單測是模型不夠聰明。后來排查了三天，我才發(fā)現(xiàn)，真正的問題居然是因為我在 CLAUDE.md 里寫錯了一行模糊的規(guī)則。

當(dāng)時我重構(gòu)一個視頻項目的布局，為了省事，在項目主規(guī)則里寫了句：“優(yōu)化整體界面排版，確保移動端顯示正常”。

結(jié)果，我喝杯茶的功夫，AI 終端 Agent（Claude Code）不僅改了移動端布局，還自作主張幫我重構(gòu)了桌面端邏輯、改寫了 package.json 引入了新的排版依賴，并把半個倉庫的 CSS 全修改成了 diff。一跑構(gòu)建，滿屏報錯。AI 還在終端里發(fā)了瘋似的一邊道歉一邊繼續(xù)盲目亂改，直到把我的 Token 額度徹底燒光。

【此處配圖：一行紅色的配置代碼在 IDE 中高亮，下方指示箭頭指向一個由齒輪和代碼崩塌組成的廢墟，代表一行配置錯誤導(dǎo)致的連鎖跑偏】

作為一個每天全靠 AI 敲代碼的獨立開發(fā)者（一人 AI 公司），我踩過了無數(shù)次 Agent“鬼打墻”的坑。今天咱們不講概念，只聊實操：為什么你寫的規(guī)則文件總是起反作用？如何通過項目規(guī)則、任務(wù)單和驗收清單，馴服你的 AI Agent？

一、 為什么你的 Agent 總是越改越亂？

大模型在做 Agent 執(zhí)行任務(wù)時，有幾個天然的心智弱點。如果你的項目配置規(guī)則（.cursorrules / CLAUDE.md / AGENTS.md）寫得不夠嚴(yán)密，它一定會踩進這三個泥潭：

1. 臨時指令與長期規(guī)則混淆

很多程序員習(xí)慣在項目規(guī)則里寫：“修復(fù)本模塊的 Timeout Bug，不要使用外部依賴。” 這是一個典型的“臨時指令”。一旦你把它固化進項目規(guī)則，在接下來的所有對話和開發(fā)任務(wù)里，Agent 每次啟動都會被強行喂入這個舊指令。這不僅嚴(yán)重污染了 Context（上下文），還會導(dǎo)致 AI 產(chǎn)生邏輯錯亂，在做別的事情時依然在死磕舊模塊。

2. 缺乏“物理邊界”的約束

你對 AI 說：“幫我優(yōu)化一下這個支付接口。” 在 AI 的認(rèn)知里，“優(yōu)化”是一個沒有物理邊界的詞。大模型會為了“讓代碼看起來更好”，去修改底層的通用工具類、改動外部的路由配置。因為你沒有告訴它“只許修改 target_file 里的內(nèi)容”，它就會默認(rèn)自己擁有全倉庫的所有權(quán)，最終越界修改，把無辜的代碼改崩。

3. 沒有“物理熔斷”的驗收標(biāo)準(zhǔn)

當(dāng) AI 修改完代碼，發(fā)現(xiàn)編譯報錯時，它的本能是自我糾錯。它會在終端里自動執(zhí)行 npm test，根據(jù)報錯繼續(xù)改。但如果此時測試代碼寫得有歧義，AI 就會在沒有人類干預(yù)的情況下，陷入“修改-測試-報錯-再修改”的無限死循環(huán)。直到把你的 Token 燒到熔斷，它才會停下來。

二、 避坑指南：三種寫法的常見結(jié)果對比

在軟件工程中，曖昧的表達(dá)是 Bug 的溫床。以下是我們在實戰(zhàn)中整理出來的規(guī)則寫法對比：

三、 解決方案：一套可復(fù)制的防跑偏套件

要想讓 Agent 規(guī)規(guī)矩矩干活，你必須在項目根目錄下，補齊這三件套：

1. 項目主規(guī)則（以AGENTS.md為例）

主規(guī)則用于規(guī)定 Agent 的“人設(shè)”與“禁忌物理邊界”。不要往里寫具體的業(yè)務(wù)邏輯，只寫硬性準(zhǔn)則：

# 核心執(zhí)行準(zhǔn)則
- 物理邊界：除任務(wù)單指定的 TargetFile 外，禁止修改任何其他文件。
- 行為守則：禁止進行任何范圍外的重構(gòu)。發(fā)現(xiàn)無關(guān) Bug 僅記錄，嚴(yán)禁順手修改。
- 終端限制：若連續(xù) 3 次跑測試報錯且無法定位，必須立即停止執(zhí)行并向用戶報告，禁止空轉(zhuǎn)。

2. 執(zhí)行任務(wù)單（Task Sheet）

每次安排 Agent 干活，必須給它下發(fā)一份格式化、邊界清晰的任務(wù)單。你可以把它保存在本地，讓 AI 優(yōu)先讀?。?/p>

# 執(zhí)行任務(wù)單
- 日期：2026-06-16
- 目標(biāo)：修復(fù)登錄超時無重試的 Bug
- 指定對象（物理邊界）：`/src/auth/login.ts`
- 必須完成：在 `login` 函數(shù)內(nèi)實現(xiàn)最多 3 次重試，每次間隔 1000ms
- 禁止事項：嚴(yán)禁修改 `/src/utils/http.ts` 下的通用攔截器邏輯

3. 明確的驗收清單（Checklist）

告訴 Agent，只有滿足哪些物理條件，任務(wù)才算真正結(jié)束：

## 驗收清單
- [ ] `/src/auth/login.ts` 代碼無編譯報錯
- [ ] 本地運行 `npm run test:auth` 單測且 100% 通過
- [ ] 將改動點與測試輸出記錄至項目目錄下的 `當(dāng)前任務(wù)結(jié)果.md`

四、 實戰(zhàn)改造案例：從“越改越亂”到“一步到位”

改造前（聊天式無邊界）

• 人類指令：“幫我優(yōu)化下支付超時重試。”
• Agent 動作：全倉庫掃描 -> 發(fā)現(xiàn) http.ts 命名不順眼 -> 順手重構(gòu)了通用 HTTP 類 -> 修改了支付邏輯 -> 通用類重構(gòu)導(dǎo)致全局路由崩塌 -> Agent 陷入 12 輪循環(huán)調(diào)試 -> 燒掉 25 刀 Token 后宣告失敗。

改造后（約束式任務(wù)單）

• 人類指令：“先確認(rèn)項目根目錄下的 AGENTS.md。然后讀取 任務(wù)單.md，開始執(zhí)行。”
• Agent 動作：讀取主規(guī)則（確立物理邊界）-> 讀取任務(wù)單（鎖定只能修改 login.ts）-> 精準(zhǔn)修改 3 行重試邏輯 -> 跑特定單測 -> 通過驗收 -> 自動寫入 當(dāng)前任務(wù)結(jié)果.md -> 提示用戶檢查，停止運行。全程耗時 40 秒，Token 賬單 0.15 刀。

五、 馬上抄去用的 5 條落地動作

1. 物理隔離規(guī)則：立刻把你的 .cursorrules 或 CLAUDE.md 瘦身，把具體的“臨時開發(fā)指令”刪干凈，只保留全局的編碼規(guī)范和物理隔離禁令。
2. 鎖死修改權(quán)限：給 Agent 的第一條指令永遠(yuǎn)是：“除了指定的修改文件，禁止碰其他任何文件。”
3. 設(shè)置單次步驟上限：在調(diào)用 Agent（如 Claude Code）時，設(shè)定最大運行步數(shù)限制，防止死循環(huán)跑單測燒錢。
4. 測試閉環(huán)：在讓 AI 修改代碼前，先讓它寫出對應(yīng)的單元測試。通過測試來約束它的輸出，而不是用大白話跟它辯論。
5. 結(jié)果落到文件：不要讓 Agent 在聊天框里給你發(fā)周報。強制要求它將修改結(jié)果寫成項目內(nèi)可見的 Markdown 文件（如 當(dāng)前任務(wù)結(jié)果.md），確保你可以隨時 Diff 驗收。

到此這篇關(guān)于CLAUDE.md 寫錯一行，為什么 Agent 會全程跑偏？的文章就介紹到這了,更多相關(guān)CLAUDE.md 寫錯內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評論