Best Practice 分享：成熟 CLAUDE.md 長什麼樣¶

讀者：做完 M4 的學員。時長：15-20 min（純讀，不需要動手）

M1-M4 教你怎麼寫第一份 CLAUDE.md。這頁拆解一份用了幾個月、踩過真實 incident、累積過迭代的 CLAUDE.md 長什麼樣 — 並指出哪些值得抄、哪些可以再加強。

取材自一份實際 production 在用的 Global CLAUDE.md（已匿名）。

為什麼要看別人的 CLAUDE.md？

寫 CLAUDE.md 像寫合約：第一版總是太天真。看別人踩過坑後的版本，可以省下你自己踩坑的時間。

想直接看完整範本（可複製）

這份範本的完整原文（已匿名）放在完整範本：成熟版 Global CLAUDE.md 一頁，含「極簡版（50 行）」起步用 + 「完整成熟版」全文 + 客製化指引。建議先讀完下面的模式分析，再回去複製。

8 個值得學的模式¶

模式 1：MUST / SHOULD / MAY 三層分類¶

把規則明確標 normative level（借用 RFC 2119 風格）：

## §B. 硬性約束（MUST）
- MUST：commit 前必須跑過 lint
- MUST NOT：將密碼寫進程式碼

## §C. 預設行為（SHOULD）
- SHOULD：遵循專案既有慣例
- SHOULD：選 boring and reliable 的解法

## §D. 可選建議（MAY）
- MAY：使用 type hint 提高可讀性

為什麼好：Claude 在判斷「我可不可以 override 這條」時有明確依據。MUST = 不能違反、SHOULD = 有理由可以 override、MAY = 隨意。

模擬對比：

沒有分層的 CLAUDE.md有 MUST/SHOULD/MAY 分層

學員：請用 type hint 重構這個函式

Claude：好的，我會加 type hint。順便我看到 README 寫「程式碼註解一律繁中」但你的其他檔案都是英文註解，我也統一改成繁中可以嗎？

（Claude 不知道哪條重要、把可選建議當必須遵守）

學員：請用 type hint 重構這個函式

Claude：好的，加 type hint。順帶一提我看到註解中英混用，但這是 SHOULD 等級規則，不影響本次 task，要不要另開 PR 統一？

（Claude 知道這次任務範圍，提建議但不擅自擴張）

模式 2：每條規則都附 "Why" 和 "How to apply"¶

不只寫規則，寫為什麼和怎麼判斷邊界情境：

### B8. Evidence-before-claims
- MUST：宣告「完成 / 通過 / 修好」前，必須在本輪對話跑過驗證指令
- **Why**：「應該」「看起來」「理論上」會累積失信與 rework
- **How to apply**：
  - 宣告「檔案已寫入」→ 跑 `ls` 或 `cat` 確認
  - 宣告「測試通過」→ 貼出測試指令輸出

為什麼好：當 Claude 遇到規則沒明說的邊界情境，可以從 Why 推導該怎麼做，而不是「照字面執行 → 違反精神」。

模式 3：失敗處理紀律（3 次同方法停下）¶

明確的反 sunk-cost 條款：

### B6. 失敗處理
- MUST：同一方法嘗試 3 次失敗後，停下
  - **「同一方法」定義**：語意層面的同一個 approach。
    換 regex、換欄位名、換參數值仍算同一個 approach；
    換工具、換資料來源、換演算法才算不同 approach。
- MUST：停下後做三件事：
  1. 列出已嘗試的方法
  2. 重新檢視原本的假設
  3. 提議不同的 approach 給使用者選擇

為什麼好：「再試一下」是時間黑洞。明確 3 次上限 + 「同一方法」定義（避免換變數名規避規則），逼自己 step back。

模擬對比：

沒有 B6有 B6

Claude：第 1 次 regex 沒過，再試 \d{4}-\d{2}-\d{2} ...

Claude：第 2 次還是沒過，加 |\d{4}/\d{2}/\d{2} ...

