21 萬星的 CLAUDE.md：一個檔案改掉 Claude 寫 code「想太多、亂改」的壞習慣

用 Claude Code（或 Cursor）寫程式一陣子，你大概遇過這些狀況：

一個小功能，它寫了三個新檔案、兩層抽象，外加一堆你沒要的設定。
你只叫它修一個 bug，它順手「優化」了旁邊十幾行，連註解都改掉。
它說「完成了！」，結果一跑就壞。

這些問題，AI 圈大神 Andrej Karpathy（前特斯拉 AI 總監、OpenAI 創始成員）在 X 上寫過一篇觀察，講得非常精準。後來有人把他的觀察整理成一份 CLAUDE.md，放上 GitHub，到 2026 年 10 月已經累積 超過 21.7 萬顆星。

這篇帶你看這份檔案到底寫了什麼、為什麼有效，以及兩種安裝方法。

先說清楚：這份檔案不是 Karpathy 本人寫的，而是第三方根據他的貼文整理出來的。repo 名稱是 andrej-karpathy-skills，README 標題是「Karpathy-Inspired Claude Code Guidelines」。

什麼是 CLAUDE.md？

CLAUDE.md 是 Claude Code 會自動讀取的專案說明檔。只要放在專案根目錄，Claude 每次開工前都會先看過一遍，等於是給它一份「工作守則」。

大部分人的 CLAUDE.md 寫的是專案架構、指令、程式風格。這份 Karpathy 版不一樣：它不講你的專案，只講 AI 寫程式時的行為——什麼時候該停下來問、什麼時候不要多做。

整份檔案只有 65 行，核心是四個原則。

原則一：Think Before Coding（先想再寫）

Don't assume. Don't hide confusion. Surface tradeoffs.

Karpathy 觀察到，模型很常「替你做了錯誤的假設，然後就一路衝下去，不回頭確認」。

所以第一條要求 Claude：

不確定的地方，先說出你的假設，或直接問。
需求有多種解讀時，把幾種可能列出來，不要自己挑一個默默做。
如果有更簡單的做法，要講出來（必要時反駁使用者）。
搞不清楚就停下來問，不要硬做。

效果：它會在動手前多問一兩句，看起來慢一點，但省掉「做了半天方向錯」的時間。

原則二：Simplicity First（簡單優先）

Minimum code that solves the problem. Nothing speculative.

這條直接對應 Karpathy 那句名言：AI 很愛把程式寫複雜，「明明 100 行能搞定，它寫 1000 行」。

檔案裡的具體規則：

不加沒人要求的功能。
只用一次的東西，不要包成抽象層。
不加沒人要求的「彈性」或「可設定性」。
不為不可能發生的情況寫錯誤處理。
如果寫了 200 行、其實 50 行就夠，重寫。

還附了一個自我檢查問題：「一個資深工程師看了，會不會覺得這太複雜？」

原則三：Surgical Changes（精準修改）

Touch only what you must. Clean up only your own mess.

這條是很多人最有感的。AI 修改程式時常常「順便」動到旁邊的東西：改格式、改註解、重構沒壞的程式碼，最後 diff 一大坨，根本不知道它到底改了什麼。

規則是：

不要「改善」旁邊的程式碼、註解或格式。
沒壞的東西不要重構。
照原本的程式風格寫，就算你偏好別的寫法。
發現無關的死碼，提出來就好，不要自己刪。
只清掉「因為你這次修改而變成沒用」的東西。

檢查標準：每一行改動，都要能對應到使用者的需求。

原則四：Goal-Driven Execution（目標導向）

Define success criteria. Loop until verified.

Karpathy 的關鍵洞察是：LLM 非常擅長「一直重試直到達成某個明確目標」。所以與其告訴它怎麼做，不如給它成功的標準。

檔案把模糊的指令轉成可驗證的目標：

原本的指令	改成
「加個驗證」	先寫無效輸入的測試，再讓它通過
「修這個 bug」	先寫一個能重現 bug 的測試，再讓它通過
「重構 X」	確保重構前後測試都通過

多步驟任務則要求它先列計畫，每一步都寫好「怎麼驗證」。

效果：「說做完但其實沒做完」的情況會少很多，因為它得先證明測試過了。

怎麼安裝？兩種方法

方法一：Claude Code 外掛（推薦，所有專案通用）

在 Claude Code 裡輸入：

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

裝成外掛後，所有專案都會套用。

方法二：只放進單一專案

新專案，直接下載成 CLAUDE.md：

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

已經有 CLAUDE.md 的專案，用「附加」的方式，不會蓋掉你原本的內容：

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

repo 現在的網址是 github.com/multica-ai/andrej-karpathy-skills，舊網址 forrestchang 會自動轉過去，上面的指令照樣能用。repo 裡也有給 Cursor 用的規則檔（.cursor/rules/karpathy-guidelines.mdc）。

怎麼知道它有沒有用？

檔案最後寫了它「有在作用」的跡象：

diff 變乾淨：只出現你要求的改動。
比較少因為寫太複雜而重寫。
動手前會先問釐清問題，而不是做錯了才改。
PR 變小、變乾淨，沒有順手的「重構」跟「改善」。

要注意的地方

它偏向「謹慎」而不是「快」。 檔案自己也寫了：很簡單的小任務（改個錯字、一行修正）不需要走完整套流程，讓 AI 自己判斷。
它不是萬靈丹。 例如網路上有人說它能「防止 AI 亂編不存在的 API」，但檔案裡其實沒有這條。它主要解決的是：亂猜、寫太複雜、亂改無關的程式、沒驗證就說完成。
授權：README 寫 MIT，但 repo 裡目前沒有 LICENSE 檔，如果要用在公司專案，建議自己確認一下。

參考連結

GitHub：https://github.com/multica-ai/andrej-karpathy-skills
Karpathy 原文（X）：https://x.com/karpathy/status/2015883857489522876

有用的話，歡迎到 IG @aihub.tw 跟我說你的 Claude 有沒有變乖。