前言：不就是一份「給 AI 看的說明文件」嗎？

「CLAUDE.md 不就是把專案規範寫一份文件丟給 AI 讀嗎？跟寫 README、寫 wiki 有什麼本質上的不同？」

如果只看表面，確實看不出差別——都是一份 Markdown 文件，都放著一堆「這個專案該怎麼做事」的規則。但 CLAUDE.md 有一個 README 沒有的特性：它幾乎每次任務都會被完整載入進 AI 的工作記憶裡。這個特性帶來一個直接的後果：這份文件裡放什麼、放多少，直接決定了 AI 每次工作時「腦子裡裝的東西」有多少雜訊。

昨天的系列介紹立下了這句話：AI 開發工具本身也需要被當成軟體來設計——沒有清楚的分工跟驗證機制，這些工具會用最省事的方式退化成一堆互相矛盾、逾越範圍的雜訊。 CLAUDE.md 是這套工具鏈裡最基礎、也最容易被寫壞的一塊。今天要講的，是它該裝什麼、不該裝什麼。

今日目標

• 理解 CLAUDE.md 跟一般文件在「載入時機」上的本質差異
• 掌握一條具體的判斷分界：什麼規則該放 CLAUDE.md，什麼該放別的地方
• 認識「分不清楚」會造成的兩種實際傷害
• 建立寫進 CLAUDE.md 前先問自己一個問題的習慣

CLAUDE.md 的特性：它不是被查閱的，是被載入的

一般的技術文件（README、wiki、規格書）是「被查閱」的——你有問題的時候去找，找到了讀那一段，其他段落不會進到你的腦子裡。CLAUDE.md 不一樣，它的設計前提是「每次任務開始前，完整讀進工作記憶」。這代表：

• CLAUDE.md 裡的每一行文字，每一次任務都要花一次載入成本，不管這次任務用不用得到
• CLAUDE.md 裡的每一條規則，都在跟其他規則搶奪 AI 的注意力權重——規則越多，每一條被真正記住、真正被遵守的機率就越低

這兩個特性合起來，決定了 CLAUDE.md 不能被當成「什麼規則都往裡面塞」的萬用抽屜。

判斷分界：這條規則「幾乎每次都用得到」嗎？

一條具體、好用的判斷標準是：這條規則，如果拿掉，會不會讓「幾乎每一次」任務都可能出錯？ 如果答案是肯定的（例如「commit 訊息要用 Conventional Commits 格式」「新檔案一律 UTF-8 no BOM」），這條規則屬於 CLAUDE.md。如果答案是「只有碰到某個特定情境才用得到」（例如「重構某個特定模組時要遵守的覆蓋率門檻」「呼叫外部 API 時要用哪個介面組 request」），這條規則不該放進 CLAUDE.md，該放進一支獨立的 skill，讓 AI 只在真的碰到那個情境時才載入。

這個分界背後的邏輯，是把「規則的觸發頻率」跟「規則的儲存位置」對齊——觸發頻率高的規則，值得每次都付出載入成本；觸發頻率低的規則，載入成本應該只在真的用到的時候才付出。

用一組對照來看這件事實際發生的樣子：

❌ 全部塞進 CLAUDE.md：
一份 CLAUDE.md 裡同時有「commit 訊息格式」（幾乎每次都用得到）、
「某個資料層模組的欄位型別轉換規則」（只有動那個模組才用得到）、
「某支腳本的參數順序慣例」（只有寫那支腳本的呼叫端才用得到），
全部平鋪直敘地混在一起，隨著專案演進越寫越長。
→ 每次任務都要載入這整份文件，包含 95% 這次用不到的細節；
  規則越多，AI 對任何單一規則的「注意力權重」越稀薄，
  容易漏掉真正該遵守的那一條

✅ 分層：CLAUDE.md 只放全站規則，細節放進 skill：
CLAUDE.md 裡只留「commit 訊息格式」這類幾乎每次都用得到的規則；
「某個資料層模組的欄位型別轉換規則」寫成一支 skill，
只在動到那個模組的路徑時才自動載入；
「某支腳本的參數順序慣例」也是同樣處理。
→ 每次任務載入的 CLAUDE.md 維持精簡，只在真的碰到
  對應情境時，才把細節規則帶進工作記憶

CLAUDE.md 該回答的問題是「這個專案不管做什麼事，都要遵守的底線是什麼」；skill 該回答的問題是「碰到這個特定情境時，還要多遵守什麼」。 把後者的答案寫進前者的位置，是最常見、也最容易被忽略的設計錯誤。

分不清楚會造成的兩種傷害

第一種傷害是權重稀釋：CLAUDE.md 越長，AI 對裡面任何一條規則的重視程度就越平均、越稀薄。十條規則裡，AI 大概能穩定記住並套用的可能只有前面幾條最顯眼的；混進五十條規則裡，同一條規則被真正落實的機率明顯下降。這不是 AI「變笨」，是任何有限注意力的系統都會發生的現象——規則堆得越多，單條規則能分到的注意力就越少。

第二種傷害是載入成本：每次任務都要重新讀一次完整的 CLAUDE.md，這份成本會隨著文件變長而線性增加。如果裡面 90% 的內容這次任務根本用不到（例如你正在寫一篇跟資料庫完全無關的文件，卻要載入一整段資料層型別轉換規則），這些成本就是純粹的浪費，而且是每次都要重複付出的浪費。

今日思考題

回想你自己專案裡的 CLAUDE.md（或任何你維護給 AI 讀的規範文件）：裡面有沒有哪一條規則，只有在碰到某個特定模組、特定情境才用得到，卻被放在「每次都要載入」的位置？如果拿掉它，會不會讓你意識到它其實更適合被歸類到別的地方？

今日重點回顧

• CLAUDE.md 跟一般文件的本質差異：它是「每次都被完整載入」，不是「被查閱」
• 判斷分界：這條規則「幾乎每次任務都用得到」嗎？是就放 CLAUDE.md，不是就該放進按需載入的 skill
• 分不清楚會造成兩種傷害：權重稀釋（規則越多、每條被記住的機率越低）跟載入成本（每次都要付出、大部分時候用不到）
• CLAUDE.md 回答「不管做什麼都要遵守的底線」，skill 回答「碰到特定情境還要多遵守什麼」

明日預告

明天用一個具體案例，走一次「CLAUDE.md 太長」實際會發生什麼事——不是空談權重稀釋這個概念，而是看它在真實任務裡怎麼讓一條原本清楚的規則被忽略掉。