Claude：第 3 次再加民國年 ...

Claude：第 4 次再改 group capture ...

學員：（30 分鐘後）這還在跑？

Claude：第 3 次 regex 仍失敗。停下。

已嘗試：基本日期 / 加斜線格式 / 加民國年。重新檢視假設：我一直假設欄位是字串，但 traceback 顯示是 datetime object。建議換 approach：用 pandas.to_datetime，而非 regex。

要這樣試嗎？

模式 4：Evidence-before-claims 反「應該」¶

### B8. Evidence-before-claims
- MUST NOT：用「應該」「看起來」「理論上」「剛剛改完應該就好」代替驗證
- EXCEPTION：純 read-only 查詢、純解釋型回答

為什麼好：「應該過了」累積一次 = 一次 trust debit。十次後使用者就再也不信任何「完成」的宣稱。

模擬對比：

沒有 B8有 B8

學員：commit 一下

Claude：好的，已 commit。應該過 hook 了，這個 lint 規則之前沒改過。

學員：（5 分鐘後發現 CI red）...

學員：commit 一下

Claude：好的，commit 跑下去。
ruff check ... Passed
ruff format ... Passed
[main abc1234] feat: ...
確認 hook 通過、commit landed。

模式 5：不確定性處理紀律¶

### B3. 不確定性處理
- MUST：以下情境必須停下來問，不得擅自決定：
  - 資料中出現未定義的值（例：新國別代碼）
  - 同一檔案有兩個以上合理的處理方式
  - 指令可以合理解讀為 ≥2 種做法
- MUST NOT：遇到不確定時靜默選 fallback 值（如「其他」「unknown」「N/A」）

為什麼好：明確列舉「禁用 fallback」是反 silent failure 的最強條款。

模擬對比：

沒有 B3有 B3

學員：跑 pipeline

Claude：跑完了。處理 1247 筆，其中 23 筆代碼未定義，歸入「其他」分類。

學員：（一週後）為什麼這個月「其他」分類爆增？

學員：跑 pipeline

Claude：跑到第 437 筆停下。出現未定義代碼「ZX」，rules 沒列。

我不知道該： (a) 併入哪個現有分類 (b) 歸入「其他」

這是新代碼嗎？請告訴我規則我再繼續。

模式 6：正例段落把抽象規則具體化¶

## §E. 正例

### E1. 重構計畫的顆粒度
**情境**：使用者說「幫我重構 X」

好的計畫：
> 重構前我理解的現狀：[...]
> 我提議的方向：[...]
> 會動到的檔案：[...]
> 你覺得方向對嗎？確認後我開始。

重點：**現狀理解 + 方向 + 會動到的檔案 + 確認請求**。

為什麼好：抽象規則（「複雜任務先出計畫」）很容易被誤判顆粒度（出個 50 行 spec 反而 over-engineering）。正例校準「夠用就好」的長相。

模式 7：明確的層級規則¶

## §H. 層級規則

| Global 層級 | 專案級可否 override |
|------------|-------------------|
| §B MUST   | ❌ 不可 override |
| §C SHOULD | ✅ 可，但需寫理由 |
| §D MAY    | ✅ 隨意 |

### Monorepo 特殊規則
讀取順序：Global → monorepo CLAUDE.md → sub-project CLAUDE.md
衝突時由具體到抽象：sub-project > monorepo > Global（於可 override 範圍內）。

為什麼好：多層 CLAUDE.md 共存時的衝突解決寫死，不然每次都靠 Claude 自己 judge。

模式 8：記憶系統職責分離¶

| 系統 | 性質 | 用途 |
|------|------|------|
| CLAUDE.md | 結構化、人工控管 | 規則、長期事實 |
| auto memory | 半結構化、對話自動累積 | 使用者偏好、回饋、臨時脈絡 |

- MUST：跨 session 必須穩定的規則 → 寫 CLAUDE.md
- MUST：使用者偏好、單次回饋 → 寫 auto memory
- MUST NOT：同一內容同時寫在兩處（避免漂移）

