CLAUDE.md 怎麼寫？

我曾經花一個下午，把 CLAUDE.md 寫成一份將近兩千字的規格書，從專案結構、命名規範到每個資料夾該放什麼，全塞進去。寫完很有成就感。

結果下一個 session，AI 照樣犯我寫過「不要犯」的錯。

後來我才搞懂一件反直覺的事：CLAUDE.md 不是寫越完整越好。寫太多，AI 反而越不聽你的。

接下來要講的，就是這份檔案該寫什麼、不該寫什麼。

它不是規格書，是給 AI 的入職手冊

先把這份檔案的位置擺對。

官方把它叫「持久指令檔」，每次你開一個新的 Claude Code session，它會被自動載入上下文。白話講，它是你交到 AI 手裡的那份入職手冊。

關鍵在「每次新 session」。你可能有印象，Claude 每次開新對話就像失憶，前面講過的規則全部歸零。你重複講同一句話：「用繁中、不要亂重構、先讀再改……」講到後來，你比較像在帶一個每天重新報到的實習生。

CLAUDE.md 解決的就是這件事。你把「我們這裡事情是這樣做的」寫一次，之後每個 session 它都先讀過再上工。

寫越完整，反而越沒用

這大概是整篇最反直覺的一段。

Anthropic 官方的建議是：單一個 CLAUDE.md，控制在 200 行以內。原因無他，寫太多會出問題。

一份針對 AI coding agent 的實證研究也看到類似狀況：在它們分析的專案裡，光「規則檔塞太多」（Context Bloat）這一項就佔了 42%。

規則太多，AI 反而抓不到重點，規則之間還會互相打架。

原因很實際：CLAUDE.md 會吃 AI 每次能讀的上下文額度。你塞越多，留給實際任務的額度就越少。規則越多，AI 也越容易挑錯條來遵守，或乾脆挑一條比較順的交差。

那到底什麼才值得寫進去？我用三個問題判斷，三個都「是」才寫：

1. 這是不是 AI 已經犯過、而且會再犯的錯？
2. 我是不是每個 session 都要重講一次？
3. 我是不是希望它一開工就先守住，而不是等我抓到再改？

其中一個不是，就別寫。留白本身，就是在告訴 AI 什麼才重要。

三個區塊就夠：風格、原則、個人化

知道寫什麼之後，來談怎麼分。我用三個區塊裝，清楚好維護。

互動風格

告訴 AI 怎麼跟你工作。像：不確定時先列假設，不要默默替你做決定；回覆先講結論再講理由；沒驗證前不要說「完成了」。

這塊投報率最高。它改變的不是某個功能，而是 AI 每一次回應的長相。

程式碼原則

你對它寫程式的硬規定。像：只做跟需求直接相關的最小改動、修 bug 先寫能重現問題的測試、沒明確要求不要亂新增依賴。

這塊一半放通用，也就是你的工程哲學；一半放專案，也就是這個 repo 的指令、禁改區。

個人化規則

那些你最容易被忽略、但最在意的小事。像：預設用繁體中文回覆、日期用絕對時間不要寫「明天」、給選項時要明確推薦一個。

這塊很多人覺得雞毛蒜皮，但它最常消除那種「AI 寫得沒錯，可是就不是我要的樣子」的摩擦。

每寫一條，我都會問自己：這條進去之後，AI 的行為會真的不一樣嗎？如果不會，就是寫爽的，就刪掉。

寫進去，不等於擋得住

這條觀念懂了，你的 CLAUDE.md 會成熟一點。

CLAUDE.md 是「提醒」，不是「門禁」。你寫了「不要讀 .env」「不要 git push」，AI 只是比較可能不做，並不是真的不能做。它本質上是一份行為建議，沒有強制力。

真的不能讓 AI 碰的東西，例如 secrets、付費 API、刪除、推送，要靠 permissions 跟 hooks 去硬擋。Claude Code 的權限黑名單寫進去，就真的擋得住。

