一份會被遵循的 CLAUDE.md
這裡有個幾乎每個人都會踩到的陷阱：您的 CLAUDE.md 檔案會不斷變大。您遇到一個問題，就加一條規則。又遇到另一個問題，再加一條規則。不久之後，您就有了一個龐大的檔案，而 Claude 開始忽略其中的部分內容。這不是 Claude 的錯誤。這是這個檔案運作方式的本質。
需要理解的關鍵是，CLAUDE.md 並不是強制執行的設定。它是指引。每一行都在與其他每一行競爭 Claude 的注意力。檔案越長，它與自身競爭的程度就越高，Claude 可靠遵循任何單一規則的程度就越低。所以目標不是把所有事情都寫下來。目標是讓檔案保持精簡。檔案越精簡，Claude 實際遵循的比例就越高。
首先，問問 CLAUDE.md 是否真的是合適的工具
在您寫下一條規則之前，先問問它是否真的該放進 CLAUDE.md。有些規則是指引，而有些規則是絕不能逾越的硬性界線。這是兩種不同的任務。
以「絕不推送到 main」這樣的規則為例。如果您把它放進 CLAUDE.md，您只是希望 Claude 讀到並遵守它。大多數時候它會遵守。但對於這麼危險的事情，「大多數時候」還不夠好。像這樣的硬性規則應該放在 pre-tool-use hook 裡。
這個差異很重要。hook 是在 Claude 執行動作之前運行的程式碼，它能夠真正阻止該動作。所以即使 Claude 真的嘗試推送到 main，hook 也會阻止它。那才是真正的強制執行，而不是禮貌的請求。把您的硬性規則移到 hook 裡，讓 CLAUDE.md 處理較軟性的慣例。
四個位置
CLAUDE.md 不只是放在您專案裡的單一檔案。它可以存在於四個地方，而 Claude 在啟動時會把它們全部一起載入。沒有任何內容會被遺漏，它們會疊加在一起。
以下是每一個的用途：
- 受管理的政策（Managed policy） — 由您的平台團隊控制的組織層級檔案。您無法排除它，所以組織政策永遠都會生效。
- 使用者（User） — 您個人的偏好設定，會跟隨您在這台機器上的每一個專案。
- 專案（Project） — 與您團隊共用的檔案，已納入版本庫。
- 本機（Local） — 被 git 忽略。僅供您個人在這個版本庫中使用的筆記。
最後那個「本機」，很容易被忽略，但其實非常好用。假設您正在自己的分支上進行重構，想讓 Claude 在工作時記住一些架構上的決定。這不該放進共用的專案檔案裡，因為那會影響您整個團隊。它應該放在本機檔案裡，只屬於您在這個版本庫中使用。
用 import 拆分大型檔案
當您的專案檔案開始變長時，您可以使用檔案路徑 import 語法把它拆成幾個部分。不再是一整面文字牆，而是指向其他檔案：
@.claude/conventions/code-style.md
@.claude/conventions/testing.md
@.claude/conventions/workflow.md這對於組織內容非常有用。但要清楚知道它到底帶給您什麼好處，因為很容易產生錯誤的想法。當 Claude 啟動時，它會把那些被 import 的檔案就地展開，正好在您引用它們的位置。所以 import 能幫您把內容整理得井井有條，但所有內容仍然會一次性全部載入。它們並不會減少 Claude 必須讀取的上下文量。使用 import 是為了組織內容，而不是為了縮減負載。
措辭才是讓規則真正生效的關鍵
一旦您決定某條規則該放進 CLAUDE.md，Claude 是否真的會遵守它，就取決於您怎麼措辭。大多數規則失敗的原因是它們太模糊。以下是修正的方法。
具體且可檢驗
不要寫「遵循最佳實踐」。您自己真的知道那確切是什麼意思嗎？如果您無法檢查它是否被遵循，Claude 也無法。比較以下兩者：
- 模糊：「遵循 API 路由的最佳實踐。」
- 具體：「把新的 API 路由放在
src/api/handlers裡，每個檔案一個。」
第二種是明確的。您可以看著結果，立刻判斷它是否做對了。這就是每條規則都該達到的標準。
指明替代方案，而不只是禁止某件事
當您告訴 Claude 不要做某件事時，要說明該做什麼來取代它。否則您就留下了一個開放的缺口。
- 留下缺口：「不要使用預設匯出（default exports）。」 好，但那接下來該怎麼做？
- 封閉缺口：「使用具名匯出（named exports），而不是預設匯出。」
第二個版本指明了替代方案，所以沒有任何空間可以被誤解。
強調是一種預算
像「IMPORTANT」和「YOU MUST」這樣的字詞確實會提高一條規則的優先順序。但那只是相對於周圍其他較平淡的內容而言。如果每條規則都在大聲喊叫，那就沒有任何東西能真正突出，強調也就失去了意義。所以要把強調當作一種預算來看待。把它花在那兩三條一旦被違反就真的會造成傷害的規則上，讓其他規則維持在正常的音量。
讓檔案持續接受修訂
您的 CLAUDE.md 檔案永遠不會完成。把它當作持續被編輯的活程式碼來對待。
當 Claude 做錯事時，不要只是嘆口氣然後手動修正。把它當作是針對您的 CLAUDE.md 檔案的一份錯誤報告。您甚至可以直接告訴 Claude：「把這個加進 CLAUDE.md 檔案裡」，它就會為您寫下這條規則。這樣一來，每次出錯時，這個檔案都會變得更好。
總結
把您的 CLAUDE.md 當作正式上線的程式碼來對待。如果您無法為某一行內容找到理由，就刪掉它。為了讓檔案保持精簡且容易被遵循：
- 把硬性規則移到 hook 裡，讓它們真正被強制執行。
- 用 import 來組織長檔案（但要記住它們並不會減少上下文）。
- 讓每條規則都具體且可檢驗，並指明替代方案。
- 把您的強調預算花在少數幾條最重要的規則上。
- 每當 Claude 出錯時，持續修訂這個檔案。
整個概念很簡單。檔案越精簡，Claude 遵循的比例就越高。