Skills Atlas · Karpathy CLAUDE.md 使用說明書
forrestchang / andrej-karpathy-skills 是把 Andrej Karpathy 對 LLM 編碼盲點的觀察，萃取成一份單一 CLAUDE.md 的工程紀律檔。它不靠提示詞工程，而是把「擅自假設、過度抽象、留下死碼、邊改邊重構」這四個慣性錯誤，轉換成可驗證的成功標準與確定性的迴圈條件 — 讓 Claude Code、Cursor 以同一份規範運作。
CLAUDE.md。Karpathy 的觀察點出三個事實：模型會替你做錯的假設、會把簡單問題寫得過度複雜、會偷偷改掉它沒讀懂的程式碼。Forrest Chang 用一份檔案把這三件事，連同對策，寫進 Claude 的工作模式。
大多數 CLAUDE.md 都是寫給人看的風格指南。這份不是 — 它寫的是「禁止做什麼」與「在哪些條件下停下來」。例如 Surgical Changes 直接禁止順手改 adjacent code，Simplicity First 設下「200 行能寫成 50 行就重寫」的硬門檻。
Karpathy 的關鍵洞察是：「LLMs are exceptionally good at looping until they meet specific goals.」這份檔案把它落實成 Goal-Driven Execution — 「修這個 bug」轉換成「先寫一個能重現問題的測試，再讓它通過」。模型不需要更多話，需要更明確的成功條件。
同一份內容，既能以 Claude Code Plugin 全域註冊，也能 curl 成 per-project CLAUDE.md，還預先打包了 .cursor/rules/karpathy-guidelines.mdc。一份規範跨工具運作，是這份倉庫真正的工程貢獻。
每一條原則都針對 LLM 一個系統性誤差 — 假設不檢查、過度抽象、無關修改、目標模糊 — 以「禁止做什麼」與「在哪裡停下」明確界定。
Don't assume. Don't hide confusion. Surface tradeoffs.
針對 Karpathy 點名的「模型替你做錯誤假設然後一路寫下去」。要求模型在動工前 — 明確列出假設、提出多種詮釋讓你選、遇到更簡單的解法主動 push back、遇到不確定就停下來問。例如收到「加快搜尋」這種模糊需求時，先列出三種詮釋（回應時間／吞吐量／感知速度）與各自工時，再請使用者裁示。
Minimum code that solves the problem. Nothing speculative.
禁止「為了未來彈性而做的抽象」、禁止「為不可能發生的錯誤情境寫處理」。範例：當需求只是「算折扣」，不要動用 Strategy pattern + 抽象類別 + enum + dataclass — 一個 def calculate_discount(amount, percent) 就夠了。判準是「資深工程師會不會說這 over-engineered？」。
Touch only what you must. Clean up only your own mess.
禁止「順手改 adjacent code」、禁止「把單引號改雙引號」、禁止「補 docstring」這類 drive-by 改動。即使看到無關的死碼也要 提報而不刪除。判準是「每一行 diff 都要能直接追到使用者的需求」 — 讓 PR 評審變成可預期的事。
Define success criteria. Loop until verified.
這條是 Karpathy 觀察的核心 — 「LLMs are exceptionally good at looping until they meet specific goals.」 把祈使句改成可驗證目標：「加驗證」→「為非法輸入寫測試，再讓它通過」；「修這個 bug」→「先寫一個能重現問題的測試，再讓它通過」。多步任務用 步驟 → verify: 檢查項 的格式列出，模型就能獨立迴圈推進。
Bias toward caution over speed.
這份 CLAUDE.md 設計為可合併 — 在原四條原則之後直接追加「Project-Specific Guidelines」段落，例如 Use TypeScript strict mode、All API endpoints must have tests。原作者也明示這份規範偏向謹慎：對顯然只是 typo 修正的小事，可自行判斷不必上滿全套紀律。
兩種主要部署方式，加上 Cursor 跨工具支援、既有 CLAUDE.md 的合併策略，以及如何驗證它確實在運作的觀察指標。
兩行斜線指令，所有專案立即生效
在 Claude Code 內先註冊 marketplace：/plugin marketplace add forrestchang/andrej-karpathy-skills，再執行 /plugin install andrej-karpathy-skills@karpathy-skills。安裝完成後，這份四原則紀律會在你打開任何專案時自動套用，免去每個 repo 都得 curl 一次 CLAUDE.md 的麻煩。
curl 直接放進專案根目錄適合單一 repo 想限定範圍套用的情境
在新專案根目錄執行 curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md。檔案會被 Claude Code 自動讀取為當前專案的指引；不影響其他專案，也方便 commit 進版控、跟團隊共用。
不覆蓋現有規範，疊加 Karpathy 紀律
如果專案已經有自己的 CLAUDE.md，使用 echo "" >> CLAUDE.md 加空行，再 curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md 把四條原則接在後面。原作明確設計成可合併，與專案特定規則不衝突。
repo 已預先打包 Cursor project rule
倉庫內建 .cursor/rules/karpathy-guidelines.mdc，clone 下來打開 Cursor 就生效；也提供 CURSOR.md 說明如何把同一份規則複製到其他專案。Claude Code 與 Cursor 共用同一份語意，避免在 IDE 之間切換時規則漂移。
沒有日誌、沒有後台 — 用 PR 形態判斷
原作者列出四個可觀察跡象：diff 裡只有被請求的修改、不會因為過度複雜而重寫、釐清問題出現在實作之前、PR 乾淨無 drive-by。這四個指標也是 Tenten 在客戶端把 Claude 接進 Shopify Plus / Webflow 工作流時，最常用來檢視「這份規範有沒有真的影響輸出」的清單。
這幾個模式都直接對應原 README / CLAUDE.md 已經寫明的條款，但常被使用者跳過。把它們刻意做出來，模型輸出品質會明顯升一階。
這是 Goal-Driven Execution 最值錢的小動作
原 CLAUDE.md 直接給了三組對照：「Add validation」→「Write tests for invalid inputs, then make them pass」；「Fix the bug」→「Write a test that reproduces it, then make it pass」；「Refactor X」→「Ensure tests pass before and after」。把指令寫成能寫成測試的句子，模型才有「完工條件」可以迴圈到底。
CLAUDE.md 給的標準格式
多步任務的標準寫法是 1. [Step] → verify: [check]。每個步驟自己有完工條件，模型可以一步一步推進並自行確認。沒有 verify 的計畫就是「make it work」 — 原文點名這種寫法會讓模型不斷回頭問你。
原作明示鼓勵的合併方式
README 給的範例是在四原則後另開 ## Project-Specific Guidelines 區段，例如 Use TypeScript strict mode、All API endpoints must have tests、Follow the existing error handling patterns in src/utils/errors.ts。原則層提供工程紀律，專案層提供技術選型 — 兩層各司其職。
Simplicity First 內建的判準
CLAUDE.md 直接寫明這個自檢句：「Would a senior engineer say this is overcomplicated? If yes, simplify.」 把這句寫進 PR 模板或 review checklist，比堆十條風格規定還有效。配合「If you write 200 lines and it could be 50, rewrite it」這條硬門檻使用。
取自倉庫 EXAMPLES.md，是四條原則在真實任務裡的「壞示範 vs 好示範」對照 — 拿來當入職教材、code review checklist 都很合用。
最常見也最危險的 LLM 慣性 — 偷偷擴大 PR 範圍
壞示範：使用者請修「空字串 email 會 crash」，模型同時改進整個驗證邏輯、補 docstring、加型別、調整空白。好示範：只改處理空 email 的那幾行，明確聲明「Only changed: The specific lines that fix empty email handling」。這條規則對接觸 production code 的團隊最關鍵 — 任何超出範圍的改動都要在 PR 描述裡額外揭露。
沒問清楚就動工，是 LLM 最大的失誤源
壞示範：模型自行假設範圍是全部使用者、特定檔案位置、預設欄位，然後寫一整支匯出。好示範：先回問四個關鍵點 — Scope?（哪些使用者）、Format?（CSV / JSON / Excel）、Fields?（哪些欄位）、Volume?（資料量是否需要分批）。把假設外顯為四個是非題，比直接寫 200 行匯出邏輯更高效。
「為了未來彈性」是過度抽象最常見的藉口
壞示範：「算商品折扣」被實作成 Strategy Pattern + 抽象基類 + Enum + Dataclass，外加可注入的折扣策略工廠。好示範：def calculate_discount(amount: float, percent: float)，三行解決，附上一行註解「等真的需要多種折扣策略時再抽象」。LLM 對「彈性」的偏好是訓練偏差 — 規範要明白禁止這種推測性設計。
把「修這個 bug」轉換成可驗證的迴圈
壞示範：模型一看到「排序有問題」就直接改 sort 邏輯，沒先確認問題到底是什麼。好示範：先寫一個能重現「非確定性排序行為」的測試 → 改用 stable sort → 跑測試確認修正 → 跑既有測試套件確認無迴歸。這是 Goal-Driven Execution 在 bug fix 場景的標準動作 — 沒有測試就沒有完工條件。
大功能拆小步驟，每步都帶 verify 條件
壞示範：模型一次把 Redis-backed 的限流系統做完並一個 PR 送上來。好示範：拆成四個離散步驟，每一步都有具體測試、可獨立部署。當 PR 有問題時，rollback 範圍是一個步驟而不是整個系統 — 這也是 Tenten 在處理電商遷移時，把 Headless 切換、金物流串接、Cache 策略 各自隔離部署的同一套思路。
Karpathy 對 LLM 編碼盲點的觀察在社群早就流傳，但把它寫成可執行單檔 — 並同時打通 Claude Code Plugin 與 Cursor — 的人就是 Forrest Chang。社群反應集中在三件事。
README 直接引用三段：「The models make wrong assumptions on your behalf and just run along with them without checking.」「They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code.」「They still sometimes change/remove comments and code they don't sufficiently understand.」這三段的對策，正是四大原則的 1、2、3 條。原 X 貼文 →
這份 repo 在 GitHub 趨勢追蹤站 Trendshift 上有獨立頁面 — 這通常意味著它在某段時間內進入了 GitHub 全站趨勢前列。對一份「只有一個 markdown 檔」的倉庫而言，這個熱度幾乎全部來自內容本身的可重用性，而非附帶的程式碼資產。Trendshift 頁面 →
社群已出現整篇拆解這份 CLAUDE.md 的文章 — 包括 antigravity.codes 的「Karpathy's CLAUDE.md Skills File: The Complete Guide」與 Medium 上 Kristopher Dunham 的「Andrej Karpathy's Fix for AI Coding Agents Gone Wrong」。當原始倉庫只是一個 markdown 檔還能引出長文評論，代表它在工程社群被當作典範文件而非工具來討論。antigravity.codes →
四條原則對所有人都受用，但「先從哪裡裝、怎麼跟既有規範整合」要看你是哪種角色。下面是 Tenten 在客戶端最常採取的四種起手式。
直接在 Claude Code 內 /plugin marketplace add forrestchang/andrej-karpathy-skills，再 /plugin install andrej-karpathy-skills@karpathy-skills。所有專案立刻共享同一份四原則紀律，不用每個 repo curl 一次 — 對自由接案的工程師最划算。
curl -o CLAUDE.md ... 後 commit 進 repo，所有團隊成員拉到的都是同一份。再附上一段 Project-Specific Guidelines（例如 strict mode、API 必含測試、錯誤處理規範）。新人 onboarding 不用再口頭交代「我們的 PR 風格」 — 規範本身會直接約束 AI 輸出。
倉庫已預打包 .cursor/rules/karpathy-guidelines.mdc。團隊內 Claude Code 與 Cursor 混用時，把這份檔案搬到專案的 .cursor/rules/ 即可 — Claude Code 讀 CLAUDE.md，Cursor 讀 .mdc，兩邊收到的工程紀律是同一份語意，避免規則漂移。
Tenten 在客戶端把這份 CLAUDE.md 當作「PR 是否能進主幹」的審核基準 — 配合 四個觀察指標（diff 範圍、是否 over-engineered、釐清問題在前、無 drive-by）建立 review checklist。讓 Claude 的輸出先通過 Karpathy 紀律，再進入 Shopify Plus / Webflow / Headless 的部署管線。
Tenten 是 AI-First 設計與技術顧問公司。我們把 Claude、MCP、Agentic Commerce 接進 Headless CMS、Webflow、Shopify Plus 的企業級交付 — 讓 CLAUDE.md 這層工程紀律，真正影響你的 PR 形態、code review 節奏、與正式上線的品質門檻。