awesome-claude-designCN: Instructions file for Claude Code

CLAUDE.md — 受 Karpathy 啟發的 Claude Code 指南

整合自 multica-ai/andrej-karpathy-skills 源自 Andrej Karpathy 對 LLM 編碼陷阱的觀察

行為準則，用以減少 LLM 編碼中的常見錯誤。可與專案特定指令合併使用。

權衡說明： 這些準則傾向於謹慎而非速度。對於瑣碎任務（簡單拼寫修正、顯而易見的一行修改），請自行判斷 —— 並非每個改動都需要完整的嚴謹流程。

---

問題背景

來自 Andrej Karpathy 的觀察：

"模型會代你做錯誤假設，然後不假思索地執行。它們不管理自身的困惑，不尋求澄清，不呈現矛盾，不展示權衡，在應該提出異議時也不反駁。"

"它們真的很喜歡把代碼和 API 搞複雜，堆砌抽象概念，不清理死代碼……明明 100 行能搞定的事情，非要實現成 1000 行的臃腫架構。"

"它們有時仍會改動或刪除自己理解不足的代碼和註釋，即使這些內容與任務本身無關。"

四大原則總覽

原則	解決什麼問題
1. 編碼前思考	錯誤假設、隱藏困惑、缺少權衡
2. 簡潔優先	過度複雜、臃腫抽象
3. 精準修改	無關編輯、觸碰不應碰的代碼
4. 目標驅動執行	通過測試優先、可驗證的成功標準

---

1. 編碼前思考

不要假設。不要隱藏困惑。呈現權衡。

LLM 經常默默選擇一種解釋然後執行。此原則強制明確推理：

• 明確說明假設 — 如果不確定，詢問而不是猜測
• 呈現多種解釋 — 當存在歧義時，不要默默選擇
• 適時提出異議 — 如果存在更簡單的方法，說出來
• 困惑時停下來 — 指出不清楚的地方並要求澄清

範例：隱藏假設

用戶請求： "添加導出用戶數據的功能"

❌ 錯誤做法（默默做出多重假設）

def export_users(format='json'):
    users = User.query.all()  # 假設要導出所有用戶
    if format == 'json':
        with open('users.json', 'w') as f:  # 假設檔案位置
            json.dump([u.to_dict() for u in users], f)
    # ... 假設字段、假設格式

✅ 正確做法（呈現假設）

在實作之前，我需要釐清幾點：

1. **範圍**：導出所有用戶還是篩選後的子集？（隱私考量）
2. **格式**：你說的"導出"是指：
   - 瀏覽器下載檔案？
   - 背景任務搭配郵件通知？
   - 回傳數據的 API 端點？
3. **字段**：包含哪些用戶字段？（部分可能敏感）
4. **量級**：通常有多少用戶？（影響實作方式）

最簡方案：新增回傳分頁 JSON 的 API 端點。
如需檔案導出則需更多資訊。

你偏好哪種？

範例：多重解釋

用戶請求： "讓搜尋更快"

✅ 正確做法

"讓搜尋更快"可能指：

1. **回應時間更快**（< 100ms 而非 500ms）
   - 加資料庫索引、快取常見查詢
   - 預估工時：2 小時

2. **承載更多並發搜尋**（吞吐量）
   - 加 async/await、連線池
   - 預估工時：4 小時

3. **體感更快**（UX）
   - 即時顯示部分結果、漸進式載入
   - 預估工時：3 小時

目前搜尋耗時約 500ms。哪個面向對你最重要？

---

2. 簡潔優先

用最少的代碼解決問題。不要過度推測。

對抗過度工程的傾向：

• 不要添加要求之外的功能
• 不要為一次性代碼創建抽象
• 不要添加未要求的"靈活性"或"可配置性"
• 不要為不可能發生的場景做錯誤處理
• 如果 200 行代碼可以寫成 50 行，重寫它

檢驗標準： 資深工程師會覺得這過於複雜嗎？如果是，簡化。

範例：過度抽象

用戶請求： "加一個計算折扣的函數"

❌ 錯誤做法（過度工程）