CLAUDE.md 的三個層級

高雄有個做設備保養管理系統的軟體公司，去年十一月找我開了一次諮詢。他們不是來問要不要導入 AI，已經在用了。六個工程師，每個人的 Claude Code 都裝好了、每天在用。

問題是這樣的。

PM 說：「同一個功能，給 A 工程師做，跑出來的程式碼有完整錯誤處理；給 B 工程師做，沒有。風格不一致我可以接受，但行為不一致讓我沒辦法 review。」

CTO 問我：「CLAUDE.md 要放在哪裡，大家才能同步？」

答案只有一句話：放在專案根目錄，提交進 git。

但那次諮詢，我們聊了將近四十分鐘。因為技術答案只要三分鐘，剩下的時間在聊另一件事。

CLAUDE.md 的三個層級

Claude Code 讀取 CLAUDE.md 有三個層級，用途完全不同。

第一層是個人層級，路徑在 ~/.claude/CLAUDE.md。這份只有你自己的電腦讀得到，適合放個人偏好，比如你希望回應永遠用繁體中文、你不喜歡 Claude 解釋太多步驟、你有自己慣用的命名風格。不影響其他人，也不會被 git 追蹤。

第二層是專案根目錄的 CLAUDE.md，也就是 ./CLAUDE.md。Claude Code 在這個目錄工作的時候，會自動讀取這份文件。把它提交進 git，每個人 clone 下來就自動拿到，這就是團隊共用的方式。

第三層是子目錄層級，比如 backend/CLAUDE.md 或 frontend/CLAUDE.md，只有在那個子目錄工作時才讀取。大型 repo 或前後端分工非常明確的專案才需要，一般情況用不到。

高雄那家公司的解法就是第二層：在專案根目錄建 CLAUDE.md，把規則寫進去，git add，commit，推上去。從那天起，每個工程師在這個 repo 工作，Claude Code 都從同一份規則出發。

放進去的東西決定它有沒有用

很多人建完 CLAUDE.md 就把一大堆規則貼進去，然後兩個月後開始忽略它。

CLAUDE.md 裡有用的規則大概分兩類。

一類是穩定的、死的資訊：這個專案用的技術堆疊是什麼、目錄結構怎麼組織、哪些檔案是關鍵不能亂改、部署有什麼特殊規則。這類東西寫了不太需要更新。

另一類是活的規範：API 命名慣例、測試覆蓋率要求、某個模組目前的重構方向、哪些做法這個 repo 決定不再使用。這類東西需要人去維護，而且最好有人明確負責。

高雄那家公司最後的 CLAUDE.md 大概八百字。技術堆疊、資料庫操作規則、錯誤處理的規範、幾個「不要這樣做」的反面例子。PM 說從那之後，review 速度快很多，因為工程師和 Claude Code 拿到的是同一套判斷標準。

位置之前，先問清楚這個

「放哪裡」只是最後一步。

建那份文件之前，有一個問題要先回答：哪些規則算是團隊共識，哪些只是你個人的偏好？

這個問題比它聽起來麻煩。

我見過不少技術主管，自己花了一個下午寫了一份很詳細的 CLAUDE.md，裡面充滿了他自己的編程習慣，然後放進 git，推給整個團隊。兩個月後，沒人在意那份文件了。因為那是他一個人的規則，不是六個人討論出來的規則。

Claude Code 看不出這份文件是不是真正的共識，它只是照著做。但工程師感覺得出來，很快就開始忽略它。

易經裡有個概念，叫「得位」與「失位」。一個爻在它應該在的位置，力量就出得來；在不對的位置，力量就散掉了。

CLAUDE.md 放在 git 根目錄，是得位。但裡面的規則如果不是真正的共識，而是某個人包裝成共識的個人偏好，那就是失位。位置對了，東西本質不對，一樣發揮不了作用。

建文件之前，先開一次會，問清楚哪些規則大家都認同。這個步驟比「放哪裡」花時間，但值得。

高雄那家公司開了一次一個半小時的會，把規則討論清楚了。最後寫進 CLAUDE.md 的只有七條，比 CTO 原來草稿少了一大半。但那七條，是六個工程師都點頭的七條。

之後 review 順多了。

個人層級的 CLAUDE.md 也值得建

那個 ~/.claude/CLAUDE.md 個人層級，很多人不知道可以用。

如果你在多個不同專案之間切換，又想要 Claude Code 的行為有跨專案的一致性，個人偏好放這裡就好。比如你希望它回應永遠用繁體中文、破壞性操作前先詢問確認、偏好看程式碼範例而不是長篇說明。

有個做教育軟體的工程師，他的 ~/.claude/CLAUDE.md 只有四行：不喜歡冗長解釋、偏好範例而非說明文字、任何刪除或覆蓋動作都要先問他、回應用繁體中文。他說加了這四行之後，每天使用的摩擦感少了很多。

個人層級不影響其他人，也不被 git 追蹤。你自己的偏好，放這裡就好。