編者按：2026 年 1 月，Andrej Karpathy 對 Claude 寫代碼的吐槽，引出了一個看似很小、但在 AI 編程工作流中極其關鍵的文件：CLAUDE.md。Forrest Chang 隨後將這些問題整理成 4 條行為規則，試圖約束 Claude 在編碼時常見的錯誤：靜默假設、過度工程化、誤傷無關代碼，以及缺乏清晰的成功標準。

但幾個月後，Claude Code 的使用情境已不再僅限於「讓模型撰寫一段程式碼」。隨著多步驟 Agent、hook 鏈式觸發、skill 載入和多程式碼庫協作成為常態，新的失敗模式也開始出現：模型在長任務中失控、測試通過卻未驗證真實邏輯、遷移完成但靜默跳過錯誤、不同程式碼風格被錯誤混合。

本文作者在 6 週內測試了 30 個代碼庫，並在 Karpathy 原有 4 條規則基礎上新增 8 條規則，試圖覆蓋 AI 編程從單次補全走向 Agent 化協作後的新問題。

以下為原文：

2026 年 1 月下旬，Andrej Karpathy 發了一串推文，抱怨 Claude 寫代碼的方式。他指出了三類典型問題：在未說明的情況下做出錯誤假設、過度複雜化，以及對原本不應更改的代碼造成無關破壞。

Forrest Chang 看到了這條推文串，將其中的抱怨整理成 4 條行為規則，寫入一個單獨的 CLAUDE.md 檔案，並上傳至 GitHub。這個項目上線第一天便獲得 5,828 個 Star，兩週內被收藏 60,000 次，如今已擁有 120,000 個 Star，成為 2026 年增長最快的單檔案程式碼倉庫。

隨後，我在 6 週時間裡，用 30 個代碼庫對它進行了測試。

這 4 條規則確實有效。過去大約 40% 機率會出現的錯誤，在適合這些規則發揮作用的任務中，下降到了 3% 以下。但問題在於，這個模板最初是為了解決 1 月份 Claude 寫代碼時出現的錯誤。

到 2026 年 5 月，Claude Code 生態面臨的問題已有所不同：Agent 之間相互衝突、hook 鏈式觸發、skill 加載衝突，以及跨會話多步驟工作流中斷等。

因此，我又加入了 8 條規則。以下是完整的 12 條規則版 CLAUDE.md：每一條為何值得加入，以及原版 Karpathy 模板會在哪 4 個地方悄悄失效。

如果你想跳過解釋，直接複製使用，完整文件放在文末。

為什麼這很重要

Claude Code 的 CLAUDE.md，是整個 AI 編程技術棧裡最被低估的檔案。大多數開發者通常會犯三類錯誤：

首先，把它當成偏好垃圾桶，把自己所有習慣都塞進去，最後膨脹到 4000 多個 token，規則遵守率掉到 30%。

第二，乾脆完全不用，每次都重新 prompt。這會造成 5 倍 token 浪費，而且不同會話之間缺乏一致性。

第三，複製一個模板後就再也不管。它可能有效兩週，但隨著程式碼庫變化，會在你不知不覺中失效。

Anthropic 的官方文件明確指出：CLAUDE.md 本質上僅具建議性。Claude 大約會在 80% 的時間遵循它。一旦超過 200 行，遵守率就會明顯下降，因為重要規則會被噪音淹沒。

Karpathy 的模板解決了這個問題：一個文件、65 行、4 條規則。這是最低基準。

但上限還可以更高。在加入以下這 8 條規則後，它涵蓋的就不只是 Karpathy 在 2026 年 1 月抱怨的代碼撰寫問題，也包括 2026 年 5 月才出現的 Agent 排程問題——這些問題在原模板撰寫時還不存在。

原始的 4 條規則

如果你還沒有看過 Forrest Chang 的倉庫，請先看這個基礎版本：

規則 1：編碼前先思考。

不要默默做假設。要說明你的假設，暴露權衡點。在猜測之前先提問。當存在更簡單的方案時，要主動提出反對意見。

