為什麼 coding agent 會忽略你的指示?
指示檔案說要停止,coding agent 卻照做。了解 context window、harness、規則載入時機與內容衝突,先診斷原因,再決定是否重寫規則。
為什麼 coding agents 會忽略你的指示
coding agents 會因為 4 個原因忽略你的指示,而且原因不是你的語氣不夠強硬。規則可能從未進入 context window。規則可能過於模糊,無法用來檢查某個動作。context 中的其他內容可能與規則矛盾,通常就是 agent 剛讀取的程式碼。或者規則仍在載入狀態,但位於目前 turn 很前面的位置,agent 會依據附近的內容工作。
每個原因都有對應的修正方式,因此第一步是區分這些原因。使用大寫字母和 IMPORTANT 並不能診斷問題。以下機制以 Claude Code 為範例,因為截至 October 2026,其載入與壓縮行為已有詳細文件。其他工具的細節不同,但整體行為相同。
先說明 2 個術語。context window 是模型在特定 turn 看到的文字區塊,包括 system prompt、你的指示檔案、對話,以及 agent 讀取的每個檔案。harness 是模型周邊的程式,也就是從磁碟讀取檔案並組合該文字區塊的程式。本文幾乎所有抱怨,實際上都是對 harness 的抱怨,而不是對模型的抱怨。
指示檔案是訊息,不是設定
指示檔案不是設定檔。執行環境不會讀取 CLAUDE.md 並強制套用其中內容。執行框架會從磁碟讀取檔案,再將文字貼入對話。在 Claude Code 中,這些內容會以放在 system prompt 後方的 user message 傳送,因此模型看到這些規則的方式,與看到你輸入的其他內容相同。
這會導致一個令人不安的結果。你的規則會與視窗中的所有其他文字競爭,而且權重相同。規則只是一項主張。代理程式剛開啟的檔案則是證據。兩者不一致時,證據往往會勝出;系統也不會產生錯誤,因為從模型的角度來看,沒有任何事情出錯。
官方文件已清楚說明這一點:指示檔案會被視為內容,而不是受強制執行的設定。若要無論模型如何決定都阻止某項操作,就需要使用 hook,而不是寫下一句話。請記住這項原則。本文末尾的大多數修正方式,都是將這項原則套用到特定案例。
載入哪些指示檔,以及何時載入
Claude Code 會從啟動所在的目錄開始,沿著目錄樹向上搜尋。從檔案系統根目錄到目前工作目錄之間的所有 CLAUDE.md 和 CLAUDE.local.md,都會在啟動時完整載入。這些檔案會依該順序串接,因此距離啟動目錄最近的檔案最後讀取;在同一個目錄中,.local 檔案會附加在主要檔案之後。
位於目前工作目錄下方子目錄中的檔案,載入方式不同。它們不會在啟動時載入,而是在代理程式讀取該目錄中的檔案時載入。.claude/rules/ 中帶有 paths: frontmatter 欄位的路徑範圍規則也相同:只有在讀取符合條件的檔案時,才會加入內容,而不是每一輪都載入。自 v2.1.309 起,以這種方式載入的檔案也有每檔大小限制(200K 內容視窗為 40,000 個字元)。如果檔案較長,代理程式只會收到檔案開頭的內容,因此大型巢狀檔案接近結尾的規則可能永遠不會進入內容視窗。
這項差異可以解釋許多回報的失敗案例。你將規則放在 packages/api/CLAUDE.md,接著詢問 API,代理程式卻未開啟 packages/api/ 下方的任何檔案就直接回答。這不是規則被忽略,而是規則根本不存在於當次內容中。如果你的儲存庫將指引分散在 monorepo 中各套件的指示檔,每次都應先檢查這一點。
採用 AGENTS.md 的儲存庫還有另一個載入陷阱。自 v2.1.277 起,Claude Code 預設會將 AGENTS.md 讀取為專案指示,但只有在目前工作目錄及其上方所有目錄中都沒有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 時才會如此(個人的 ~/.claude/CLAUDE.md 不算在內)。只要加入其中任何一個檔案,即使只是存放個人備註的 CLAUDE.local.md,Claude Code 就會改為讀取你的 CLAUDE.md 檔案,並完全略過 AGENTS.md。若要同時載入兩者,請在 /config 將 Project instructions 設為 claude-md-and-agents-md。在 v2.1.277 之前的版本,或你想保留 CLAUDE.md 時,可使用 CLAUDE.md;其第一行是 @AGENTS.md,會在啟動時匯入該檔案,後面再放置 Claude 專用備註。如果沒有其他內容要加入,也可以使用符號連結。至於該檔案本身應放入哪些內容,則是另一個問題,詳見 將代理程式指示與人類文件分開。
確認檔案已載入,再進行改寫
在確認 agent 能讀取檔案之前,不要修改文字。這裡有 2 項檢查,先從成本較低的項目開始。
在工作階段中執行 /context。它會依類別列出目前的視窗內容,其中 Memory files 清單會列出啟動時載入的所有指示檔案。清單中沒有某個檔案,表示它未在啟動時載入;在有其他機制載入它之前,寫入該檔案的任何內容都不會生效。子目錄中的巢狀檔案不會出現在清單中,因為它們會按需載入;載入時,終端機會顯示包含其路徑的 Loaded 行。/memory 會列出檔案位置並開啟檔案供編輯,包括目前尚不存在的檔案。
若要取得更確切的結果,請記錄載入事件。每當 CLAUDE.md 或規則檔案進入內容時,InstructionsLoaded hook event 都會觸發;其中的 matcher 會說明載入原因:session_start、nested_traversal、path_glob_match、include 或 compact。將以下內容放入 .claude/settings.json:
{
"hooks": {
"InstructionsLoaded": [
{
"matcher": "nested_traversal",
"hooks": [
{
"type": "command",
"command": "cat >> /tmp/instructions-loaded.log"
}
]
}
]
}
}hook 會將 payload 以 JSON 形式寫入標準輸入,因此 cat 會附加完整記錄。工作時使用 tail -f /tmp/instructions-loaded.log 監看記錄。系統會忽略此事件的結束狀態,因此 hook 只能觀察,不能阻止載入。如果你預期巢狀檔案應該載入,但在該工作階段的記錄中始終沒有出現,請停止重寫文字。問題出在檔案位置。唯一例外是 Claude Code 直接讀取的 AGENTS.md 不會觸發此事件,因此請改在 /memory 中尋找其路徑。從 CLAUDE.md 匯入的 AGENTS.md 則會照常觸發此事件。
長時間工作階段對規則的影響
這裡有兩種不同的影響,需要採取不同的應對方式。
距離。 在執行壓縮前,第 1 回合指定的規則到了第 90 回合仍在上下文視窗中,但此時會與 90 回合較新、也更符合目前工作的文字競爭。壓縮執行後,只在聊天中輸入的規則可能完全不在視窗中:Claude Code 自身的文件警告,對話早期的指示可能遺失;這就是下方所述的第二種影響。你無法設定來消除距離,但可以測量它。請在新的工作階段中執行相同工作。如果規則在新工作階段中有效,卻在長時間工作階段的後段失效,原因就是距離或壓縮。
壓縮。 上下文視窗填滿時,工作框架會先摘要目前為止的對話,再從摘要繼續。能保留下來的是摘要工具判定重要的內容,這不一定等同於你認為重要的內容。Claude Code 會依不同機制說明結果,而差異很大。專案根目錄的 CLAUDE.md 與未限定範圍的規則,會在壓縮後從磁碟重新注入。自動記憶體也會從磁碟重新注入。帶有 paths: frontmatter 的規則會遺失,直到再次讀取符合條件的檔案。子目錄中的巢狀 CLAUDE.md 檔案會遺失,直到再次讀取該子目錄中的檔案。
依照該表排列指示後,脆弱程度的順序就很明顯。只在聊天中輸入的規則是工作階段中最脆弱的內容:只有摘要恰好保留它時,規則才會持續有效。位於 packages/api/CLAUDE.md 的規則次之,因為它只載入過一次,之後被摘要移除,必須等到下一次在該目錄中讀取時才會返回。專案根目錄檔案中的規則最持久,因為每次都會從磁碟重新讀取。
因此,如果某項指示必須在整個工作階段中持續有效,就應放在不含 paths: frontmatter 的專案根目錄檔案中。其他內容都屬於取捨,應由你有意識地決定。管理上下文視窗中保留的內容涵蓋使用 focus 引數的 /compact,以及在無關工作之間使用 /clear;這兩者都會改變摘要工具判斷你的規則內容的頻率。
為什麼周邊程式碼會勝過規則
這是人們最常描述、卻最少正確診斷的失敗情況。你的檔案寫明資料庫存取必須經由 repository layer。代理程式卻撰寫了直接呼叫 ORM(object relational mapper)的 handler。這不是因為它忽略了你的風格要求,而是因為證據數量勝出。
規則描述偏好。程式碼展示實例。代理程式開啟即將編輯的模組中 3 個檔案,而這 3 個檔案都直接呼叫 ORM 時,context 的一方是 1 句抽象描述,另一方則是 3 個具體、近期且符合任務的範例。複製本機模式通常是正確行為。這裡之所以錯誤,是因為你知道 context 不知道的資訊:那些檔案是 legacy code。
因此,請將這項資訊寫入規則。明確說明自身反例的規則,才能在實際 repository 中持續有效。只陳述偏好的規則則無法做到。
新增的資料庫存取必須經由app/repositories/。app/legacy/下的檔案仍會直接呼叫 ORM。那是舊程式碼,不是應遵循的模式。不要複製它。
真正發揮作用的是第 2 句。它在代理程式找到這些內容之前,先告訴代理程式將會看到什麼,以及應如何解讀。相同的修正方式也適用於任何明顯與 repository 不一致的規則:歷史紀錄未遵循的 commit 格式、測試套件中有一半未採用的測試配置,以及只適用於新程式碼的 import 慣例。只要程式碼與檔案內容不一致,就應在檔案中明確指出這項差異。
無法檢查的模糊規則,也就無法遵循
「撰寫乾淨的程式碼。」「不要過度工程化。」「保持簡單。」「小心處理遷移。」這些規則都無法針對特定操作進行測試,無論是由 agent 測試,還是由你測試。若 agent 收到一項無法用來檢查自身輸出的規則,就只能猜測,而你則憑感覺評分。
請對檔案中的每一行套用以下測試。寫出一個 shell 命令,讓規則被違反時以非零狀態結束。如果你無法寫出該命令,這項規則就無法檢查。比較以下範例:
- 無法檢查:「讓函式保持精簡。」可檢查:「長度超過 60 行的函式,其上方必須有註解說明原因。」
- 無法檢查:「測試你的變更。」可檢查:「執行
npm test,並在標記任務完成前貼上失敗數量。」 - 無法檢查:「保持檔案井然有序。」可檢查:「HTTP handler 必須放在
src/api/handlers/。該目錄不得放置其他內容。」 - 無法檢查:「正確格式化程式碼。」可檢查:「
.ts檔案使用 2 個空格縮排。」
「不要過度工程化」是人們最先放棄的規則,因為修正方式不是把句子縮短,而是把句子寫得更長:明確說明實際可行的最小變更是什麼,才能提供 agent 可用來比對自身 diff 的判準。
大小問題只是換了一種形式。Claude Code 的指引要求每個 instruction file 少於 200 行,並直接指出,檔案越長,遵循程度越低。700 行的檔案不代表指示更明確。它只是包含 700 行主張,彼此矛盾的機會更多,而且每一輪都會計入你的 context window,直接反映在 token 使用量中。將檔案分段,讓每項規則位於讀者可快速瀏覽的標題下,相關做法請參閱撰寫 agent 能夠執行的 instruction file。更好的做法,是刪除描述性內容,而非指示性內容:說明 handler 和 model 所在位置的目錄導覽,屬於 agent 可按需從解析後的 repository map查詢的結構,不必在每一輪都放入 context window。
如何在 10 分鐘內診斷
請依序執行以下步驟。直接跳到最後一步,往往只會讓人留下很長一份充滿強硬規則、但仍然無法運作的檔案。
- 確認規則已載入。 執行
/context並查看 Memory files 清單;如果是巢狀檔案,則在終端機中尋找其Loaded行。如果找不到該檔案,請修正位置後停止。目前清單中的其他步驟都還不適用。 - 在全新工作階段重現問題。 啟動新的工作階段,並交辦應觸發該規則的最小工作。在這裡遵循規則,但在長時間工作階段中失效,表示問題可能出在內容距離或壓縮。在這裡也失效,則表示問題出在規則本身。
- 移除競爭規則。 在現有程式碼本來就遵循該規則的目錄中,要求進行相同的變更。如果遵循情況恢復,表示周圍的程式碼覆蓋了你的規則文字。
- 搜尋衝突。 兩個檔案針對相同行為提供不同指示,是已知的失敗原因:模型可能任意選擇其中一個,而且不會告訴你它這麼做了。
- 讓規則可檢查後重新測試。 使用具體路徑與條件改寫規則。遵循情況大幅改善,表示成因在於措辭。
第 4 步只需執行一個命令。請搜尋所有指示來源中的相關主題,不要只搜尋你正在編輯的檔案:
grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null如果兩個檔案中的內容互相矛盾,問題就在這裡。刪除其中一個。不要試圖用更強硬的措辭替它們排序,因為沒有可供依循的排序引擎。在 Claude Code v2.1.283 或更新版本中,/doctor prompt-audit 會在指示檔案、規則與技能中執行更廣泛的搜尋,並回報矛盾及建議的編輯內容;在你提出要求前,不會變更任何內容。
依影響力排序的修正方式
以下每個步驟的影響力都高於前一個步驟,但設定成本也更高。規則只需重新措辭即可解決時,先從最上方開始。當規則重要到不能接受偶爾遺漏時,立即往下採用更嚴格的方式。
- 讓規則具體化。 指定路徑、命令或條件。加入代理程式會在儲存庫中找到的反證,如前文所示。這不需額外成本,卻能解決出乎意料多的問題。
- 將規則移到所管理內容附近。 例如巢狀的
CLAUDE.md、.claude/rules/中限定路徑範圍的規則,或直接加在檔案頂端的註解。如此一來,規則會與適用的程式碼在同一次讀取中載入。請接受這項取捨:以這種方式載入的內容會在下一次壓縮時被移除,並在下一次符合條件的讀取時恢復。 - 將強制執行移至 hook。 文字說明只是要求,hook 才能做出判定。Hook 會在固定的生命週期事件中以程式碼執行,不論模型得出什麼結論都會套用。
- 將規則交給確定性工具,並刪除文字說明。 例如格式化、匯入順序、行長度、禁止匯入項目及 commit 訊息格式。
ruff format、prettier --write、eslint、pre-commithook。格式化工具每次都能正確執行,且不消耗 token。句子大多數時候能正確傳達規則,但每次互動都會消耗 token。
以下完整說明步驟 3。假設 migration 檔案絕對不可由代理程式編輯。將以下內容放入 .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
}
]
}
]
}
}再將以下內容放入 .claude/hooks/guard-migrations.sh:
#!/usr/bin/env bash
set -euo pipefail
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*/migrations/*)
echo "Files under migrations/ are written by hand. Stop and ask first." >&2
exit 2
;;
esac
exit 0執行 chmod +x .claude/hooks/guard-migrations.sh,接著啟動新的工作階段,並要求代理程式編輯 migrations/ 下的檔案。編輯會遭拒絕,訊息會以原因形式傳回。PreToolUse 的結束狀態 2 會在工具呼叫執行前將其阻擋,而 stderr 文字會以阻擋訊息的形式傳給模型。${CLAUDE_PROJECT_DIR} 會解析為專案根目錄,因此無論代理程式目前位於哪個目錄,hook 都能正常運作。代理程式不必同意規則、記住規則,或在目前的內容中仍保留規則。編輯不會發生。
若只是沒有任何邏輯的單純禁止規則,在設定中使用 permissions.deny 即可達到相同效果,且不必維護 script;權限模式會決定哪些操作可在不先詢問你的情況下執行。如果某項指示確實必須放在 system prompt 層級,而不是 user message 中,--append-system-prompt 可將其放在該層級。不過這是每個新工作階段都必須再次傳入的啟動旗標,因此較適合 script,而非互動式工作。
你無法僅靠指示消除的問題
請明確區分哪些部分由你負責。放置位置、措辭、檔案之間的衝突,以及檔案大小,都是作者的問題,也應由作者修正。其餘則屬於模型行為,無法僅靠更好的措辭消除。
同意不等於遵從。 代理程式可能會確認規則、正確重述規則,卻在兩次工具呼叫後違反規則。這種確認不會產生任何成本,也無法預測後續行為。不要把它視為修正,也不要把它算作測試。
有些習慣會持續出現。 例如加入註解、加入防禦性錯誤處理、撰寫結尾摘要,以及執行下一個直覺上應執行的命令。即使規則禁止這些行為,它們仍會以較低而非零的頻率再次出現。你可以測量自己的發生率:在全新的工作階段中執行相同工作 10 次,並計算違規次數。若該數字必須為零,就必須把規則移出提示內容。工作尚未完成一部分卻宣告完成,屬於相同類型的習慣;修正方式不是改寫措辭,而是採用結構化方法:unlazy skill 會以 Depth Tree 取代該句,並要求代理程式先通過 gate 檔案,才能宣告完成。
你目前的工作階段本身會成為範例。 如果代理程式在第 12 輪違反規則,而你放任不管,該違規行為就會以示範形式留在內容中,而且比規則新得多。發現違規時,應立即修正。未修正的違規行為會教導整個工作階段後續的行為。
指示檔案不是安全邊界。 它只能塑造行為,無法強制執行。凡是遺漏會造成重大損失的事項,例如憑證或破壞性命令,都應交由權限或 hook 控制。讓代理程式無法接觸秘密對資料採用相同原則:不要要求代理程式不要讀取某個檔案,而是讓該檔案實際上無法讀取。
簡而言之,先證明檔案已載入,再讓規則具備可檢查性,將規則移到受其規範的對象旁邊;如果遺漏率仍然重要,就不要只依賴文字描述。代理程式無法忽略的規則,從未真正要求代理程式遵守。
FAQ
為什麼 Claude Code 忽略我的 CLAUDE.md?
請先確認它是否已載入,不要直接假設它遭到忽略。執行 /context,查看 Memory files 清單;清單中沒有列出的檔案,表示啟動時未載入。指示檔會在 system prompt 之後,以 user message 的形式提供,並被視為上下文,而不是強制執行的設定,因此無法保證嚴格遵循。實際上多半是以下 4 種情況之一:檔案位於 agent 從未讀取的子目錄中、2 個檔案的內容互相衝突而模型任意選擇其中一個、規則過於模糊而無法據此判斷操作,或周圍的程式碼示範了與規則相反的做法。
在工作階段中途編輯指示檔,會產生什麼影響?
對已存在於對話中的副本沒有影響。工作目錄上層的檔案會在啟動時完整載入,因此模型持有的內容是啟動當時的版本。若要載入編輯後的內容,請開始新的工作階段,或要求 agent 使用一般檔案工具讀取該檔案,將目前版本以新的訊息加入對話。完成壓縮後,系統會從磁碟重新讀取專案根目錄檔案,因此新版本也會在該時間點載入。
根目錄的 CLAUDE.md 與巢狀檔案內容衝突時,哪個檔案優先?
兩者都沒有可靠的優先順序。已探索到的檔案會串接至上下文中,而不是彼此覆寫;檔案會依檔案系統根目錄到工作目錄的順序排列,因此距離工作目錄最近的檔案只會最後被讀取。系統沒有解決矛盾的優先順序機制,Claude Code 的文件也指出,互相衝突的規則可能會被任意處理。請將巢狀檔案撰寫為補充規則,並明確指定其適用路徑;不要試圖以更高優先順序壓過衝突內容,應直接刪除衝突。
我的指示能在 /compact 後保留嗎?
這取決於指示的載入方式。專案根目錄的 CLAUDE.md、未指定範圍的規則及自動記憶,會在壓縮後從磁碟重新注入。具有 paths: frontmatter 的規則,以及子目錄中的巢狀 CLAUDE.md 檔案,會遺失,直到再次讀取相符的檔案為止。只有在摘要器恰好保留的情況下,單純輸入聊天內容中的指示才會保留。若規則必須在整個工作階段中持續有效,請將它放在專案根目錄檔案中,且不要使用 paths: frontmatter。
何時應將規則改用 hook,而不是文字說明?
當檢查可確定執行,且漏檢的代價高於撰寫小型 script 的代價時,就應改用 hook。檔案路徑限制、commit 前必須執行的命令,以及禁止的工具呼叫,都符合這個條件。PreToolUse hook 若以 status 2 結束,會直接阻擋工具呼叫,並將 stderr 文字傳回模型作為原因;因此無論規則是否仍存在於上下文中,都能持續生效。凡是 formatter 或 linter 能夠判斷的內容,都應交由該工具負責,並從指示檔中完全刪除。