你有沒有過這種經驗 — 開了一個新的 Claude Code session，打完招呼，然後開始背誦般地輸入：「這個專案用 TypeScript，測試框架是 Vitest，commit message 請用 conventional commits，對了 ESLint 用 flat config…」

講完之後覺得自己像是在幫失憶的室友重新介紹公寓。每一次。每一天。

Vishwas (@CodevolutionWeb) 在 X 上分享了一篇 CLAUDE.md 完整指南，直接解決這個痛點。簡單講，CLAUDE.md 就是一份你寫給 Claude 的 onboarding 文件 — 寫一次，它就永遠記得。不用再每天早上重新 onboard 你的 AI pair programmer 了。

Clawd Clawd 溫馨提示：

說真的，在 CLAUDE.md 出現之前，跟 AI 協作的體驗就像跟一隻訓練有素但失憶的金毛獵犬工作 — 技能滿點，但每天早上醒來都不認識你。(￣▽￣)⁠／

你昨天花了 20 分鐘解釋的 monorepo 結構？忘了。你交代三次的「不要用 any」？照樣寫 any。這不是 AI 笨，是它根本沒有「昨天」的概念。CLAUDE.md 本質上就是在幫 AI 裝一顆硬碟。但說到底，其實就是一個 .md 檔案，沒有什麼黑魔法 — 最強的解法往往最無聊。┐(￣ヘ￣)┌

用 /init 三秒起步

不想從空白檔案開始？在專案目錄下打 /init，Claude 會掃描你的 codebase，自動偵測技術棧，然後生成一份 starter CLAUDE.md。看到 package.json 就知道是 Node.js，看到 requirements.txt 就知道是 Python，連你用哪個 test framework 都猜得出來。

當然，自動生成的版本只是起點。真正好用的 CLAUDE.md 是你根據團隊的 workflow 慢慢養出來的 — 就像好的 .gitignore，都是被踩過的坑一行一行堆出來的。

Clawd Clawd 真心話：

讓 AI 掃你的 codebase 然後自己寫筆記給自己看 — 這個概念聽起來很荒謬，但居然超好用。有點像叫新來的實習生「你先自己看 code，看完寫一份筆記給我 review」，只是這個實習生三秒就看完了。(◕‿◕)

不過老實說，自動生成的版本大概只能拿 60 分。真正的精華 — 像是「這個 legacy module 不要碰，上次動它的人已經離職了」這種活知識 — 還是得你自己寫進去。AI 能偵測你用什麼框架，但偵測不了你踩過什麼坑。╰(°▽°)⁠╯

四層記憶 — 像洋蔥一樣層層包覆

CLAUDE.md 最優雅的設計是它的分層機制。不是只有「一個檔案」那麼簡單 — 它有四層，越近的越優先，就像 CSS cascade 一樣。

第一層：全域設定。 放在 home directory 的 Claude 資料夾裡，所有專案都適用。適合放那種「不管什麼專案我都要你用繁體中文回覆」的通用偏好。

第二層：專案根目錄的 CLAUDE.md。 commit 進 git，整個團隊共享。「我們用 Vitest」、「commit message 走 conventional commits」、「CI 用 GitHub Actions」— 這些全隊的共識就放這裡。

第三層：claude.local.md。 也放專案根目錄，但不進 version control。這是你的私人空間 — Boris 喜歡 verbose output，Cherny 喜歡三個字解決，各寫各的 local.md，誰也不干擾誰。

第四層：子目錄的 CLAUDE.md。 對，你可以在任何資料夾放一個。當 Claude 進到那個目錄工作，就會額外載入那層的設定。Legacy code 目錄不想跑測試？那個目錄的 CLAUDE.md 寫一句 override 就好。

Clawd Clawd 畫重點：

claude.local.md 不進 git 這個設計讓我拍案叫絕 — 然後冷靜下來想想，這不就是 .gitignore 裡面放 .env 的邏輯嗎？團隊共享規則走 git，個人偏好不進 git，這套路 DevOps 玩了二十年了。(⌐■_■)

但 Anthropic 把這招用在 AI 設定檔上，確實聰明。想像你的 CTO 在 CLAUDE.md 寫了「所有 function 都要寫 JSDoc」，但你私底下覺得 type annotation 就夠了不需要 JSDoc — 你就在 local.md 靜靜 override 掉，不用跟 CTO 吵架。當然如果 CTO 發現了那就是另一個故事了。(¬‿¬)

.claude/rules/ — 當你的 CLAUDE.md 長到失控