為什麼好：Claude Code 有 CLAUDE.md + auto memory 兩種長期記憶機制。沒寫清楚分工，最後兩邊都半套、互相衝突。

還可以再加強的 3 個地方¶

加強 1：長度 — 600+ 行的甜蜜陷阱¶

成熟的 CLAUDE.md 容易越寫越長（這份接近 600 行）。風險：

新進的 Claude（或新接手的協作者）讀完都累，傾向只看標題
條目互相衝突的機率上升（例：B2「先出計畫」vs B7「輸出簡潔」邊界模糊）
增加 context 成本（每個 session 開頭都載入）

模擬對比：

600 行單檔Tiered CLAUDE.md

Claude 啟動 → 載入 600 行 → 後續對話常常「忘記」中段的條款需要使用者反覆提醒「§B6 寫了」「§E3 有正例」

Claude 啟動 → 載入 80 行核心（top 5 MUST + index）其他段落按需 lazy-load（透過 @ref filename.md 連結）

可以怎麼做： - 主檔留 top 5 MUST + 索引 - §E（正例）、§G（shared-core 細節）、§J（meta 規則）拆出去用 @reference 連 - 留個「先讀這個」的 fast-track（前 100 行）

加強 2：§F 易 drift，缺自動校驗¶

§F「當前狀態快照」是 volatile 段落（會隨時間過期）。這份 CLAUDE.md 有明確 §J 寫作紀律規定「14 天 / 30 天 review」 — 但沒有機制強制執行。

模擬情境： - §F 寫「最新一期 2026-04-16」 - 兩個月後實際是 2026-06-XX，但沒人 review - Claude 照舊 context 回應 → 出錯

可以怎麼做： - 在 §F 每個條目加 last_updated: YYYY-MM-DD - 寫一個 pre-commit hook 檢查 §F 條目超過 N 天就 warning - 或在 §F 開頭嵌一段「last_verified: YYYY-MM-DD，如果今天距離超過 30 天請先重新檢視 §F 再使用」

加強 3：MUST 條目太多，缺新人 fast-track¶

10 條 MUST（B1-B10）對成熟使用者剛好；對「第一次協作的 Claude session」可能 overwhelming。

模擬對比：

現狀加 fast-track

新 Claude session → 讀完 §B 10 條 → 第一次 task 用力套用所有規則 → 過度 cautious （例：問了 5 個釐清問題才開始小修一個 typo）

新 Claude session → 先讀「核心 3 條」（例：B5 安全、B6 失敗處理、B8 evidence）熟悉脈絡後再讀剩下 7 條

可以怎麼做：在 §B 開頭加「## §B0. 如果你只記 3 條，記這 3 條」。

小結¶

抄哪些	暫不抄
✅ MUST/SHOULD/MAY 分層	❌ §F 狀態快照（你還沒有狀態要追）
✅ 每條規則附 Why	❌ §G 跨專案共用（單專案不需要）
✅ 失敗處理（3 次同方法停下）	❌ §H 層級規則（單一 CLAUDE.md 不需要）
✅ Evidence-before-claims	❌ 600 行的長度（先寫 100 行能用就好）
✅ 不確定性處理（禁 silent fallback）
✅ 正例段落具體化

第一份 CLAUDE.md 目標 = 50-80 行。等用了一陣子、踩過幾個雷，再依需要加。不要一開始就模仿這份成熟版的長度 — 你會寫不出來。

給已經寫過 CLAUDE.md 的你¶

如果你做完 M4，已經有一份 50 行左右的 CLAUDE.md，下一個迭代可以考慮：

把規則標 MUST / SHOULD / MAY
至少 3 條 MUST 附 Why
加 1-2 個正例段落（不只列規則、給範例對話）
加「不要做的事」清單（明確紅線）
加「失敗 N 次後停下」的反 sunk-cost 條款

不要急著做完所有。寫到下次 session 你發現「啊這條 Claude 又忘了」再補。

← 回 M4 ｜回首頁