規則 2：優先簡化。
用最少的程式碼解決問題。不要加入想像中的功能。不要為一次性程式碼設計抽象層。如果資深工程師認為它過於複雜，就應該簡化。

規則 3：外科手術式修改。
僅修改必須修改的部分。不要順手「優化」相鄰代碼、註釋或格式。不要重構沒有壞掉的東西。保持與現有風格一致。

規則 4：以目標為導向執行。
先定義成功標準，然後循環迭代，直到完成驗證。不要告訴 Claude 每一步該怎麼做，而是告訴它成功結果應該是什麼樣，讓它自己迭代。

這 4 條規則，能解決我在無人監督的 Claude Code 會話中看到的大約 40% 的失敗模式。剩下約 60% 的問題，則藏在下面這些空白地帶。

我新增的 8 條規則，以及為什麼

每一條規則，都來自一個真實時刻：Karpathy 原來的 4 條規則已經不夠用了。下面我會先講那個場景，再給出對應規則。

Karpathy 的規則未涵蓋這一點，因此模型開始自行決定本應由確定性代碼處理的問題：是否重試一次 API 調用、如何路由一條訊息、何時升級處理。結果是，每週的判斷都不一致。你得到的是一種按每個 token 收費 0.003 美元的、不穩定的 if-else。

那個時刻是這樣的：有一段代碼會調用 Claude 來「判斷遇到 503 時是否應該重試」。它一開始運行得很好，持續了兩週，後來突然變得不穩定，因為模型開始將請求體也當作判斷上下文。重試策略變得隨機，因為 prompt 本身也是隨機的。

沒有預算限制的 CLAUDE.md，就等於一張空白支票。每一次迴圈都有可能失控，變成一次 50,000 token 的上下文傾倒。模型不會自己停下來。

那個時刻是這樣的：一次調試會話持續了 90 分鐘。模型一直在反覆迭代同一段 8KB 的錯誤訊息，並逐漸忘記自己已經嘗試過哪些修復方案。到最後，它開始提出我早在 40 條訊息前就已否定的方案。如果有 token 預算，這個過程在第 12 分鐘就該被終止。

當程式碼庫中的兩個部分互相矛盾時，Claude 會試圖同時討好雙方，結果寫出的是一團不連貫的程式碼。

當時的情況是：代碼庫中存在兩種錯誤處理模式，一種是 async/await 加顯式 try/catch，另一種是全局錯誤邊界。Claude 寫出的新代碼同時使用了這兩種模式，導致錯誤處理被執行了兩次。我花了 30 分鐘才弄清楚為何錯誤被吞掉了兩次。

Karpathy 的「外科手術式修改」告訴 Claude 不要改動相鄰代碼，但它沒有告訴 Claude：先理解相鄰代碼。沒有這一條，Claude 會寫出與 30 行之外既有代碼相衝突的新代碼。

當時的情況是：Claude 在一個已有函數旁邊新增了一個功能完全相同的函數，因為它沒有先讀取原來的函數。兩個函數做的是同一件事。但由於 import 順序的關係，新函數覆蓋了舊函數，而舊函數已作為事實上的唯一標準存在了 6 個月。

Karpathy 的「以目標為導向執行」暗示測試可以作為成功標準。但在實踐中，Claude 會把「測試通過」當成唯一目標，於是寫出一些能通過淺層測試、卻會破壞其他東西的代碼。

當時的情況是：Claude 為一個認證函數撰寫了 12 個測試，全部通過。但生產環境中的認證邏輯出現了故障。這些測試僅驗證了函數「返回了某個東西」，而非驗證它是否返回了正確的內容。該函數之所以能通過測試，是因為它返回了一個常量。

Karpathy 的模板預設互動為一次性。但真實的 Claude Code 工作通常是多步驟的：跨 20 個文件重構、在一個會話中構建功能、跨多個 commit 調試。如果沒有檢查點，一步走錯，前面所有進度都可能丟失。

