Claude Code 必裝的 CLAUDE.md？我用 10 個真實工單測試了 Karpathy Skills

先說結果。為了驗證 Karpathy Skills（社群整理的 CLAUDE.md 行為準則）是否真的有用，我挑了 10 個真實工單，固定 Claude Opus 4.8，唯一變數是是否啟用 Karpathy 四條原則。一週下來，最讓我記住的數字是：

也有失望的時候——改一個常數的工單，準則幾乎沒幫上忙，還多了一輪「確認假設」的囉嗦。下文會把成功與失敗都寫清楚，並附上我儲存庫裡正在用的 CLAUDE.md 最終版本（Claude Code Rules / Prompt 長尾詞會搜到這類內容）。

Claude Code 為什麼總亂改程式碼？

不是模型「笨」，而是預設優化目標和工程師不一致：它傾向於盡快產出「看起來完整」的修補——多寫抽象、多改鄰檔、少問歧義。Andrej Karpathy 在 X 上歸納過四類慢性病灶：沒問清楚就動手、簡單需求過度工程、順手改不該改的檔案、用「搞定它」代替可驗證目標。

2026 年春天，社群把這套觀察壓進一個幾十行的 CLAUDE.md（forrestchang/andrej-karpathy-skills，亦稱 Karpathy Skills）。沒有新執行環境，只有四條行為合約——Claude Code 每次開工作階段都會讀。我關心的是：I tested it — 數字到底多少。

Karpathy Skills 是什麼？

名字裡帶 Skills，但產物形態是專案級指令檔，不是 OpenAI GPT、也不是 OpenHuman 的 SKILL.md 外掛包。Claude Code 啟動工作階段時會讀取儲存庫根目錄的 CLAUDE.md（以及全域外掛注入的等價文字），在你敲第一行需求之前就約束 Agent 怎麼思考、怎麼改 diff。

四條原則與官方 CLAUDE.md 原文一一對應（見 儲存庫 CLAUDE.md）：

• Think Before Coding：先陳述假設、暴露歧義、提出更簡單方案，而不是靜默選一種理解開寫。
• Simplicity First：只寫解決問題所需的最小程式碼；拒絕未被要求的抽象、設定項與「將來可能用到」的層。
• Surgical Changes：只動任務相關行；不順手「整理」鄰域程式碼；自己引入的死程式碼要清，歷史遺留的只提示不刪。
• Goal-Driven Execution：把「修 bug / 加校驗」改寫成可驗證目標（先寫失敗測試再綠），多步任務列出每步的 verify 檢查點。

安裝方式二選一：Claude Code 外掛 /plugin install andrej-karpathy-skills@karpathy-skills，或把上游 CLAUDE.md 合併進你儲存庫根目錄——下文「我的 CLAUDE.md 最終版本」可直接複製。

我的測試方法

為了驗證這套規則是否真的有用，我按下面方式控制變數（測試運行於 Mac mini M4 Cloud Mac，只為保證 tmux 長跑與 xcodebuild 不斷線；結論與是否在雲端無關，你在本機 Mac 上同樣可以重現）：

• 10 個真實工單：Swift 小功能 4、跨檔重新命名 2、補測試 2、CI 腳本 2。
• 固定模型：claude-opus-4-8，Effort high，同一週內不升級小版本。
• 唯一變數：對照組用舊 CLAUDE.md（無 Karpathy 段）；實驗組合併四條原則 + 下文兩條團隊規則。
• 每個工單跑兩次（先 A 後 B 或隔天交替），避免「同一天狀態好」偏差。

記錄五類指標，對齊評審裡真正費時間的部分：

10 個工單測試結果

下表為中位數（n=10，非官方基準）。若你只記一個數：無關 diff −78%。

展開無關 diff：18% → 4%，即 Agent 仍改了很多檔案，但「Payment 模組被順手格式化」這類路徑從 diff 裡消失了——Surgical Changes 直接對應這條曲線。首次 CI 綠 5/10 → 8/10 則主要來自 Goal-Driven Execution：Agent 更常先補失敗測試再改實作。

哪些場景提升最大？

• 跨檔重新命名 / 改簽名：無關 diff −78% 體感最明顯，CR 不再像「掃雷」。
• 需求略含糊的小功能：Think Before Coding 逼 Agent 先列假設，返工從 3 次降到 1 次（工單 PAY-1842、AUTH-901）。
• 補測試 + 改實作：一次綠率上升，Goal-Driven 的「先紅後綠」被寫進 CLAUDE.md 後執行更穩定。

與 程式碼知識圖譜 正交：圖譜答「改哪裡」，CLAUDE.md 答「別亂改」。

哪些場景幾乎沒提升？（含失敗案例）

一個讓我失望的任務：改一個常數。 工單 CFG-77：把 maxRetryCount 從 3 改為 5，路徑已寫明。啟用 Karpathy 後，Agent 仍多了一輪：「是否也要改退避策略與單元測試預設值？」——澄清步驟 +1，diff 品質與無準則時一樣乾淨，總耗時反而多 4 分鐘。這類規格極清的單點修改，四條裡的 caution 偏「過度認真」，幾乎 0 收益。

其它幾乎無效的情況：

