Appearance
CLAUDE.md 最佳實踐：12 條規則
透過精簡行為規則（不超過 200 行）系統性關閉 Claude 的已知失敗模式，將錯誤率從 41% 降至 3%。
概述
CLAUDE.md 是放在 repo 根目錄的純文字檔，Claude Code 每次啟動時都會載入它作為行為指引。正確使用時，它是「行為契約」——針對你在這個 codebase 實際觀察到的失敗模式，逐條關閉；錯誤使用時，它是噪音——令 Claude 遵從率從 80% 降至 30%，甚至更低。
2026 年 1 月，Andrej Karpathy 公開批評 Claude 的三大程式撰寫缺陷：靜默的錯誤假設、過度複雜化、以及不必要修改無關程式碼。Forrest Chang 將這些問題包裝為 4 條行為規則後，首日獲得 5,828 顆星，兩週 60,000 個書籤。隨後有作者在此基礎上橫跨 30 個 codebase 進行 6 週測試，補充了 8 條規則，將錯誤率從 11% 再降至 3%。
核心限制：Anthropic 官方文件指出 CLAUDE.md 為「建議性」文件，遵從率約 80%。超過 200 行後，重要規則會被雜訊淹沒，遵從率急劇下降。規則要少而精，每條必須能回答「這防止了什麼錯誤？」
核心內容
Karpathy 原始 4 條規則
Rule 1 — Think Before Coding（先想再寫）
明確陳述假設；不確定時詢問而非猜測；存在歧義時提出多種解讀；有更簡單方案時主動提出；感到困惑時停下來，說明哪裡不清楚。
Rule 2 — Simplicity First（簡單優先）
最少程式碼解決問題，不寫推測性功能；不為單次使用的程式碼引入抽象層。自測：資深工程師會說這過度複雜嗎？若是，則簡化。
Rule 3 — Surgical Changes（外科手術式修改）
只碰必須碰的地方，只清理自己製造的混亂；不「順手改善」相鄰程式碼、註解或格式；不重構沒有壞掉的東西，符合現有風格。
Rule 4 — Goal-Driven Execution（目標驅動執行）
定義成功標準，循環直到驗證完成；告訴 Claude 成功長什麼樣，讓它自行迭代。強健的成功標準讓 Claude 能獨立循環。
補充 8 條規則（覆蓋 Karpathy 未涵蓋的失敗模式）
Rule 5 — 只將模型用於判斷性任務
Claude 適合：分類、起草、摘要、從非結構化文字提取資訊。不適合：路由、重試、狀態碼處理、確定性轉換。若程式碼已能回答問題，就用程式碼回答。
觸發背景：「是否重試 503」的邏輯交給 Claude 判斷，導致每週決策不同、行為不穩定。
Rule 6 — Token 預算不是建議，是強制規定
| 範圍 | 預算上限 |
|---|---|
| 單一任務 | 4,000 tokens |
| 單一 session | 30,000 tokens |
接近預算時：摘要後重新開始，不強行繼續；明確回報預算接近，不靜默超支。
觸發背景：90 分鐘除錯 session，Claude 對同一份 8KB 錯誤訊息迭代，逐漸忘記哪些修法已試過，最後建議早已被否決的方案。
Rule 7 — 浮現衝突，不要平均化
若 codebase 中兩種模式相互矛盾，選擇一種（較新 / 測試較完整的），說明選擇原因，並標記另一種待清理。「同時滿足兩種規則的平均程式碼是最差的程式碼」。
觸發背景：Codebase 同時存在兩種錯誤處理模式，Claude 寫出同時使用兩者的程式碼，錯誤被吞兩次，耗費 30 分鐘排查。
Rule 8 — 先讀再寫
在任何檔案中新增程式碼前，必須先閱讀：該檔案的 exports、直接呼叫者（immediate caller）、明顯的共用 utilities。「看起來跟現有程式碼無關」是最危險的一句話。
觸發背景：Claude 在現有函式旁新增功能完全相同的函式，因 import 順序取代了已作為 source of truth 長達 6 個月的舊函式。
Rule 9 — 測試驗證意圖，不只驗證行為
測試必須編碼「為何這個行為重要」，不只驗證函式有回傳值。無法在業務邏輯變更時失敗的測試，代表函式設計有誤。
觸發背景：Claude 為認證函式撰寫 12 個通過的測試，但函式實際上回傳的是常數。正式環境認證壞掉才發現問題。
Rule 10 — 每個重要步驟後設置檢查點
每完成一個步驟後，摘要：✅ 已完成什麼、✅ 已驗證什麼、🔲 還剩什麼。不要從一個你無法向我描述的狀態繼續。若失去脈絡，停下來重新陳述。
觸發背景：6 步驟重構在第 4 步出錯，但此時 Claude 已完成第 5、6 步，拆解所花時間比重做整件事還長。
Rule 11 — 符合 codebase 慣例，即使你不同意
在 codebase 內部，符合規範 > 個人品味。若真的認為某慣例有害，明確提出，不要靜默分叉。
觸發背景：Claude 在 class-component codebase 中引入 React Hooks，破壞了依賴
componentDidMount的測試模式，耗費半天移除並重寫。
Rule 12 — 大聲失敗，不要靜默成功
| 錯誤說法 | 問題所在 |
|---|---|
Migration completed | 若有任何記錄被靜默跳過，此陳述即為錯誤 |
Tests pass | 若有任何測試被跳過，此陳述即為錯誤 |
Feature works | 若詢問的邊界案例未被驗證，此陳述即為錯誤 |
預設行為：浮現不確定性，而非隱藏它。
觸發背景：Claude 回報資料庫 migration「成功完成」，但 14% 的記錄因 constraint violation 被靜默跳過，11 天後報表異常才發現。
Karpathy 原始規則的 4 個盲點
| 盲點 | 說明 |
|---|---|
| 長時間執行的 agent 任務 | 原始規則針對單次程式碼撰寫，對多步驟 pipeline 無預算規則、無檢查點規則、無「大聲失敗」規則 |
| 多 codebase 一致性 | 「符合現有風格」預設只有一種風格；monorepo 中 Claude 隨機選擇或取平均 |
| 測試品質 | Goal-Driven Execution 把「測試通過」當成成功，未要求測試有意義 |
| 正式環境 vs 原型 | Simplicity First 保護正式程式碼，卻也拖慢合理需要推測性鷹架的早期探索 |
已排除的無效嘗試
| 嘗試方案 | 為何失敗 |
|---|---|
| 超過 12 條（測試至 18 條） | 超過 14 條後遵從率從 76% 降至 52%；200 行上限是真實的 |
依賴可能不存在工具（如 always use eslint） | 工具不存在時靜默失敗；改為能力無關的描述 |
| 在 CLAUDE.md 中使用範例而非規則 | 3 個範例耗費與 10 條規則相當的 context，且 Claude 會過度擬合 |
be careful / think hard / really focus | 純噪音，遵從率降至 30%；改為具體命令式（如「明確陳述假設」） |
| 要求 Claude 表現得「資深」 | 無效；Claude 已認為自己是資深的 |
關鍵要點
- CLAUDE.md 不是願望清單，是關閉特定已觀察到失敗模式的行為契約
- 每條規則都應能回答：這條規則防止了什麼錯誤？
- 不超過 200 行：超過後遵從率明顯下降
- 針對你真實遇過的失敗模式調整的 6 條規則，遠勝過包含 6 條你永遠用不到的規則的 12 條清單
- 從 4 條規則擴展到 12 條，遵從率幾乎不變（78% → 76%），但錯誤率再降 8 個百分點，因為新規則覆蓋的是不同的失敗模式
實際應用
測試數據（50 個代表性任務，橫跨 30 個 codebase，6 週）：
| 配置 | 錯誤率 | 規則遵從率 |
|---|---|---|
| 無 CLAUDE.md | 41% | — |
| Karpathy 原始 4 條規則 | 11% | 78% |
| 完整 12 條規則 | 3% | 76% |
常見誤用模式：
| 誤用模式 | 後果 |
|---|---|
| 堆砌所有偏好，膨脹至 4,000+ tokens | 遵從率降至 30% |
| 完全略過，每次手動提示 | Token 浪費 5 倍，跨 session 無一致性 |
| 複製範本後放著不管 | 兩週內靜默失效 |
部署設定參考
以下為可直接複製使用的完整 12 條規則範本。
完整 12 條 CLAUDE.md 範本
markdown
# 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.
Don't follow steps. Define success and iterate.
Strong success criteria let you loop independently.
## Rule 5 — Use the model only for judgment calls
Use me for: classification, drafting, summarization, extraction.
Do NOT use me for: routing, retries, deterministic transforms.
If code can answer, code answers.
## Rule 6 — Token budgets are not advisory
Per-task: 4,000 tokens. Per-session: 30,000 tokens.
If approaching budget, summarize and start fresh.
Surface the breach. Do not silently overrun.
## Rule 7 — Surface conflicts, don't average them
If two patterns contradict, pick one (more recent / more tested).
Explain why. Flag the other for cleanup.
Don't blend conflicting patterns.
## Rule 8 — Read before you write
Before adding code, read exports, immediate callers, shared utilities.
"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.
## Rule 9 — Tests verify intent, not just behavior
Tests must encode WHY behavior matters, not just WHAT it does.
A test that can't fail when business logic changes is wrong.
## Rule 10 — Checkpoint after every significant step
Summarize what was done, what's verified, what's left.
Don't continue from a state you can't describe back.
If you lose track, stop and restate.
## Rule 11 — Match the codebase's conventions, even if you disagree
Conformance > taste inside the codebase.
If you genuinely think a convention is harmful, surface it. Don't fork silently.
## Rule 12 — Fail loud
"Completed" is wrong if anything was skipped silently.
"Tests pass" is wrong if any were skipped.
Default to surfacing uncertainty, not hiding it.安裝方式
bash
# 步驟 1：將 Karpathy 原始 4 條規則附加到現有 CLAUDE.md
# （使用 >> 而非 >，避免覆蓋已有的專案特定規則）
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
# 步驟 2：將 Rule 5–12 貼到下方，儲存至 repo 根目錄相關概念
- Claude Code 權限模式與安全設定 — Claude Code 的六種權限模式與安全設定，CLAUDE.md 是設定行為規則的配套
- Superpowers AI 開發方法論 — 強制性 AI 開發工作流，與 CLAUDE.md 規則形成互補的多層次約束
- OpenSpec SDD 框架 — Spec-Driven Development 框架，透過規格文件而非 CLAUDE.md 規則來控制 Claude 行為的另一種取向
- GitHub Copilot Sub-Agent 編排 — 多 Agent 協作時，每個 Agent 的行為控制同樣依賴類似原則