那個時刻是這樣的：一個 6 步重構任務在第 4 步出錯了。等我發現時，Claude 已經在錯誤狀態之上繼續完成了第 5 步和第 6 步。拆解修復花的時間，比重做整個任務還長。如果有檢查點，第 4 步就能發現問題。

在一個已經有成熟模式的代碼庫中，Claude 喜歡引入自己的寫法。即使它的寫法「更好」，引入第二套模式本身，也比任何一種單一模式都更糟。

當時的情況是：Claude 在一個基於 class component 的 React 程式碼庫中引入了 hooks。它確實能運行，但同時破壞了程式碼庫原有的測試模式，因為這些測試依賴 componentDidMount。最後花了半天時間才將其刪除並重寫。

Claude 最昂貴的失敗，往往是那些看起來像成功的失敗。一個函數「能跑」，但返回了錯誤資料；一次 migration「完成了」，但跳過了 30 條記錄；一個測試「通過了」，但只是因為斷言本身是錯的。

當時的情況是：Claude 說一次資料庫遷移「成功完成」。但實際上，它靜默跳過了 14% 觸發觸發約束衝突的記錄。跳過行為被寫入日誌，卻未被明確暴露。11 天後，當報表數據開始異常時，我們才發現問題。

我在 6 周時間裡，追蹤了同一組 50 個代表性任務，覆蓋 30 個代碼庫，測試了三種配置。

錯誤率是指：任務需要被糾正或重寫，才能符合原始意圖。計入的錯誤包括：靜默錯誤假設、過度工程化、無關破壞、靜默失敗、違反約定、衝突妥協、漏掉檢查點。

遵守率是指：當某項規則適用時，Claude 有多大概率會顯性應用該規則。

真正有趣的結果，不僅是錯誤率從 41% 降至 3%。更重要的是，當規則從 4 條擴展至 12 條時，合規負擔幾乎沒有增加，合規率僅從 78% 微幅下降至 76%，但錯誤率又再下降了 8 個百分點。新增的規則涵蓋了原來 4 條規則未處理的失敗模式，它們並未爭奪相同的注意力預算。

Karpathy 模板會在哪些地方悄悄失效

即使不加入新規則，原來的 4 條規則模板也至少在 4 個地方不夠用。

第一，長時間運行的 Agent 任務。
Karpathy 的規則主要針對 Claude 正在寫代碼的那一刻。但當 Claude 執行一個多步驟 pipeline 時，會發生什麼？原始模板沒有預算規則，沒有檢查點規則，也沒有「大聲失敗」規則。於是 pipeline 會慢慢偏移。

第二，多程式碼庫一致性。
「匹配現有風格」預設只有一種風格。但在一個擁有 12 個服務的 monorepo 裡，Claude 必須選擇到底匹配哪一種風格。原始規則沒有告訴它怎麼選。於是它要么隨機選擇，要么把幾種風格平均混合。

Third, test quality.
「以目標為導向執行」會將「測試通過」視為成功，卻未說明測試本身必須有意義。結果就是，Claude 寫出一些幾乎什麼都沒驗證的測試，但這些測試會讓它誤以為自己很有把握。

Fourth, the difference between production environment and prototype stage.
同樣的 4 條規則可以防止生產代碼被過度工程化，但也可能拖慢原型開發。因為原型階段有時確實需要 100 行探索性腳手架，先摸清方向。Karpathy 的「簡單優先」在早期代碼裡容易過度觸發。

這 8 條新增規則並非要取代 Karpathy 的原始 4 條規則，而是在彌補它們的空白：原模板對應的是 2026 年 1 月那種偏自動補全式的程式碼撰寫情境；而到了 2026 年 5 月，Claude Code 已進入由 Agent 驅動的、多步驟、多程式碼庫協作環境，兩者面對的問題並不相同。

哪些方法沒有奏效

在最終確定這 12 條規則之前，我也嘗試過一些其他方案。

加入我在 Reddit / X 上看到的規則。
其中大多數，要麼只是用不同說法重複 Karpathy 原來的 4 條規則，要麼是無法泛化的領域特定規則，例如「始終使用 Tailwind class」。最後都刪除了。