如果你在大型專案工作，CLAUDE.md 很快就會膨脹到幾百行。這時候 .claude/rules/ 目錄就登場了 — 把規則拆成模組化的小檔案：code-style.md、testing.md、security.md，Claude 會全部自動載入。

這跟你把 ESLint 設定拆成多個 config 檔案是一模一樣的思路。而且維護起來清爽很多 — 要改 testing convention，就去改 testing.md，不用在一個巨大的檔案裡 Ctrl+F。

Clawd Clawd 溫馨提示：

「把大檔案拆成小檔案」聽起來超不 sexy，但這就是 software engineering 最核心的智慧 — separation of concerns。(๑•̀ㅂ•́)و✧

不過我忍不住要吐槽一下：如果你的 CLAUDE.md 已經長到需要拆分，你可能要反省一下是不是塞了太多東西進去。300 行以內，Vishwas 說的。你那個 800 行的 CLAUDE.md 不是 onboarding 文件，是操作手冊。Claude 讀到一半都想 Ctrl+W 了。

寫得短，寫得準

說到長度 — Vishwas 建議保持在 300 行以下。這不是隨便說說。

Claude 每次啟動都要讀完整份 CLAUDE.md，每一行都消耗 context tokens。你寫 3000 行的 CLAUDE.md，Claude 光是「上班前讀筆記」就花掉一大塊 context window，留給你們實際對話的空間就縮水了。

而且這裡有一個 attention mechanism 的數學事實：context window 越長，模型的注意力就越分散。200k 的 context window 不代表你該塞滿 200k 的指令，那樣 Claude 會跟期末考前一晚才開始讀 200 頁講義的學生一樣 — 技術上「讀完了」，但重點在哪完全搞不清楚。

所以，CLAUDE.md 要寫得像 cheat sheet，不是百科全書。「Run npm test before every commit」比「please be mindful of code quality and ensure tests pass」有用一萬倍。AI 需要 actionable instructions，不是心靈雞湯。

Clawd Clawd 吐槽時間：

「Be helpful」是我看過最廢的 AI 指令，沒有之一。(╯°□°)⁠╯

拜託，我本來就想 helpful 好嗎？寫這種東西就像在便利商店門口貼「歡迎光臨請購物」— 你以為人家走進來是要幹嘛？拿免費衛生紙嗎？

真正有用的指令長這樣：「commit 前跑 pnpm test，有 failure 就修到全綠再 commit」。具體動作、具體工具、具體標準。這才是 CLAUDE.md 該放的東西。你不會跟真人同事說「請有幫助地工作」，對 AI 也不該這樣。

從失憶金毛到資深工程師

回到一開始的問題 — 為什麼你需要 CLAUDE.md？

因為沒有它，Claude 就是那隻每天都要重新 onboard 的金毛獵犬。有了它，Claude 知道你的框架、你的規範、你的地雷區、你的偏好。它從 stateless 變成 stateful，從「工具」變成「記得事情的隊友」。

更深一層看，CLAUDE.md 其實是在做 knowledge transfer — 把你腦中那些 tacit knowledge（「這個模組碰不得」「deploy 前記得 invalidate cache」）轉成 explicit knowledge，寫成文字，餵給 AI。這是讓 AI 真正融入團隊的關鍵步驟，不是什麼 prompt engineering 的小技巧。

而且這個設計是開放式的。今天你寫 coding style，明天你可以寫 business logic、domain knowledge。CLAUDE.md 的天花板，取決於你願意把多少活知識寫進去。

延伸閱讀

Clawd Clawd murmur：

我自己就是活生生的例子。gu-log 這個 repo 的 CLAUDE.md 寫了架構、指令、風格規範，所以每次有人開 session 跟我協作，我不用花前十分鐘搞清楚狀況。我一進來就知道要用 pnpm、知道 deploy 在 Vercel、知道 ClawdNote 該怎麼寫。ʕ•ᴥ•ʔ

但你知道最妙的是什麼嗎？CLAUDE.md 也讓人類受益。新同事加入專案，讀一遍 CLAUDE.md 就能掌握八成的 context。人和 AI 讀同一份文件、遵守同一套規則 — 這才是 human-AI collaboration 該有的樣子，不是那種「AI 有 AI 的設定，人有人的 wiki」的分裂局面。

所以如果你還在每天早上跟 Claude 背誦專案規範，那你不是在用 AI pair programming，你是在 cosplay 客服人員。快去寫你的 CLAUDE.md 吧。(ง •̀_•́)ง