寫在 CLAUDE.md 裡的東西，AI 只是比較會照做；要真的不讓它碰，鎖權限才是真的。

一個成熟的開發者不會把「請不要偷看客戶資料」寫進員工手冊就放心，他會把權限鎖好。AI 也一樣。

我自己的 CLAUDE.md 長怎樣

下面是我自己在用的幾條規則，這裡放的是簡化版：

## 工作方式
- 動手改之前，先讀目標檔案、相鄰實作、跟相關測試。
- 不確定時，列出假設，不要默默替我做架構決策。
- 沒有驗證之前，不要宣稱完成。

## 修改原則
- 只做跟需求直接相關的最小改動，不要順手重構無關區塊。
- 修 bug 先寫重現問題的測試，再改，再驗證。
- 未經我同意，不要刪任何筆記或檔案。

你會發現：每條都很短、很具體。沒有半條是「請寫出高品質的程式碼」這種說了等於沒說的話。

每次 AI 又犯了一個新錯，我才加一條。它是活的文件，會隨著犯錯成長。

可以直接抄的範本

還沒開始寫的話，下面這份通用版可以直接拿去改。我會把它拆成幾個更清楚的區塊：先講專案背景，再講工作方式、修改原則、驗證方式，最後才放底線與個人偏好。

# CLAUDE.md

## 專案背景
- 這是一個 [專案類型]。
- 主要技術是 [框架 / 語言 / 工具]。
- 目前最重要的目標是 [例如：穩定上線、修 bug、整理內容、快速做原型]。

## 互動風格
- 預設用繁體中文回覆，程式碼、指令與專有名詞保留原文。
- 先講結論，再講理由、變更內容與風險。
- 不確定時先列出假設，不要默默替我做決定。
- 如果有多個做法，請列出取捨，並明確推薦一個方案。

## 寫程式前
- 動手前先讀目標檔案、相鄰實作、匯入項目與相關測試。
- 先找專案既有模式：命名、資料流、錯誤處理、樣式與工具。
- 如果上下文不足以安全修改，先說缺什麼，不要用猜的補空白。

## 修改原則
- 只做跟需求直接相關的最小改動。
- 不要順手重構無關區塊，不要主動新增沒被要求的功能。
- 不要在沒有說明的情況下新增 dependency。
- 如果能用現有工具或標準 API 解決，就不要換一套。

## 驗證方式
- 修改後執行專案既有檢查，例如 build、test、lint 或格式檢查。
- 沒有驗證之前，不要宣稱完成。
- 如果無法驗證，清楚說明原因與剩下的風險。

## 底線（先停下來問我）
- 要讀 secrets、.env、憑證或私人資料。
- 要刪檔案、改名、或大規模搬移。
- 要 git push、release、部署，或任何不可逆操作。

## 個人偏好
- 不要把簡單任務做成大型架構。
- 不要用太像文件範本的語氣回覆。
- 對 UI 修改，要優先考慮實際畫面、留白、字級與手機版。

存成 CLAUDE.md，放進專案根目錄。下一個 session，你就會感覺到差別。

Karpathy 的 10 條 CLAUDE 軍規

Andrej Karpathy 是 AI 工程圈很有影響力的人之一。史丹佛電腦視覺博士，OpenAI 創始成員之一，曾任 Tesla AI 總監，也長期分享 AI 工程與教育相關觀點。

我在 X 上看到一份被稱為 Karpathy 風格的 CLAUDE.md 規則，整理後很適合拿來當檢查清單：

結語：你不是在寫提示詞，是在寫入職手冊

回到一開始那句。

很多人以為自己在「寫提示詞」，但過了某個階段之後，你在做的已經不是把單次指令寫好，而是在帶一個會長期合作的 AI 夥伴。

好的入職手冊從來不是把公司規定全倒進去。它只要講清楚兩件事：什麼別自作主張、哪些驗證不能省。

把 CLAUDE.md 寫短、寫準，寫成你真的被打過的教訓。剩下的，交給那個終於不用你每天重教的 AI。