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

> Karpathy 觀察整理成的 CLAUDE.md：先想再寫、簡單優先、精準修改、目標導向四原則，附 Claude Code 外掛與單一專案兩種安裝方法。

- 網址：https://yourjobpocket.com/learn/claude-karpathy-claudemd
- 發布：2026-10-16
- 主題：Claude Code
- 作者：@your.engineer.ben（https://www.instagram.com/your.engineer.ben/）
- 出處：Lesson by Job Pocket（https://yourjobpocket.com/learn），免費、不用登入

用 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`）。

---

## 怎麼知道它有沒有用？

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

1. **diff 變乾淨**：只出現你要求的改動。
2. **比較少因為寫太複雜而重寫。**
3. **動手前會先問釐清問題**，而不是做錯了才改。
4. 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 [@your.engineer.ben](https://www.instagram.com/your.engineer.ben/) 跟我說你的 Claude 有沒有變乖。
