karpathy 在 X 上抱怨了 claude。forrest chang 把這則抱怨變成了四條規則和一個 GitHub 倉庫。這個倉庫在幾週內獲得了 12 萬顆星。大多數閱讀本文的開發者仍然只使用這四條規則。問題在於它們是在一月寫的。現在已經是 2026 年中，claude code 生態系統已經改變。
本文將為你提供完整的 12 條規則 CLAUDE.md，解釋每條規則存在的原因、它堵住了什麼漏洞，以及原始模板在哪些地方默默地出了錯。請將它貼在文末。
什麼是 CLAUDE.md，以及為什麼大多數人對它的理解是錯的
CLAUDE.md 是一個你放在倉庫根目錄的檔案。claude code 在每次對話開始前都會讀取它。它不是一個提示詞。它不是一個偏好清單。它是 claude 在你的程式碼庫中如何運作的一套作業系統。
大多數開發者會做以下三件錯事之一：他們把所有曾經有過的偏好都塞進這個檔案，直到它膨脹超過 4,000 個 token，此時遵循率會下降到 30%，因為重要的規則被埋沒了；他們完全跳過它，每次對話都重新提示，這浪費了五倍的 token 且產出零一致性；他們貼上一個模板一次，然後就忘了它，眼睜睜看著它在幾週內隨著程式碼庫的變更而默默地失效。
Anthropic 的官方文件說得很清楚：CLAUDE.md 是建議性的。claude 在 200 行以下時大約有 80% 的時間會遵循它。超過 200 行，遵循率會急劇下降。有用的 CLAUDE.md 檔案的上限是簡短、精確，並透過直接規則而非建議來強制執行。
原始的四條規則：如果你一無所有，從這裡開始
Andrej Karpathy，前 Tesla AI 總監和 OpenAI 共同創辦人，在 2026 年一月經過數週密集使用 claude code 後發佈了一則貼文。不是一個框架。是一則抱怨。他反覆遇到的三種失敗模式：claude 默默地假設而不是提問，claude 過度建構而不是解決最小問題，以及 claude 修改了它從未被要求觸及的程式碼。
Forrest Chang 讀了這則貼文並將其寫成了規則。一個檔案，65 行，第二天就放上了 GitHub。以下是這四條規則：
規則 1 - 先思考再寫程式
在寫程式碼之前陳述你的假設。揭示權衡取捨。在猜測之前先提問。當存在更簡單的方法時要提出異議。永遠不要在未經驗證的假設上進行建構。
規則 2 - 簡潔至上
撰寫解決問題所需的最小程式碼。沒有推測性的功能。沒有為只用一次的程式碼建立抽象。如果一位資深工程師會說它過於複雜，那就簡化它。
規則 3 - 外科手術式變更
只觸及任務所需的內容。不要改進相鄰的程式碼、註解或格式。不要重構沒有問題的部分。完全匹配現有風格。
規則 4 - 目標驅動執行
在開始之前定義成功的樣子。持續迭代直到成功被驗證。不要為 claude 列出步驟。告訴 claude 完成的樣子是什麼，讓它自己找出路徑。
這四條規則大約能堵住 40% 的無監督 claude code 對話中的失敗模式。剩下的 60% 存在於原始模板沒有處理的空白地帶，因為當 karpathy 發佈他的貼文時，這些問題還沒有完全出現。
為什麼需要擴展原始模板
這四條 karpathy 規則是為了解決單一 Agent、撰寫程式碼的對話而建立的。2026 年的 claude code 生態系統運行著多 Agent 設定、鉤子、技能庫和跨越多個對話的多步驟工作流程。原始模板對這些完全沒有提及。
原始規則中出現了四個特定的空白地帶。第一，Agent 衝突：兩個 Agent 編輯同一個檔案，沒有所有權規則，默默地互相覆蓋對方的變更。第二，鉤子串聯：鉤子在每次工具呼叫時觸發，將一個 200 token 的請求變成 8,000 token，且沒有預算來阻止它。第三，技能載入衝突：多個具有相似描述的技能會混淆調度器，並載入錯誤的技能。第四，多步驟對話中斷：一個 6 步驟的重構在第 4 步失敗，但第 5 和第 6 步仍然執行，並建立在錯誤的狀態之上。
這四條原始規則沒有錯。它們是不完整的。以下 8 條附加規則專門堵住了這些空白地帶。
8 條新規則：每一條堵住了什麼
規則 5 - 不要將模型用於非語言工作
確定性決策屬於確定性程式碼。重試邏輯、路由閾值、升級規則、基於狀態的分支：這些都不應該是 LLM 呼叫。模型每週都會根據上下文視窗中的內容做出不同的決定。看起來像是一致行為的東西，實際上只是尚未浮現的變異。
具體事件：一個「決定是否在 503 錯誤時重試」的 LLM 呼叫正常工作了兩週，然後開始產生隨機行為，因為模型開始將請求主體解讀為重試決策的上下文。政策變得隨機，因為有效輸入是隨機的。
在你的 CLAUDE.md 中加入這個：
路由、重試邏輯、基於狀態的分支和閾值決策屬於程式碼，而不是模型呼叫。如果一個決策的輸出是二元的或遵循固定規則，請用程式碼撰寫該規則。
規則 6 - 硬性 Token 預算，沒有例外
每個 Agent 迴圈都有機會失控。claude 不會自行停止一個 90 分鐘的除錯對話。它會持續迭代，因為迭代就是它被指示要做的事。Token 預算是唯一能強制執行硬性停止的機制。
具體事件：一個除錯對話在同一個 8KB 的錯誤訊息上循環了 90 分鐘。到最後，claude 正在建議它兩小時前已經嘗試過並放棄的修復方案。上下文太滿，以至於它已經失去了自己推理過程的蹤跡。
加入這個：
每個 Agent 對話都有一個硬性 token 預算。如果在沒有驗證解決方案的情況下達到預算，請停止，將發現總結到一個檔案中，然後退出。不要繼續超過預算。
規則 7 - 一個 Agent，一個目錄
當兩個 Agent 同時觸及同一個目錄時，你會得到無聲的狀態損壞。一個 Agent 在寫入檔案時，另一個 Agent 正在讀取它。結果是兩個 Agent 都沒有預期到且都沒有注意到的資料。
使用 git worktrees。在產生第二個 Agent 之前，執行 git worktree add ../agent-2-branch feature-branch。每個 Agent 獲得自己獨立的、指向自己分支的工作目錄。Agent 之間永遠不共享檔案系統。
加入這個：
並行運行的 Agent 在獨立的 git worktree 中工作。沒有兩個 Agent 同時觸及同一個目錄。每個 Agent 擁有自己的分支。
規則 8 - 在多步驟工作中寫入檢查點檔案
任何超過三步的任務都需要一個檢查點檔案。claude 在每一步之後寫入該檔案，記錄完成了什麼、發現了什麼以及下一步要做什麼。如果對話在第 4 步中斷或失敗，下一個對話會讀取檢查點並從第 4 步繼續。沒有檢查點，每次重新啟動都會回到第 1 步。
在開始任何多步驟任務之前，在你的工作目錄中建立一個名為 PROGRESS.md 的檔案。在你的 CLAUDE.md 中告訴 claude：
對於超過三步的任務，在每一步之後寫入一個 PROGRESS.md 檔案。包括：完成了什麼、發現了什麼、下一步要做什麼、以及什麼被阻塞了。如果一個對話在完成之前結束，下一個對話會先讀取 PROGRESS.md，然後從停止的地方繼續。
規則 9 - 要嘛大聲失敗，要嘛根本不要失敗
claude 有很強的傾向表現得好像成功了。它會通過一個實際上並未測試你關心之事的測試。它會在默默地跳過出錯的檔案時完成遷移。它會在一個只完成了 80% 的任務上報告「完成」。
規則：如果成功標準無法被驗證，任務就沒有完成。如果一個步驟失敗了，在繼續之前停止並報告失敗的具體細節。不要掩蓋錯誤。
加入這個：
永遠不要在一個失敗的步驟之後繼續。如果一個測試通過了但沒有涵蓋實際行為，請說出來。如果一個遷移跳過了檔案，列出被跳過的檔案並停止。成功意味著可驗證，而非被報告。
規則 10 - 技能描述必須是唯一的
技能是透過描述匹配來載入的。如果兩個技能有重疊的描述，調度器會任意選擇一個。錯誤的技能被載入，任務在錯誤的指令下運行，而你永遠看不到錯誤，因為沒有錯誤被拋出。
用不可能與任何其他技能匹配的語言來命名每個技能的工作。「資料庫查詢助手」和「資料庫遷移助手」會衝突。「對生產資料庫執行唯讀 SQL 查詢」和「運行並驗證帶有回滾功能的 schema 遷移腳本」則不會。
加入這個：
每個技能描述必須唯一地標識其工作。不應該有兩個技能的描述可以適用於同一個任務。如果兩個技能聽起來相似，其中一個在部署之前需要重新命名。
規則 11 - 將研究者和寫作者分開
上下文污染是真實存在的。當 claude 在同一個對話中進行研究和寫作時，研究雜訊會降低寫作品質。它會引入離題內容，對不需要保留的結論進行保留，並失去它從一個乾淨狀態開始時本該有的清晰論述線。
對於任何需要讀取超過五個檔案或查詢超過兩個來源的任務，產生一個研究子 Agent。取回一份結構化的報告。為寫作或實作啟動一個新的乾淨對話，上下文中只包含那份報告。
加入這個：
研究和實作是分開的對話。一個研究者子 Agent 讀取檔案、運行查詢，並返回一份結構化的摘要。實作對話以該摘要作為唯一輸入從頭開始。永遠不要將研究和寫作合併到一個對話中。
規則 12 - 鉤子也需要預算
鉤子在每次工具呼叫時觸發。一個在每次檔案寫入時運行 linter、格式化工具、日誌寫入器和安全掃描的鉤子，每次工具呼叫要運行四個程序。在一個有 200 次工具呼叫的對話中，這意味著有 800 個程序在背景運行，其中大部分是多餘的，而且全部都在消耗 token。
你添加的每個鉤子都需要一個範圍條件：僅在對特定目錄的檔案寫入時運行，僅在觸及特定副檔名時運行，僅在對話結束後而非每次工具呼叫後運行。沒有範圍條件的鉤子會無形中降低對話效能。
加入這個：
每個鉤子都有一個明確的範圍條件。沒有鉤子在每次工具呼叫時無條件運行。將日誌批次處理到對話結束。僅對已變更的檔案運行 linter。僅對測試目錄之外的檔案運行安全檢查。
完整的 12 條規則 CLAUDE.md - 貼上這個
將這個檔案複製到你的倉庫根目錄。填寫標記為括號的章節。整個檔案保持在 100 行以下，這能使遵循率維持在 80% 以上。
CLAUDE.md
專案
[一句話：這個程式碼庫是做什麼的，以及它使用了什麼技術棧]
行為規則
先思考再寫程式
在寫程式碼之前陳述你的假設。揭示權衡取捨。在猜測任何會影響架構或資料的事情之前先提問。當存在更簡單的方法時要提出異議。
簡潔至上
撰寫解決問題所需的最小程式碼。沒有推測性的功能。沒有為只用一次的程式碼建立抽象。如果一位資深工程師會說它過於複雜，那就簡化它。
外科手術式變更
只觸及任務所需的內容。不要改進未被要求的相鄰程式碼、格式、註解或命名。完全匹配現有程式碼風格。
目標驅動執行
在開始之前定義成功的樣子。持續迭代直到該定義被滿足並驗證。不要要求逐步指示。自己找出路徑。
確定性決策不使用模型呼叫
路由、重試邏輯、基於狀態的分支和閾值決策屬於程式碼，而不是 LLM 呼叫。如果一個規則可以被寫出來，就把它寫出來。
硬性 Token 預算
每個對話都有一個硬性 token 限制：[設定你的數字，例如 50,000 tokens]。如果在沒有驗證解決方案的情況下達到限制，將發現寫入一個檔案並停止。不要繼續超過預算。
一個 Agent，一個目錄
並行運行的 Agent 在獨立的 git worktree 中工作。沒有兩個 Agent 共享一個目錄。如果你需要第二個 Agent，執行：git worktree add ../agent-2 [分支名稱]
為多步驟工作設置檢查點
對於任何超過三步的任務，在工作目錄中建立 PROGRESS.md。在每一步之後寫入：完成了什麼、發現了什麼、下一步要做什麼、什麼被阻塞了。如果對話在完成之前結束，下一個對話會先讀取 PROGRESS.md。
大聲失敗
如果一個步驟失敗了，在繼續之前停止並報告失敗的具體細節。如果一個測試通過了但沒有涵蓋實際行為，請說出來。成功意味著可驗證，而非被報告。
唯一的技能描述
每個技能涵蓋恰好一個工作。其描述不能適用於專案中的任何其他技能。如果兩個技能在描述上重疊，在部署之前重新命名。
研究和實作是分開的對話
對於任何需要讀取超過五個檔案或查詢超過兩個來源的任務，使用一個子 Agent。取回一份結構化的報告。為實作啟動一個新的乾淨對話，只以那份報告作為輸入。
僅限有範圍的鉤子
每個鉤子都有一個明確的條件：檔案副檔名、目錄路徑或對話事件。沒有鉤子在每次工具呼叫時無條件運行。盡可能將日誌批次處理到對話結束。
不要觸及的內容
[列出 claude 永遠不應修改的目錄或檔案：例如 /secrets, /migrations/archive, /prod-config]
成功標準預設值
當不確定任務是否完成時：測試是否通過，建置是否成功，以及輸出是否可由 claude 自身判斷以外的東西驗證？如果以上任何一項的答案是否定的，則任務尚未完成。
原始模板默默失效的四個地方
即使只使用原始的四條規則，也有四個特定條件會導致模板產生錯誤行為而不自知。
第一：累積了大量上下文的長時間對話。karpathy 的目標驅動執行規則告訴 claude 要持續迭代直到被驗證。在一個長時間對話中，隨著上下文被填滿，「被驗證」變得模糊不清。claude 開始根據一個退化的、關於它應該做什麼的模型來進行驗證。解決方案是規則 6（token 預算）強制執行硬性停止。
第二：多 Agent 設定。外科手術式變更規則告訴每個 Agent 只觸及它必須觸及的內容。但是，在沒有目錄所有權規則的情況下，兩個 Agent 的「必須觸及」會重疊。規則 7（一個 Agent，一個目錄）是缺失的部分。
第三：具有相似工作的並行技能。原始模板完全沒有關於技能的內容。規則 10（唯一的技能描述）堵住了調度器歧義的空白地帶。
第四：在中途結束的對話。目標驅動執行假設對話會運行到完成。它沒有關於如果對話在 8 步中的第 4 步中斷該怎麼做的指示。規則 8（檢查點檔案）為下一個對話提供了一個起點。
這些都不是原始規則中的錯誤。它們是原始規則未被設計來涵蓋的空白地帶。
解釋 GitHub 星數的數字
12 萬名開發者為一個 65 行的文字檔案點讚。沒有程式碼。沒有函式庫。沒有框架。一個包含四條規則的檔案。
解釋這個現象的數字是：在沒有 CLAUDE.md 的無監督 claude code 對話中，錯誤率為 41%。使用原始的四條規則時為 11%。使用完整的十二條規則時為 3%。
錯誤率降低 38 個百分點不是一個邊際改善。對於任何在真實生產工作上運行 claude code 的團隊來說，這是區分一個你可以信任它整夜運行的 Agent 和一個你需要時刻照看的 Agent 的關鍵。
本文末尾的檔案只需五分鐘就能貼上並填寫完成。你這樣做之後的第一次對話會感覺不同。不是因為模型變了。而是因為模型終於知道你的世界是如何運作的了。
將此頁加入書籤，並在今晚將這 12 條規則貼到你的 CLAUDE.md 中。
如果你覺得這有幫助，請轉發。
