CLAUDE.md 12條AI編碼避坑指南
{"id":90965,"title":"CLAUDE.md\u9019\u6a23\u5beb\u624d\u5c0d\uff0112\u689d\u898f\u5247\u4e00\u6b21\u6574\u7406\uff0c\u8b93Claude Code\u932f\u8aa4\u7387\u5f9e41%\u964d\u81f33%","image":"https:\/\/image-cdn.learnin.tw\/bnextmedia\/image\/album\/2026-05\/82fs-1779088632.png?w=1600\u0026output=webp","summary":"\u958b\u767c\u8005\u5c07Claude\u6307\u4ee4\u64f4\u5145\u81f312\u689d\uff0c\u7cbe\u6e96\u89e3\u6c7a\u8907\u96dcAI\u4ee3\u7406\u76f2\u9ede\u5be6\u6e2c\u986f\u793a\uff0c\u65b0\u898f\u4f7f\u7a0b\u5f0f\u932f\u8aa4\u7387\u753141%\u9a5f\u964d\u81f33%\uff0c\u5927\u5e45\u63d0\u5347\u958b\u767c\u6548\u80fd\u3002","is_ads":"0","page_title":"CLAUDE.md\u9019\u6a23\u5beb\u624d\u5c0d\uff0112\u689d\u898f\u5247\u4e00\u6b21\u6574\u7406\uff0c\u8b93Claude Code\u932f\u8aa4\u7387\u5f9e41%\u964d\u81f33%","url":"https:\/\/www.bnext.com.tw\/article\/90965\/claude.md-claude-code","category":"AI\u8207\u5927\u6578\u64da","tag":"Claude","published_gmt":"2026-05-18T15:02:00+08:00","published_at":"2026-05-18 15:02:00","editor_name":"","canonical_url":"","page_serial":"1"}
2026.05.18
|
AI與大數據
CLAUDE.md這樣寫才對！12條規則一次整理，讓Claude Code錯誤率從41%降至3%
開發者將Claude指令擴充至12條，精準解決複雜AI代理盲點實測顯示，新規使程式錯誤率由41%驟降至3%，大幅提升開發效能。
＃Claude
蘇柔瑋
CLAUDE.md這樣寫才對！12條規則一次整理，讓Claude Code錯誤率從41%降至3%
2026.05.18
|
AI與大數據
蘇柔瑋
分享
收藏
分享
收藏
重點一：基於前期基礎，開發者將CLAUDE.md規則擴充至12條，使Claude程式碼錯誤率從11%降至3%。
重點二：新增的8條規則主要解決複雜AI代理問題，涵蓋嚴格控管詞元預算、多步驟任務檢查點，以及強制突顯程式碼衝突等。
重點三：實測證明擴充至12條規則並未降低指令遵循度，反而有效彌補舊版規則在處理大型專案與長期任務時的重大盲點。
知名AI研究員安德烈．卡帕西（Andrej Karpathy）於2026年初指出AI模型在編寫程式碼時的常見缺失。隨後，開發者Forrest Chang將其總結為4條CLAUDE.md指令，成功將高達 41% 的 AI 編碼錯誤率大幅降至 11%，在GitHub上斬獲逾12萬顆星。
然而，隨著AI生態系快速演進，有開發者針對30個程式碼庫進行長達六週的實測，發現將原有的AI編碼提示規則擴充至12條後，成功使Claude 的程式碼錯誤率從11%進一步壓縮至3%以下，全面提升了開發效率。
問題的起源：AI 助理為什麼會出錯？
今年 1 月，卡帕西在社群媒體上公開抱怨，他用 AI 寫程式，卻老是出問題。他歸納出3個反覆出現的模式：
AI 遇到不確定的情境時，不會詢問使用者，而是自行假設並繼續執行，導致最終產出與需求不符。
AI 傾向以複雜的架構解決可以用簡單方式處理的問題，引入多餘的抽象層與不必要的功能。
AI 在修改指定程式碼時，常順手「整理」周邊不相關的程式碼、格式或註解，造成難以追蹤的副作用。
總歸來說，以上3個問題的共通點，是AI在沒有明確規範的情況下，會自行填補空白，但內容並非是使用者想要的。
一篇抱怨文，意外變成全球12萬人都在用的解法
軟體工程師Forrest Chang在讀到卡帕西的貼文後，將這3個問題整理成4條具體的行為規則，以單一純文字檔案的形式發佈於開源平台 GitHub。
這份檔案名為「CLAUDE.md」，是一份放置於程式專案根目錄的純文字說明書，用途是告訴 AI 助理在協作過程中應當遵守哪些行為準則。
其運作原理類似於企業為新進員工準備的工作守則，規定AI在面對模糊指示、遇到衝突情境，或需要自行判斷時，必須依循哪些原則行事。
這份 65 行的檔案在 GitHub 上一天內獲得將近 6,000 人收藏，兩週突破 6 萬，目前已超過 12 萬，成為 2026 年成長最快的單一檔案開源專案。
這4條規則的核心要點分別為：
規則1：寫程式前先思考
實作前務必釐清所有假設與模糊地帶，絕不盲目猜測或替使用者做決定；若有更簡單的解法應主動提出，遇到任何不清楚的地方必須立刻停下來發問。
規則2：簡單至上
只用最少的程式碼解決當下問題，嚴格拒絕任何過度工程化、推測未來需求的功能或不必要的抽象層，確保產出符合資深工程師眼中的「精簡」標準。
規則3：手術式修改
只精準更動與需求直接相關的範圍，絕對不去「順手改善」或重構旁邊未損壞的程式碼及排版，並且只負責清理因本次修改才變成無用的變數或引入。
規則4：目標導向執行
將任務轉化為「可被驗證的具體目標」（例如：寫出測試並讓它通過），為多步驟任務建立帶有檢查點的計畫，讓 AI 能基於明確的成功標準自主迭代到完成。
從4條擴增到12條：新的問題在哪裡？
原始4條規則雖然有效，但資深AI工程師Mnimiy在進行系統性測試後發現，它們主要針對的是「單次對話中的寫程式錯誤」，但在面對2026年更複雜的多步驟AI代理協作（Agent-orchestration）與大型專案時，會暴露出以下幾個關鍵漏洞：
無法應付長時間運作的多步驟任務 ：原規則預設為單次互動，缺乏 Token 預算與進度檢查點。這導致 AI 在長任務中容易迷失方向、悄悄把錯誤疊加；同時也沒限制 AI 的職責，讓它越界去處理 API 路由等本該由純程式碼執行的確定性邏輯，徒增成本與不穩定性。 在多程式碼庫中會引發風格混亂 ：原規則要求「配合現有風格」，但當專案中同時存在新舊兩種相衝的寫法時，AI 會試圖將兩者「平均融合」，反而寫出更難除錯的四不像程式碼。 產生為通過而通過的無效測試 ：原規則要求 AI 循環執行直到成功，導致 AI 為了交差，寫出毫無業務價值、只為了亮綠燈的淺層測試（例如把數值寫死），掩蓋了真實的邏輯錯誤。 扼殺原型開發的彈性 ：「簡單至上」規則嚴禁任何推測性架構與多餘程式碼，這能有效保護正式環境，但對於需要快速搭建框架、探索方向的原型開發階段，反而會讓 AI 綁手綁腳。
https://t.co/W4MxdOyUKD— Mnimiy (@Mnilax) May 9, 2026
Mnimiy針對這4個缺口，歷經六週、橫跨30個專案，新增了8條規則，填補AI代理時代的系統盲點，讓AI的編寫錯誤率從11%降至 3%。
新增的8條規則解決了什麼問題？
以下是Mnimiy提出的8條規則，用來補足前4條規則的複雜 AI 代理協作的死角。
規則5：只讓 AI 做需要判斷力的事
將 AI 用於分類、摘要、草擬等主觀判斷工作，嚴禁讓 AI 去處理狀態碼判斷、API 重試或路由分配。
只要能用傳統程式碼以 if-else 邏輯寫死的確定性任務，就應交由純程式碼執行，避免模型產生隨機且不可靠的決策。
<code>## Rule 5 — Use the model only for judgment calls Use Claude for: classification, drafting, summarization, extraction from unstructured text. Do NOT use Claude for: routing, retries, status-code handling, deterministic transforms. If a status code already answers the question, plain code answers the question. </code>
規則6：強制設定詞元預算上限
明確規範單一任務（如 4,000 tokens）與單次對話（如 30,000 tokens）的消耗上限。當運算資源即將耗盡時，模型必須主動總結當前進度並要求重新啟動對話。
此舉可防止模型在無法解決的錯誤中陷入無限迴圈，造成不必要的資源與成本浪費。
<code>## Rule 6 — Token budgets are not advisory Per-task budget: 4,000 tokens. Per-session budget: 30,000 tokens. If a task is approaching budget, summarize and start fresh. Do not push through. Surfacing the breach > silently overrunning. </code>
規則7：衝突要攤開講，禁止混合寫法
當程式庫中存在兩種相互矛盾的寫法時，AI 傾向「兩種都照顧到」，寫出一個試圖同時滿足兩種規範的程式碼。這比任何一種原始寫法都更難維護。
規則7要求 AI 選擇其中一種（優先選較新或測試較完整的），說明理由，並標記另一種待日後清理。
<code>## Rule 7 — Surface conflicts, don't average them If two existing patterns in the codebase contradict, don't blend them. Pick one (the more recent / more tested), explain why, and flag the other for cleanup. "Average" code that satisfies both rules is the worst code. </code>
規則8：寫程式前先讀懂周邊程式碼
在新增或修改任何程式碼之前，模型必須先讀取該檔案的輸出 (exports)、直接呼叫者函數以及相關的共用工具程式碼。
不允許模型在未完全理解現有程式碼結構的情況下，以兩者互不相關為由直接寫入新功能。
<code>## Rule 8 — Read before you write Before adding code in a file, read the file's exports, the immediate caller, and any obvious shared utilities. If you don't understand why existing code is structured the way it is, ask before adding to it. "Looks orthogonal to me" is the most dangerous phrase in this codebase. </code>
規則9：測試要驗證為什麼，不只是有沒有
模型編寫的測試程式碼必須能真實反映商業邏輯的運作。如果一項業務邏輯發生改變，相關的測試卻依然能夠通過（例如模型為了讓測試亮綠燈而將回傳值寫死），即代表該測試無效。
測試的目的是驗證行為為何重要，而非僅驗證程式有在執行。
<code>## Rule 9 — Tests verify intent, not just behavior Every test must encode WHY the behavior matters, not just WHAT it does. A test like `expect(getUserName()).toBe('John')` is worthless if the function takes a hardcoded ID. If you can't write a test that would fail when business logic changes, the function is wrong. </code>
規則10：多步驟任務每完成一步就要回報
長時間的重構或功能開發橫跨多個步驟，一旦中途出錯，後續步驟可能全部建立在錯誤的基礎上。
規則10要求 AI 在完成每個重要步驟後，主動回報「已完成事項、已驗證事項、剩餘事項」，若模型在執行過程中遺失上下文，無法精確描述當前狀態，就必須立即中止任務並重新釐清，防止錯誤進度持續疊加。
<code>## Rule 10 — Checkpoint after every significant step After completing each step in a multi-step task: summarize what was done, what's verified, what's left. Don't continue from a state you can't describe back to me. If you lose track, stop and restate. </code>
規則11：遵從現有慣例，不要偷偷引入新風格
每個程式庫都有自己的命名規則、元件寫法與錯誤處理模式。AI 即便認為自己的寫法更好，也不應在沒有告知的情況下引入新風格，因為「兩種風格並存」比任何一種風格單獨使用都更難維護。
無論模型是否認為某種新框架或寫法更優良，只要專案既定採用特定的命名規則或舊有架構，模型就必須完全配合，禁止在未經討論的情況下擅自引入新風格。
<code>## Rule 11 — Match the codebase's conventions, even if you disagree If the codebase uses snake_case and you'd prefer camelCase: snake_case. If the codebase uses class-based components and you'd prefer hooks: class-based. Disagreement is a separate conversation. Inside the codebase, conformance > taste. If you genuinely think the convention is harmful, surface it. Don't fork it silently. </code>
規則12：主動揭露錯誤，禁止隱性失敗
這是 8 條新規則中最受關注的一條。規則要求 AI 在任何步驟有疑問、有遺漏，或無法完整驗證結果時，必須明確回報異常，絕對不允許回報「執行完成」或「測試通過」。
必須將所有不確定性或未執行的步驟完整呈現給開發者，確保沒有任何錯誤被默默忽略。
<code>## Rule 12 — Fail loud If you can't be sure something worked, say so explicitly. "Migration completed" is wrong if 30 records were skipped silently. "Tests pass" is wrong if you skipped any. "Feature works" is wrong if you didn't verify the edge case I asked about. Default to surfacing uncertainty, not hiding it. </code>
完整12條規則一次下載
<code># CLAUDE.md — 12-rule template
These rules apply to every task in this project unless explicitly overridden. Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.
## Rule 1 — Think Before Coding State assumptions explicitly. If uncertain, ask rather than guess. Present multiple interpretations when ambiguity exists. Push back when a simpler approach exists. Stop when confused. Name what's unclear.
## Rule 2 — Simplicity First Minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. Test: would a senior engineer say this is overcomplicated? If yes, simplify.
## Rule 3 — Surgical Changes Touch only what you must. Clean up only your own mess. Don't "improve" adjacent code, comments, or formatting. Don't refactor what isn't broken. Match existing style.
## Rule 4 — Goal-Driven Execution Define success criteria. Loop until verified.