一個會被遵循的 CLAUDE.md
這裡有一個幾乎每個人都會掉進去的陷阱:您的 CLAUDE.md 檔案會一直變大。您遇到一個問題,就加一條規則。又遇到一個,再加一條。沒多久您就有了一個龐大的檔案,而 Claude 開始忽略其中的部分內容。這不是 Claude 的錯誤,而是這個檔案運作的方式。
關鍵要理解的是,CLAUDE.md 並非強制執行的設定。它是指引。每一行都在與其他每一行競爭 Claude 的注意力。檔案越長,它與自身的競爭就越激烈,Claude 遵循任何單一規則的可靠性也就越低。所以目標不是把所有事情都寫下來,而是讓檔案保持精簡。檔案越精簡,Claude 實際遵循的比例就越高。
首先,確認 CLAUDE.md 是否真的是對的工具
在您寫下一條規則之前,先問問它是否真的該放進 CLAUDE.md。有些規則是指引,有些規則則是絕不能跨越的硬性界線。這是兩種不同的任務。
以「絕不要 push 到 main」這種規則為例。如果您把它放進 CLAUDE.md,您只是在期望 Claude 會讀到它並遵守它。大多數時候它確實會。但對於這麼危險的事情,「大多數時候」還不夠好。這種硬性規則應該放進 pre-tool-use hook 裡。
這個差異很重要。hook 是在 Claude 執行動作之前運作的程式碼,而且它真的可以阻擋該動作。所以即使 Claude 真的嘗試 push 到 main,hook 也會把它擋下來。那才是真正的強制執行,而不是禮貌的請求。把您的硬性規則搬到 hook 裡,讓 CLAUDE.md 負責比較軟性的慣例就好。
四個位置
CLAUDE.md 不只是放在您專案裡的單一檔案。它可以存在於四個位置,而 Claude 在啟動時會把它們全部一起載入。沒有任何內容會被遺漏,它們會疊加在一起。
以下是每一個位置的用途:
- Managed policy(受管理政策)——由您的平台團隊控制的組織層級檔案。您無法排除它,所以組織政策永遠會生效。
- User(使用者)——跟著您在機器上每個專案的個人偏好設定。
- Project(專案)——與您的團隊共享、簽入儲存庫的檔案。
- Local(本機)——被 git 忽略。僅限這一個儲存庫的個人筆記。
最後那個「local」很容易被忽略,但其實非常好用。假設您正在自己的分支上做重構,想讓 Claude 在工作時記住一些架構上的決策。這不該放進共享的專案檔案裡,因為那會影響整個團隊。它應該放進 local,只屬於您在這個儲存庫裡使用。
用匯入拆分大型檔案
當您的專案檔案開始變得很長時,您可以使用「檔案路徑匯入」語法把它拆成幾個部分。與其寫成一大片文字牆,您可以指向其他檔案:
@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md這對整理來說非常好用。但您要清楚知道它到底帶給您什麼,因為很容易誤解。當 Claude 啟動時,它會把這些被匯入的檔案原地展開,就在您引用它們的位置。所以匯入確實能幫您整理得更整齊,但所有內容仍然會在一開始全部載入。它們並不會減少 Claude 必須讀取的上下文量。使用匯入是為了整理,而不是為了縮減載入量。
措辭才是讓規則發揮作用的關鍵
一旦您決定某條規則該放進 CLAUDE.md,Claude 是否真的會遵守它,取決於您怎麼措辭。大多數規則失敗的原因是它們太模糊。以下教您怎麼修正這一點。
要具體、要可檢驗
不要寫「遵循最佳實務」。您自己真的知道那到底是什麼意思嗎?如果您自己都無法檢驗它是否被遵守了,Claude 也無法。比較以下兩個例子:
- 模糊:「API 路由要遵循最佳實務。」
- 具體:「把新的 API 路由放進
src/api/handlers,每個檔案一個。」
第二個是明確的。您可以看著結果立刻判斷它有沒有做對。這就是每條規則都該達到的標準。
說出替代方案,不要只是禁止
當您告訴 Claude 不要做某件事時,要說明該做什麼來取代它。否則您就留下了一扇敞開的門。
- 留下空間:「不要使用 default exports。」 好,那然後呢?
- 把門關上:「使用 named exports,而不是 default exports。」
第二個版本說出了替代方案,所以沒有留下任何可以被誤解的空間。
用平實的語氣,而不是用吼的
像「IMPORTANT」和「YOU MUST」這類字眼,很少能挽救一條 Claude 一再忽略的規則。目前的模型會遵循措辭平實的一行字,而堆疊強調語氣大多只會讓 Claude 過度套用這條規則。如果一條規則絕不能妥協,那就把它做成 hook。如果它一直被忽略,那就把檔案縮短。
讓檔案持續接受修訂
您的 CLAUDE.md 檔案永遠不會「完成」。把它當作持續被編輯的活程式碼來對待。
當 Claude 做錯事時,不要只是嘆口氣然後自己手動修正。把它當作是針對您 CLAUDE.md 檔案的一份錯誤回報。您甚至可以直接告訴 Claude:「把那個加進 CLAUDE.md 檔案裡」,它就會幫您寫出那條規則。這樣一來,每次出錯,這個檔案就會變得更好一點。
總結
把您的 CLAUDE.md 當作正式上線的程式碼來對待。如果您無法為某一行說出理由,就刪掉它。要讓檔案保持精簡且容易被遵循:
- 把硬性規則搬到 hook 裡,在那裡它們才會真正被強制執行。
- 用匯入來整理冗長的檔案(但記得它們不會減少上下文量)。
- 讓每條規則都具體且可檢驗,並且說出替代方案。
- 用平實的措辭,而不是堆疊強調語氣。
- 每當 Claude 做錯事時,就持續修訂這份檔案。
整個概念其實很簡單。檔案越精簡,Claude 遵循的比例就越高。