行為約束以最小檔案集交付，不包含執行期程式碼。
此 repo 的可交付物是一組行為約束，不含執行期程式碼。GitHub metadata 描述為「一個單一 CLAUDE.md，用來改善 Claude Code 行為」，repository tree 只有 CLAUDE.md、CURSOR.md、EXAMPLES.md、README、.claude-plugin、.cursor/rules 與 skills/karpathy-guidelines/SKILL.md。
此 repo 將 coding agent 常犯的四類錯誤轉為可安裝的政策層。當 agent 進入專案時，規範要求它先暴露假設、保持簡單、做 surgical changes、定義可驗證成功條件。
Codex 使用者可將此內容轉譯為 AGENTS.md 或 repo-local agent instructions，但不宜機械照抄。Claude Code、Cursor、Codex 的 instruction merge 規則不同；需要保留的是四個行為原則，而非特定檔名。
四個原則對應四種 agent 常見失誤類型。
先思考再寫碼
不要默默選一種解讀就開始改。模糊時先列假設、指出多種可能、必要時追問，尤其是涉及資料範圍、權限、UX 或安全邊界的任務。
先用最小解
不為單次需求創造抽象，不加未被要求的彈性，不寫假想場景的 error handling。若 200 行可以是 50 行，就先縮回來。
只碰必要範圍
不要順手重排、格式化、改註解或重構鄰近程式。若任務外發現壞味道，記錄或提醒；除非被要求，不要擅自刪。
把任務變成可驗證目標
不要只執行「修好它」。要把需求轉為測試、重現步驟、檢查命令與完成條件，讓 agent 能自己 loop 到證據成立。
同一份準則提供三種安裝格式：Claude plugin、Cursor rule、reusable skill。
README 的主要路徑是 Claude Code plugin marketplace；per-project 路徑則是下載或 append CLAUDE.md。Cursor 使用 committed project rule：.cursor/rules/karpathy-guidelines.mdc，並設定 alwaysApply: true。可複用技能位於 skills/karpathy-guidelines/SKILL.md。
multica-ai/andrej-karpathy-skills, while README install snippets still use the older forrestchang/andrej-karpathy-skills path. Treat this as an upstream packaging detail to verify before copying install commands into production documentation.
repo 檔案集小，跨工具同步一致性是主要維護負擔。
| 檔案 | 目標工具 | 用途 |
|---|---|---|
CLAUDE.md | Claude Code / generic root instructions | 核心四原則，最容易複製到任意專案。 |
.claude-plugin/plugin.json | Claude Code plugin | 宣告 plugin metadata、MIT、keywords 與 skill path。 |
.cursor/rules/karpathy-guidelines.mdc | Cursor | 同一份準則，frontmatter 設 alwaysApply: true。 |
skills/karpathy-guidelines/SKILL.md | Personal skill systems | 可複製或 symlink 到個人 skills 目錄。 |
EXAMPLES.md | Human review | 用反例與修正案例展示四原則對應的錯誤型態。 |
CURSOR.md 特別提醒貢獻者：改四原則時要同步 CLAUDE.md、Cursor rule 與 SKILL.md。這是此 repo 最容易出錯的地方，因為內容重複分布在多個工具格式中。
EXAMPLES.md 把抽象原則轉成可辨識的 diff 味道。
資料匯出不是一句話需求
範例指出 agent 會默認匯出所有使用者、選定格式與欄位。正確模式是先問資料範圍、下載方式、敏感欄位與容量。
快有三種意思
回應時間、吞吐量與 perceived speed 是不同問題。agent 應先拆解 tradeoff，而不是同時加 cache、index 與 async。
折扣計算不需要策略框架
如果需求只是百分比折扣，一個函式就夠。只有真的出現多種折扣型態時，才值得抽象。
修 email bug 不等於重寫 validator
典型錯誤是修一個 crash，順便改註解、username 規則、email 判斷與格式。這正是 surgical changes 要防的事。
在 Codex 裡用它, 應該轉成 AGENTS.md 行為規範。
這份 repo 的 CLAUDE.md 可以直接啟發 Codex，但 Codex CLI 更自然的放置點是 root AGENTS.md 或特定子目錄的 AGENTS.md。轉譯時保留四原則即可，不需要保留 Claude Code plugin 指令。
建議在 Codex 版本補充三點：如何處理 dirty worktree、何時使用 rg 與測試命令、final response 必須列出驗證結果。Karpathy 準則提供通用行為框架，專案的工程慣例需另行補充。
這份規範會降低錯誤, 也會降低某些情境的速度。
- 不要把「先問」變成逃避執行。 對明確的小修，直接做；對有風險的模糊需求，再追問。
- 不要用 simplicity 壓掉必要架構。 最小解不是臨時 hack；它仍然要符合現有邊界與測試要求。
- 不要把 surgical changes 理解成不能清理。 如果你的改動製造 unused import 或 orphan code，就要清掉自己的痕跡。
- 不要只寫原則, 不寫驗證命令。 Goal-driven execution 需要具體檢查：test、lint、typecheck、build、manual route check。
- 多工具同步需要 review。 Claude、Cursor、Skill 三份內容一旦不同步，使用者會得到不一致行為。
將此準則作為團隊 agent policy 的起點文件。
先合併到專案規範
不要單獨丟進 repo。把四原則嵌入既有 stack、測試、review、部署慣例。
保留例外規則
明確寫出 trivial one-liner、純文案修正、只讀查詢等不需要完整澄清流程的場景。
加上 dirty worktree policy
Codex/Claude 在真實 repo 裡最常踩到使用者未提交變更；這部分要比原始 CLAUDE.md 更具體。
為 PR review 設完成門檻
把「驗證成功」定義成命令與輸出，而不是 agent 自稱完成。
定期檢查 diff 品質
看這份 policy 是否真的減少 drive-by refactor、過度抽象與未驗證完成聲明。