最近用 Claude Code 的開發者多半都會在 X 或 GitHub 看到一波討論：Andrej Karpathy 整理的「Claude Code 四條原則」CLAUDE.md 短短四個月衝到 15 萬 star，幾乎變成新進使用者第一個被推薦複製貼上的模板。但這份檔案實際上有一個常被忽略的細節——大家口中「Karpathy 的 CLAUDE.md」其實混淆了兩份不同的東西。他本人提交在自己 repo 的 CLAUDE.md，跟那份 4 條原則的 README，根本不是同一份檔案、也不是同一種寫法。
這篇文章不只是介紹他這個人或這兩份檔案，而是借這個案例討論一個更實用的問題：CLAUDE.md 究竟該寫什麼？先看清楚原作者版與社群編輯版的差別，再拆解兩種主流思路——當作「codebase 旅遊指南」或當作「agent 行為守則」——看完之後可以照自己專案的需要決定怎麼寫，而不是看到 star 數高就直接抄一份。
CLAUDE.md 是什麼
對 Claude Code 不熟的讀者可以先看 Claude Code 入門教學 的 CLAUDE.md 章節打基礎，這邊只簡單帶過。CLAUDE.md 是一份純文字的 Markdown 設定檔，Claude Code 每次新對話開始、agent 進到某個資料夾時，都會自動讀取它的內容、當成 system prompt 的一部分餵給模型；目的是讓 agent 在動工之前先掌握這個專案的脈絡、慣例與不可踩雷的規則。
放置位置有兩個層級，可以同時存在，Claude Code 兩份都會讀進來：
~/.claude/CLAUDE.md：個人全域，所有 repo 共用，適合放跨專案通用的工作紀律（例如「commit message 用繁體中文」「不要主動 push 到 main」這類習慣）<repo>/CLAUDE.md：專案層級，跟 source code 一起 commit 進 git，整個團隊用 Claude Code 都會自動套用，適合放這個 repo 才有的規範與技術細節
順帶一提，CLAUDE.md 這個檔名是 Claude Code 自己的慣例；其他 AI 編碼工具（例如 OpenAI Codex CLI）用的是 AGENTS.md，內容性質一樣、差別只在檔名與讀取時機。實務上想同時相容多個工具的 repo 會把兩個檔都放、或在 git 裡用 symlink 指向同一份檔案，讓使用不同 agent 的人都吃得到同一份設定。
裡面要寫什麼沒有硬規定，可以是純技術筆記、可以是行為守則、可以兩者並存——這正是本文後面要拆解的問題。
Karpathy 是誰
Andrej Karpathy（安德烈·卡帕西）是史丹佛大學博士、OpenAI 共同創辦人之一（2015–2017），後來去 Tesla 當 AI Director（2017–2022）主導 Autopilot 電腦視覺團隊，之後短暫回鍋 OpenAI（2023–2024），目前在做名為 Eureka Labs 的 AI 教育新創。
不過他在開發者圈廣為人知的真正原因，是他持續產出的教育內容：用幾百行 C 寫 GPT 的 llm.c、單檔 PyTorch 重現 GPT 訓練的 nanoGPT、YouTube 上「Neural Networks: Zero to Hero」教學系列。他不是純粹的「推特網紅」，而是會親手把大型專案做出來、再把過程寫成乾淨教材的開發者；他講工具、講工作流時有人聽，是因為背後有實作支撐。
所以當他在 2026 年 1 月開始公開談 Claude Code 工作流，很多人就把他的觀察當成可參考的範本。問題只在於，後續流傳的版本跟他本人實際在 repo 裡放的檔案，是兩件不同的事。
原作者版與社群編輯版的差別
網路上流傳的「Karpathy 的 CLAUDE.md」有兩個來源，性質完全不同：
| 分類 | Repo | 建立時間 | Star 數 | 作者 | 性質 |
|---|---|---|---|---|---|
| 原作者版 | karpathy/llm-council | 2025-11-22 | 約 19,000 | Karpathy 本人 | 專案技術筆記 |
| 社群編輯版 | multica-ai/andrej-karpathy-skills | 2026-01-27 | 約 156,000 | 社群 (multica-ai) | 行為原則歸納 |
社群編輯版那個 README 開頭就老實標註「derived from Andrej Karpathy’s observations on LLM coding pitfalls」，原始來源是他 2026 年 1 月在 X 上的一系列推文，整理者是 multica-ai 與 Forrest Chang。這份檔案的內容是有價值的，但不是 Karpathy 本人 commit 進自己 repo 的設定。混淆的代價是：很多人以為複製貼上這份就「在用 Karpathy 的工作流」，事實上 Karpathy 自己的 repo 裡寫的是完全不同風格的 CLAUDE.md。
下面分別看兩種寫法。
思路一：CLAUDE.md 當作 codebase 的旅遊指南
Karpathy 親手寫的 llm-council/CLAUDE.md 開頭就明確定位：「This file contains technical details, architectural decisions, and important implementation notes for future development sessions.」——這份檔案是寫給「未來的開發 session」看的技術筆記，不是行為守則。整份檔案的章節結構大概是這樣：
- Project Overview：一段話講這個專案在做什麼
- Architecture：逐個資料夾、逐個檔案說明角色（backend、frontend、API 介面）
- Key Design Decisions：當初決定怎麼做、為什麼這樣做
- Important Implementation Details：寫程式時要記得的細節
- Common Gotchas：之前踩過的坑與避雷紀錄
- Future Enhancement Ideas：列了但還沒做的功能
- Testing Notes：手動測試流程
- Data Flow Summary：用 ASCII 圖把資料流畫出來
內容最大的特色是「處處解釋為什麼」。隨手挑一段對應的 Architecture 段落，會看到類似這樣的句子：
Backend runs on **port 8001** (NOT 8000 - user had another app on 8000)
Frontend dev server: **port 5173** (Vite default)
Metadata is NOT persisted (in-memory only) - intentional, see Design Decisions每一條設定都附上原因。port 8001 不是隨意選的——是因為使用者另一個 app 佔了 8000；metadata 不持久化不是 bug，是刻意為之、相關設計理由可以翻到下面那一節。「Common Gotchas」也是同個味道：把以前踩過的 module import 路徑問題、CORS 設定、ranking parse 失敗的 fallback regex 條列出來，下次 agent 或自己回頭看程式時不必再從錯誤訊息倒推。
這種寫法的特色與適用情境：
- 適合的情境：個人或小團隊長期維護的專案；CLAUDE.md 等於專案的 onboarding 文件，新加入的 agent session（或新成員）讀一遍就能跟上脈絡
- 不太適合的情境：要求 Claude 在所有專案都遵守同樣的行為紀律時，這種專案專屬的內容沒辦法跨 repo 共用
- 價值來源：把「為什麼這樣設計」的背景脈絡留下來，避免每一次新 session 都得重新理解。Agent 不像人類同事可以隨口問一句「為什麼這裡用 8001 不用 8000」，這類隱含知識若沒寫下來會反覆被誤改
值得注意的是，Karpathy 在另一個更新的 repo nanochat 裡並沒有放根目錄 CLAUDE.md，改成用 .claude/skills/*/SKILL.md 把能力切成多個 skill（例如自動下載 arXiv paper 並寫摘要）。這也是另一種思路：把跨專案可重用的能力做成 skill，而不是塞進單一 CLAUDE.md。
思路二：CLAUDE.md 當作 agent 行為守則
社群整理的那份 156K star 版本走的是完全不同路線：不寫專案細節，整份檔案幾乎只是四條「Claude 該怎麼工作」的紀律。這四條原則來自 Karpathy 在 X 上歸納 Claude Code 常見失誤模式時提到的四個 failure mode，逐條對應修正方向。原文是英文，下面把核心翻成中文：
原則一：先想再寫
「Think Before Coding」——不要靜默地猜測、不要藏起困惑、明確說出 trade-off、提出多個解法版本、簡單方案能解決就反問複雜方案的必要、不確定時停下來問。
對應的 failure mode 是「silent assumptions」：LLM 拿到模糊指令時習慣自己補全意圖、做完才發現方向錯了。要求它先把假設攤開，等於是強制它在出手前先對齊。
原則二：簡單優先
「Simplicity First」——最少程式碼、沒要求的功能不要做、單次使用的程式碼不要抽象化、不要為了「彈性」「可配置性」預留沒人要求的鉤子、不要為不可能發生的情境寫錯誤處理。一個自我檢查的句子：「一位資深工程師會不會說這段過度設計了？」
對應的 failure mode 是「hypertrophy of code/abstractions」：LLM 偏好「看起來很專業」的設計，會主動加上不必要的 interface、config、generic 化。一句反問就能擋住大部分這類過度設計。
原則三：外科手術式修改
「Surgical Changes」——不要「順手改善」鄰近程式碼、不要重構沒壞的東西、配合現存程式風格、刪除自己這次改動產生的孤兒程式碼但不要動本來就存在的死碼、每一行更動都應該能直接追溯到使用者的請求。
對應的 failure mode 是「collateral changes」：請 LLM 改 A 函式，它順便重寫了 B 的縮排、把 C 改成 async、把 import 順序整理一遍。每一個改動單獨看都有道理，但合起來 diff 變得難 review，而且容易藏 bug。這條原則的意義是把改動範圍鎖在「使用者要求的事」上。
原則四：目標驅動的執行
「Goal-Driven Execution」——把任務轉換成可驗證的目標。例如「加上輸入驗證」要改成「先寫一個用無效輸入會失敗的測試，再讓它通過」；「修這個 bug」要改成「先寫一個重現這個 bug 的測試，再讓它通過」。明確的成功條件能讓 agent 自己 loop 到目標達成為止。
對應的 failure mode 是「absence of verifiable success criteria」：給模糊任務（「做好驗證」），agent 跑一輪、自己覺得完成了、回報結束，但實際上沒測過邊界情況。給可驗證目標（一個會跑的測試），agent 就能自己重試到 pass 為止，不必每一步都人工 check。
Karpathy 為這個觀念補了一句很值得記住的 punchline：
LLMs are exceptionally good at looping until they meet specific goals. Don’t tell it what to do, give it success criteria and watch it go.
翻成中文：LLM 在「給定明確條件、自己 loop 到滿足為止」這件事上能力遠超想像；與其逐步指揮它，不如給它一個成功條件然後看它自己跑到目標達成。這個觀念跟前面三條原則合在一起，剛好構成「先對齊意圖、不過度設計、不擴張範圍、有可驗證目標」的工作迴圈。
這種寫法的特色與適用情境：
- 適合的情境：放在個人全域
~/.claude/CLAUDE.md，所有 repo 都吃得到；或團隊整體想統一 Claude Code 行為紀律時 - 不太適合的情境：作為單一專案的唯一文件——這些原則太抽象，對「這個 repo 怎麼跑起來、哪個檔案做什麼」毫無幫助
- 價值來源：用四條好背的規則收斂 LLM 常見的失誤路徑。對 Claude Code 用了一陣子的人，這些原則更像是把已經有的反射動作寫下來；對剛開始用的人，可以省下不少踩雷的時間
需要老實說的是，四條原則本質上是資深工程師早就在做的事——只是被整理成可以直接複製貼進 CLAUDE.md 的形式。15 萬 star 大部分是 Karpathy 名字帶來的流量，並不代表這份檔案本身有什麼開創性的技術突破。但「把模糊的反射動作寫成明確的規則」對 LLM 來說有意義，因為它就是吃 prompt 在運作的：寫下來、它才會記得遵守。
兩種思路怎麼混用
大部分專案值得「兩者都寫、但放在不同位置」，分層處理：
| 位置 | 放什麼 | 適合的內容類型 |
|---|---|---|
~/.claude/CLAUDE.md | 個人或團隊共用的行為紀律 | 四條原則、commit message 格式、回覆語氣、不該動的檔案 |
每個 repo 的 CLAUDE.md | 該專案專屬的技術筆記 | 架構說明、port 號、踩過的坑、資料流、設計動機 |
每個 repo 的 .claude/skills/*/SKILL.md | 能力切片 | 跨專案可能重用的工作流（例如圖解產生、文章發佈、PR 流程） |
為什麼這樣分？因為這三件事的「變動頻率」和「適用範圍」差很多。行為紀律跨專案都通用、變動最慢，放在使用者層級寫一次就好；專案技術細節跟著 repo 走、會隨開發演進，跟 source code 一起 commit 進 git；能力切片是「想做這件事時才用到」的工作流，拆成 skill 比塞進 CLAUDE.md 更乾淨，這個取捨在 Claude Code Skills 教學 那篇有更完整的討論。
實務上拿這個分層套到一個新專案，最小可行的 CLAUDE.md 大概長這樣：
# 專案名稱
一段話講這個專案做什麼。
## 結構
- `src/` — 主要程式碼
- `tests/` — 測試
- `scripts/` — 雜項工具
## 跑起來
```bash
# 開發環境
npm install && npm run dev # 預設 port 5173
```
## 設計決策
- **資料層用 SQLite**：產品早期不需要 Postgres，部署簡單優先
- **不寫 ORM**：原生 SQL 比 Drizzle 更好讀，效能也夠
## 踩過的坑
- macOS 上 sharp 套件第一次 build 會卡 20 秒，是 prebuild binary 抓不到，正常
- 環境變數 `NODE_OPTIONS` 在 zsh 與 fish 行為不同，CI 用 bash
## 還沒做
- 多人協作的 conflict resolution
- 匯出成 PDF
就這樣，五段、不到一百行，但下次 Claude Code 一進來就能跟上脈絡。隨著專案成長慢慢加細節即可，不必一開始就寫完美。
CLAUDE.md 沒有正確答案，但有原則
整理一下這篇要說的：
- 網路上「Karpathy 的 CLAUDE.md」實際指兩份檔案——他本人提交的
llm-council/CLAUDE.md（技術筆記風）與社群整理的 4 條原則（行為守則風）。混為一談會看不出兩種思路的差別 - 技術筆記風適合放在每個專案的 CLAUDE.md，幫助 agent 快速跟上脈絡，重點是「處處解釋為什麼」
- 行為守則風適合放在使用者全域
~/.claude/CLAUDE.md，跨專案共用工作紀律。四條原則本質上是把資深工程師反射動作寫成明文，對 LLM 很有效因為它就是看 prompt 工作的 - 大部分專案值得分層寫：使用者層放紀律、專案層放技術知識、進階能力用 skills 切片
- CLAUDE.md 是隨專案演化的活文件，每一條規則都應該對應到一個踩過的具體情境，而不是抽象的「最佳實踐」清單
如果只能從這篇帶走一件事，建議是：停下複製貼上社群模板的衝動，先看一眼自己手邊的專案要解決什麼問題。是團隊裡 Claude 老是改太多檔案？那「Surgical Changes」這條原則對症下藥。是新 session 進來不知道哪個 port 已被佔用？那需要的不是行為守則、是 Karpathy 那種「Backend on 8001 NOT 8000」的技術筆記。15 萬 star 不代表這份檔案 fit 自己情境；它只是大家看到 Karpathy 名字按下 star 的副作用。
想更深入的話，建議直接讀兩個 repo：karpathy/llm-council 的 CLAUDE.md 與 multica-ai/andrej-karpathy-skills。一個半小時可以讀完兩份，再對照自己手邊 repo 的需要，自然會知道下一條規則該寫什麼。