寫好 CLAUDE.md 的 8 條實戰經驗 (8 Practical Rules for Writing an Effective CLAUDE.md)
原始來源與檔名：20260512_2026-05-12T092949+0800-写好 CLAUDE.md 的 8 条经验：让 Claude Code 更懂你的项目.md
來源：[[@vincemask]] / X (Twitter) — 2026-05-07
原始檔名：2026-05-12T092949+0800-写好 CLAUDE.md 的 8 条经验：让 Claude Code 更懂你的项目.md
NAPKIN | 餐巾紙
餐巾紙公式
Bad CLAUDE.md = 2000 lines of history + Vague Wishes (“Write clean code”) Good CLAUDE.md = < 200 lines + “Do NOT” lists + Pointer to Docs + Automated Hooks + MEMORY.md loop
把 CLAUDE.md 當作垃圾桶，塞進所有的公司歷史和技術文件，只會讓 Claude 在冗長的上下文中迷失。頂級玩家的 CLAUDE.md 是一份精簡的路由器與防護網。它告訴 AI 絕對不要碰什麼（禁止清單）、去哪裡找詳細資料（文件指標），並用自動化腳本（Hooks）來強制執行紀律。
一句話
這篇文章總結了在專案中撰寫
CLAUDE.md的 8 條反直覺經驗。作者指出，CLAUDE.md 的上限是 200 行，其核心價值不在於儲存所有知識，而在於提供「具體可操作的規範」與「明確的禁止清單」。進階技巧包含了：將 CLAUDE.md 作為指向其他架構文檔的指針、在敏感目錄設置區域性 CLAUDE.md、透過 Hooks 腳本強制執行規則，以及設立 MEMORY.md 來建立長期記憶迴圈。
餐巾紙草圖
[The CLAUDE.md Hierarchy]
Root Directory
├── CLAUDE.md (< 200 lines)
│ ├── Project Overview
│ ├── DO NOT Introduce List (Redux, MUI, etc.)
│ ├── Actionable Rules ("Use named exports")
│ ├── Pointers -> (See docs/architecture.md)
│ └── Triggers -> (Read MEMORY.md on start)
│
├── .claude/hooks/
│ └── pre-tool-use.json (Forces Prettier/Tests)
│
└── src/auth/
└── CLAUDE.md (Local guards: "Never touch token logic")ROUND 1: SKELETON | 骨架掃描
“這篇文章在說什麼”
- 精簡原則 (1): 越長越糟，超過 200 行會佔用過多上下文並被忽略。用簡短的產品目標取代長篇公司敘事。
- 負面表列 (2): 必須有「不要引入什麼」的清單。防堵 Claude 擅自引入不相容的最佳實踐（如在 Tailwind 專案引入 Styled-components）。
- 具體可執行 (3): 拒絕感受型規則（如「寫乾淨的代碼」）。必須是測試型規則（如「組件不超過 200 行」）。
- 架構路由 (4): CLAUDE.md 不該是圖書館，而是「指標」。告訴 Claude 架構圖在
docs/architecture.md，讓它按需載入（漸進式上下文）。 - 安全隔離 (5): 在高風險目錄（如 auth, billing）建立專屬的「本地 CLAUDE.md」作為安全護欄。
- 強制執行 (6): 寫在文本裡的規則會被忘記。將格式化或測試指令寫入
.claude/hooks/，讓系統強制執行。 - 記憶迴圈 (7): 在 CLAUDE.md 中指令 Claude 維護一個
MEMORY.md，實現跨會話的知識累積。 - 工作風格 (8): 直接在裡面寫明個人偏好（如「不要說廢話」、「代碼註解用英文」），省去每次新對話的開場白。
ROUND 2: DISSECTION | 血肉解剖
“憑什麼這麼說”
核心論證鏈
- Context Window 的零和博弈: Claude Code 每次互動都會載入根目錄的 CLAUDE.md。如果在裡面放了 2000 行的 API 規格，就等於每次提問都自費吃掉大量 Token，且沖淡了當下真正指令的權重（Attention Dilution）。
- 預設行為的覆寫 (Overriding Default Bias): 大模型受限於訓練資料，往往有自己的「預設最佳實踐」（例如偏好某些主流庫）。「禁止清單 (Do NOT introduce)」是唯一能以最高權重蓋過模型預設傾向的手段，這防止了技術棧的靜默污染。
- 從「語義約束」到「工程約束」: Rule 6 (Hooks) 是全文最硬核的洞見。模型本質上是機率分佈，它永遠有可能「忘記」執行測試。將規則轉化為 Hook 腳本（在模型執行寫檔動作前後觸發），徹底消除了機率誤差，這才是真正的工程化防線。
關鍵證據
- 具體的負面表列案例（Redux, styled-components）精準擊中了前端開發者在讓 AI 接管專案時最常遇到的依賴混亂災難。
- Hook 配置檔的 JSON 範例，證明了這套方法論是建立在 Claude Code 實際機制之上的可行操作。
邊界條件
- 「漸進式上下文 (Tiered Context)」與「本地 CLAUDE.md」的前提是，底層的 Agent 工具（如 Claude Code 或 Cursor）支援動態讀取目錄內檔案的特性。如果在不支援路徑感知的普通網頁版對話框中使用，這些技巧將無效。
ROUND 3: SOUL | 靈魂提取
“還能怎么用”
- 知識連結: 本文與《補全 Karpathy 的遺漏：升級至 12 條 CLAUDE.md》完美互補。那篇提供了具體的「規則範本」，而本篇提供了「檔案架構與部署策略（如 Hooks, Local files, Router）」。
- 深層洞見: 「CLAUDE.md 是指針，不是圖書館。」 這反映了軟體架構中 Separation of Concerns（關注點分離）的智慧。即使在寫自然語言的 Prompt，也必須具備工程師模組化設計的思維。
- 行動呼籲:
- 立刻檢查你的專案根目錄。如果你的
CLAUDE.md或.cursorrules超過 200 行，毫不留情地刪減它。 - 建立一個
MEMORY.md檔案，並在CLAUDE.md加入一句：「每次開始任務前，請先閱讀 MEMORY.md；任務結束後，將學到的新坑寫進去。」這一個動作，就能讓你的 AI 擁有持續成長的記憶。
- 立刻檢查你的專案根目錄。如果你的