使用 Claude Code 時，我最近越來越覺得重要的是 CLAUDE.md 的運用。
Claude Code 非常強大，但在既有程式碼庫中長時間運作時，容易出現以下問題。
擅自重構
連不相關的檔案也一起修改
產生巨大的 diff
過度抽象化
把模糊的需求自行解讀後實作這與其說是「AI 能力不足」，不如說是因為沒有對 AI Coding Agent 設下明確的行為約束。
因此可以參考的是 GitHub 上超過 16 萬星的 multica-ai/andrej-karpathy-skills。
更精確地說，獲得星號的並不是單獨的 CLAUDE.md 檔案，而是這個儲存庫。不過，這個儲存庫的核心正是「用來改善 Claude Code 行為的一個單一 CLAUDE.md」。
也就是說，值得注意的地方在於：受到矚目的不是龐大的工具，而是整理 AI Coding Agent 行為原則的文件。
CLAUDE.md 是什麼
CLAUDE.md 是一個會被載入到 Claude Code 中的永久指示檔。
官方文件也將 CLAUDE.md 說明為用來提供 Claude 永久性脈絡的指示。
簡單來說，它就像是給 Claude Code 用的 README。
如果給人看的 README 是在說明「這個專案怎麼使用」，那麼 CLAUDE.md 說明的就是「Claude Code 在這個專案裡應該怎麼行動」。
CLAUDE.md 不是強制設定，而是作為脈絡被載入。
它不是寫了就一定會遵守的魔法檔案。
也因此，比起冗長而模糊的描述，寫得精簡且具體反而更有效。
為什麼 CLAUDE.md 很重要
AI Coding Agent 的問題，早就不是「能不能寫程式碼」。
現在的問題已經進入下一個階段。
能不能安全地長時間運作
會不會破壞既有設計
能不能產出容易審查的 diff
會不會做出人類沒有意圖的變更Claude Code 可以讀取檔案、編輯程式碼、執行命令。
這很方便，但反過來說，如果行為約束太弱，它就很容易「自以為是在幫忙」而做出多餘的修改。
尤其在業務程式碼中，與其說是 AI 生成的程式碼本身危險，不如說是它去動到原本不該碰的地方更危險。
andrej-karpathy-skills 的核心思想
andrej-karpathy-skills 的 CLAUDE.md，是為了抑制 Claude Code 的典型失敗而設計的行為原則。
這個儲存庫的特色是，針對 Andrej Karpathy 所指出的 LLM 寫程式典型失敗模式——例如擅自加前提、過度複雜化、連不相關的程式碼都去碰——整理成 4 個原則。
核心就是以下四項。
Think Before Coding
Simplicity First
Surgical Changes
Goal-Driven Execution各自的意思都很單純。
Think Before Coding
意思是在實作前先思考。
Claude Code 遇到模糊需求時，常常會自行解讀後直接往下做。
在人類會判斷「這裡應該先確認一下」的場景，AI 卻很容易先加上一個看似合理的前提就開始實作。
因此，在實作前讓它明確說出以下內容很重要。
要達成什麼
要修改哪些檔案
要基於什麼前提進行
有哪些模糊不清的地方尤其在既有程式碼中，比起「看起來合理的實作」，「符合既有設計意圖的實作」更重要。
Simplicity First
意思是以最小必要範圍進行實作。
AI 若放著不管，常常會過度泛化，或是根據未來可能的擴充來做抽象化。
但在業務程式碼中，「未來可能會用到的抽象化」有時反而會變成負債。
例如，明明只是要新增一個簡單的驗證，卻開始建立新的共用類別或設定物件，就是典型案例。
Simplicity First 就是用來抑制這種過度設計的規則。
不要新增未被要求的功能
不要把只會用一次的東西抽象化
配合既有寫法
即使可以做得很複雜，也要先用最簡單的方式解決只要讓 Claude Code 持續意識到這個原則，diff 的雜訊就會明顯減少。
Surgical Changes
意思是只修改必要的地方。
我個人認為，這是最重要的一項。
Claude Code 其中一個危險的行為就是「順手修正」。
明明只要求修 bug，卻可能連周邊命名、註解、格式、舊程式碼都一起改掉。
表面上看起來很貼心，但從審查者的角度來看，與原始修正無關的差分混在一起，會讓風險所在變得難以辨識。
Surgical Changes 會像這樣加上限制。
只動與需求直接相關的檔案
不要做不相關的重構
不要擅自更改既有註解或格式
即使發現未使用的程式碼，只要沒被要求也不要刪除如果要在業務中使用 AI Coding Agent，我認為這個原則是必須的。
Goal-Driven Execution
意思是把工作從「指示」轉換成「可驗證的目標」。
例如，與其只這樣要求，
修復這個 bug不如改成這樣會更穩定。
新增一個可以重現這個 bug 的測試，並修正到該測試可以通過只要有明確的成功條件，AI 的表現就會強很多。
相反地，如果成功條件很模糊，它就會憑感覺實作。
在交給 Claude Code 時，最好把需求整理成以下形式。
修正對象
預期結果
確認方法
可修改範圍
不可修改範圍如此一來，Claude Code 就不只是單純的程式碼生成工具，而是更容易作為一個會執行驗證迴圈的代理程式來使用。
plugin 和 CLAUDE.md 的差異
這個儲存庫也提供了以 Claude Code plugin 方式導入的方法。
參考：andrej-karpathy-skills README
這裡很容易混淆的是 plugin 和 CLAUDE.md 的角色。
我會這樣整理：
plugin / skills = 能力追加
CLAUDE.md = 行為控制plugin 或 skills 是用來替 Claude Code 增加特定作業流程或知識。
另一方面，CLAUDE.md 是用來控制 Claude Code 應該如何表現。
也就是說，只裝 skills 並不代表 Claude Code 的行為就會變安全。
相反地，能力變多了，如果約束不夠，失控的範圍也會變大。
因此，在實務上以下這種組合最有力：
用 CLAUDE.md 固定行為原則
用 skills / plugin 擴充作業能力為什麼要放進全域 CLAUDE.md
CLAUDE.md 雖然可以放在每個專案底下，但如果是所有專案都共通想套用的行為原則，放在全域會更方便。
在 Claude Code 中，可以把 CLAUDE.md 放在下列位置，作為使用者層級的指示。
~/.claude/CLAUDE.md官方文件也將使用者指示的範圍說明為 ~/.claude/CLAUDE.md。
適合放在全域的，是不依賴專案的原則。
例如：
不要憑猜測實作
保持最小 diff
不要碰無關檔案
尊重既有設計
不要做不必要的重構
不要自行新增新的依賴以下這些內容就不適合放在全域：
- 特定專案的建置指令
- API 規格
- 目錄結構
- 分支流程
- iOS 或 React Native 等個別規則
這些比較適合寫在專案根目錄下的 CLAUDE.md。
如果混在全域裡，Claude Code 可能會在別的專案也用同樣的前提行動。
建議的結構
我個人覺得，以下這種結構最好用。
~/.claude/
├── CLAUDE.md
├── settings.json
├── skills/
└── commands/各專案內則視需要放這樣的檔案。
project/
└── CLAUDE.md角色要明確分開。
全域 CLAUDE.md
所有專案共通的行為原則
專案 CLAUDE.md
該儲存庫特有的規則
skills / plugin
可重複使用的作業流程與專業知識
commands
常用的固定任務這樣分離之後，Claude Code 的行為會更穩定。
複製到全域的步驟
在 macOS 上，先建立 Claude Code 用的目錄。
mkdir -p ~/.claude接著，把 andrej-karpathy-skills 的 CLAUDE.md 複製到全域。
curl -L \
https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md \
-o ~/.claude/CLAUDE.md確認內容。
cat ~/.claude/CLAUDE.md這樣就會作為 Claude Code 的使用者共通指示被載入。
如果 ~/.claude/CLAUDE.md 已經存在，覆蓋前務必要先備份。
全域指示會影響所有專案，萬一消失會相當麻煩。
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak如果想要和既有內容合併，不要直接覆蓋，先另存新檔再確認。
curl -L \
https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md \
-o ~/.claude/CLAUDE.karpathy.md之後再和自己的既有規則整合。
如果是我會追加的規則
直接使用 Karpathy 風格的 CLAUDE.md 就已經很有效了，但如果是在業務程式碼中使用，我覺得也可以再追加以下規則。
## Additional Rules
- Prefer minimal diffs.
- Avoid unnecessary refactors.
- Preserve existing architecture unless explicitly requested.
- Do not modify unrelated files.
- Ask before introducing new dependencies.
- Do not change public API behavior unless required by the task.
- Always explain verification steps after implementation.其中 Do not modify unrelated files 特別強。
對 AI Coding Agent 來說，不做無關修改比人類想像的還要重要得多。
使用時的注意事項
CLAUDE.md 很方便，但不是萬能的。
官方文件也說明了，Claude 對 CLAUDE.md 的處理方式是把它當作脈絡，而不是強制設定。
也就是說，寫了不代表一定會遵守。
因此，在實務上比較合理的做法是這樣：
用 CLAUDE.md 固定基本方針
重要工作時，也在 prompt 端重新指定約束
在大幅修改前，一定先讓它提出計畫
先確認 diff，再繼續下一步尤其是重要修正時，一開始就這樣指示會更穩定。
在實作前，請先說明修改目標檔案、實作方針與驗證方法。
不要修改無關檔案。光是這樣，就能大幅抑制 AI 失控。
總結
使用 Claude Code 時，重要的不只是「讓 AI 寫程式碼」。
接下來更重要的是，如何安全地運用 AI Coding Agent。
andrej-karpathy-skills 之所以能超過 16 萬星，我認為正是因為這個問題意識打中了許多工程師的痛點。
AI 的能力未來還會持續提升。
但能力越強，約束設計也越重要。
如果你真的要認真使用 Claude Code，那麼先整理 CLAUDE.md 的價值非常高。
尤其在既有程式碼庫中，光是加入以下四項就很值得。
Think Before Coding
Simplicity First
Surgical Changes
Goal-Driven Execution與其說是為了提升 Claude Code 的品質，不如說 CLAUDE.md 是安全使用 Claude Code 的基礎。
後續文章在這裡
這篇文章整理了可從 andrej-karpathy-skills 的 CLAUDE.md 學到的基本思想。
在後續文章中，為了讓 Claude Code 在實務上更安全，我將只聚焦介紹 3 個想加入 CLAUDE.md 的安全運用規則。
- 不要對沒有讀過的程式碼自行推測
- 如果無法驗證，就提供理由與手動確認步驟
- 禁止擅自進行 Git 操作或破壞性操作
一起閱讀的話，可以更進一步強化 Claude Code 的運用規則，使其更符合實務需求。
▶ 後續文章：想加進 andrej-karpathy-skills 的 CLAUDE.md 裡，Claude Code 安全運用規則 3 選
參考
GitHub - multica-ai/andrej-karpathy-skills
andrej-karpathy-skills / CLAUDE.md
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