超過 12 條規則。
我最多測試了 18 條。超過 14 條後，遵守率從 76% 下降到 52%。200 行的上限是真實存在的。超過這個長度後，Claude 會開始進行模式匹配，認為「這裡有規則」，而不是真正逐條閱讀規則。

依賴某些工具存在的規則。
例如「始終使用 eslint」，一旦項目中未安裝 eslint，這條規則就會失效，而且是靜默失效。後來我將其改為不依賴具體工具的表達，例如將「使用 eslint」改為「遵循代碼庫中已強制執行的風格」。

在 CLAUDE.md 裡放示例，而不是規則。
Examples take up more context than rules. Three examples consume about as much context as ten rules, and Claude is prone to overfitting on examples. Rules are abstract; examples are concrete. Therefore, rules should be used.

「小心一點」「認真思考」「專注一點」。
這些都是噪音。這類指令的遵守率下降至約 30%，因為它們無法被檢驗。後來我將它們替換為更具體的命令式規則，例如「明確說明假設」。

告訴 Claude 要像「資深工程師」一樣。
這沒有用。Claude 本來就覺得自己像資深工程師。真正的问题不在於它是否這樣認為，而在於它是否這樣執行。命令式規則可以縮小這個差距，身份提示詞不行。

完整的 12 條規則版 CLAUDE.md

以下是可直接複製貼上使用的完整版本。

此內容暫時無法在飛書文檔外顯示

將它儲存為倉庫根目錄下的 CLAUDE.md。在這 12 條規則下面，再添加項目專屬規則，比如技術棧、測試命令、錯誤模式等。整體不要超過 200 行，超過之後，規則遵守率就會明顯下降。

如何安裝

只需兩步：

1. 將 Karpathy 的 4 條基礎規則追加到你的 CLAUDE.md 中
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. 將本文中的規則 5–12 粘貼到下面

將檔案儲存於倉庫根目錄。這裡的 >> 很重要，它的作用是追加到已有的 CLAUDE.md，而不是覆蓋你已經寫好的項目專屬規則。

CLAUDE.md 不是願望清單，而是一份行為契約，用來封堵你已經觀察到的具體失敗模式。

每一條規則都應該回答一個問題：它能防止什麼錯誤？

Karpathy 的 4 條規則，旨在防範他在 2026 年 1 月看到的失敗模式：靜默假設、過度工程化、無關破壞、成功標準薄弱。它們是基礎，不要跳過。

我新增的 8 條規則，防的是 2026 年 5 月之後出現的新失敗模式：沒有預算約束的 Agent 循環、沒有檢查點的多步驟任務、看似測試了但其實沒測到關鍵邏輯的測試，以及把靜默失敗包裝成靜默成功的问题。它們是增量補丁。

當然，具體效果因人而異。如果你不運行多步驟 pipeline，規則 10 對你就沒那麼重要。如果你的程式碼庫只有一種統一風格，且已由 lint 強制執行，規則 11 就是冗餘的。讀完這 12 條後，保留那些真正對應你實際犯過錯誤的規則，刪掉其餘部分。

一份針對真實失敗模式定制的 6 條規則版 CLAUDE.md，勝過一份有 12 條規則、其中 6 條你永遠用不上的版本。

結語

Karpathy 於 2026 年 1 月的那條推文，本質上是一場抱怨。Forrest Chang 將其轉化為 4 條規則。最終，12 萬名開發者為這個結果點了 Star。而其中大多數人，今天仍僅在使用這 4 條規則。

模型已經進步，生態也已經改變。多步驟 Agent、hook 鏈式觸發、skill 加載、多代碼庫協作——這些在 Karpathy 寫下那條推文時都還不存在。原來的 4 條規則並沒有解決這些問題。它們不是錯了，而是不完整了。

新增 8 條規則。6 週時間，覆蓋 30 個代碼庫的測試。錯誤率從 41% 降到 3%。

今晚就收藏這篇文章，把這 12 條規則貼進你的 CLAUDE.md。如果它幫你少走一周 Claude 彎路，歡迎轉發。