行為約束以最小檔案集交付，不包含執行期程式碼。
此 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 常見失誤*類型。
Think
先思考再寫碼
不要默默選一種解讀就開始改。模糊時先列假設、指出多種可能、必要時追問，尤其是涉及資料範圍、權限、UX 或安全邊界的任務。
Simplicity
先用最小解
不為單次需求創造抽象，不加未被要求的彈性，不寫假想場景的 error handling。若 200 行可以是 50 行，就先縮回來。
Surgical
只碰必要範圍
不要順手重排、格式化、改註解或重構鄰近程式。若任務外發現壞味道，記錄或提醒；除非被要求，不要擅自刪。
Goals
把任務變成可驗證目標
不要只執行「修好它」。要把需求轉為測試、重現步驟、檢查命令與完成條件，讓 agent 能自己 loop 到證據成立。
Clarify
Choose Simple Path
Edit Narrowly
Verify
Report Evidence
同一份準則提供三種安裝格式：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。
# Claude Code plugin marketplace
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills# New project
curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# Existing project, append instead of overwrite
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.mdrepo 檔案集小，跨工具同步一致性是主要維護負擔。
| 檔案 | 目標工具 | 用途 |
|---|---|---|
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 味道。
Hidden Assumptions
資料匯出不是一句話需求
範例指出 agent 會默認匯出所有使用者、選定格式與欄位。正確模式是先問資料範圍、下載方式、敏感欄位與容量。
Search Faster
快有三種意思
回應時間、吞吐量與 perceived speed 是不同問題。agent 應先拆解 tradeoff，而不是同時加 cache、index 與 async。
Over-Abstraction
折扣計算不需要策略框架
如果需求只是百分比折扣，一個函式就夠。只有真的出現多種折扣型態時，才值得抽象。
Drive-by Refactor
修 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 準則提供通用行為框架，專案的工程慣例需另行補充。
# AGENTS.md adaptation outline
1. State assumptions before edits when scope is ambiguous.
2. Prefer the smallest change that satisfies the request.
3. Touch only files required by the task; preserve unrelated user changes.
4. Define success criteria and run the relevant verification commands.
5. Report what changed, what passed, and what was not run.這份規範會降低錯誤, 也會降低某些情境的速度。
將此準則作為團隊 agent policy 的起點文件。
先合併到專案規範
不要單獨丟進 repo。把四原則嵌入既有 stack、測試、review、部署慣例。
保留例外規則
明確寫出 trivial one-liner、純文案修正、只讀查詢等不需要完整澄清流程的場景。
加上 dirty worktree policy
Codex/Claude 在真實 repo 裡最常踩到使用者未提交變更；這部分要比原始 CLAUDE.md 更具體。
為 PR review 設完成門檻
把「驗證成功」定義成命令與輸出，而不是 agent 自稱完成。
定期檢查 diff 品質
看這份 policy 是否真的減少 drive-by refactor、過度抽象與未驗證完成聲明。