• 團隊 CLAUDE.md 已很長且與 Karpathy 重複——邊際收益遞減。
• 沒有測試 / xcodebuild——Goal-Driven 無法閉環，Agent 仍會「看起來做完」。
• 只在聊天裡問問題、不寫儲存庫——CLAUDE.md 根本不載入。

我的 CLAUDE.md 最終版本（可直接複製）

Claude Code 使用者搜 CLAUDE.md、Claude Code Rules、Claude Code Prompt，最終要的是能貼進儲存庫的成品。下面是我合併 Karpathy 四條 + 兩條 iOS 團隊規則後的版本（英文正文與上游一致，便於模型遵循；中文說明見註解）：

# CLAUDE.md — Karpathy rules + Vuncloud iOS team

## Think Before Coding
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing: state assumptions; if unclear, ask; if a simpler approach exists, say so.

## Simplicity First
Minimum code that solves the problem. Nothing speculative.
No extra abstractions, config, or error handling for impossible cases.

## Surgical Changes
Touch only what you must. Don't "improve" adjacent code or formatting.
Match existing style. Mention unrelated dead code; don't delete unless asked.

## Goal-Driven Execution
Transform tasks into verifiable goals (tests first when applicable).
Multi-step: list plan with verify check per step.

## Vuncloud: Build Verification (custom)
After code changes to Swift/ObjC targets, run before claiming done:
  xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16'
Report exit code. If tests fail, fix or stop — do not claim success.

## Vuncloud: Path Allowlist (custom)
Unless the user explicitly expands scope, only edit paths they named
or standard paired test paths (e.g. Sources/Foo/ ↔ Tests/Foo/).

安裝上游原文可執行：

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

# 或 per-project：
curl -fsSL -o /tmp/karpathy-claude.md \
  https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# 勿覆寫既有 CLAUDE.md，合併段落即可

Cursor 使用者：同步 .cursor/rules/karpathy-guidelines.mdc，與 Claude Code 保持同一語意。測 Karpathy 時務必固定 claude-opus-4-8，別與模型升級攪在一起——見 Opus 4.8 長跑指南。

Cloud Mac 長跑方案（Claude Code → tmux → Mac mini）

這篇比 OpenHuman 更適合談 Cloud Mac，因為鏈路天然閉合：Claude Code 長工作階段 → tmux 防斷線 → 同機 xcodebuild → 獨享 Mac mini。對照實驗、夜間 Agent、跨時區 CR 都怕筆電休眠；我在試點裡用 Cloud Mac 只為環境穩定，數字本身在你本機重現即可。

• tmux + Claude Code：SSH 斷開不殺工作階段（Opus 4.8 文內有範例）。
• 持久卷上的 CLAUDE.md：準則與 monorepo 綁定，不丟設定。
• Goal-Driven 硬驗收：把上節 Build Verification 寫進 CLAUDE.md，Agent 改完必須跑 Scheme。
• 與 Mac 雲端 CI 同機，改完即驗。

對照實驗腳本片段

TASK_ID="PAY-1842"
git diff --stat main...HEAD > "/tmp/${TASK_ID}-stat.txt"
git diff --name-only main...HEAD | wc -l | awk '{print "files_changed=" $1}'
# 無關路徑：人工或用 allowlist 對比
xcodebuild test -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 16' \
  | tee "/tmp/${TASK_ID}-xcodebuild.log"
echo "exit=$?" >> "/tmp/${TASK_ID}-xcodebuild.log"

在 Claude Code 裡下達任務時，盡量用目標句式餵給第四條準則，例如：

目標：為 CheckoutViewModel.validateAmount 增加非正數校驗。
驗證：1) 新增單元測試覆蓋 0、負數、NaN；2) xcodebuild test -scheme YourApp 通過；
範圍：僅允許修改 Sources/Checkout/ 與對應 Tests/，不要動 UI 主題與其它模組。

常見問題 (FAQ)

這是 Karpathy 官方寫的嗎？ 準則源自他在 X 上對 LLM 寫程式的觀察；CLAUDE.md 由社群整理（Forrest Chang 等維護）。Karpathy 轉發過相關儲存庫，請以儲存庫 README 為準。

和 Claude Code 自帶 memory / 專案說明衝突嗎？ 應合併而非覆寫。把四條原則放在 CLAUDE.md 前部，後面接你們團隊的命名、分支、測試命令。

能否替代 Code Review？ 不能。準則降低雜訊 diff 機率；合併門檻、人工 CR、安全掃描仍必需。

Cursor 使用者怎麼辦？ 複製 .cursor/rules/ 版本即可；與 Claude Code 共用同一 git 儲存庫時，保持兩份準則語意一致。

百分比結論能引用嗎？ 請引用你自己的對照實驗。本文表格僅為 Vuncloud 團隊試點範例，樣本 n=10，未做嚴格雙盲。

結論

我測了 Karpathy Skills，不是泛泛而談「有沒有用」。 10 個工單、固定 Opus 4.8：無關 diff 少 78%，首次 CI 綠 +30 個百分點；改常數則幾乎沒幫助。真正值錢的是一份寫進儲存庫的 CLAUDE.md——四條 Karpathy 原則 + 你自己的建置與路徑規則。Claude Code 長跑若要 7×24，Mac mini Cloud Mac + tmux 比 OpenHuman 賣 Mac 自然得多：Agent、終端、Xcode 本來就該在同一台 macOS 上。