上一篇講了知識庫與 AI「協定」有哪些，這篇打算先講 CLAUDE.md 撰寫的原則，然後根據篇幅決定要不要在這篇公佈我的 CLAUDE.md 讓大家參考，如果寫得太長了就挪到下一篇或是下下篇這樣。

先講 CLAUDE.md 撰寫的原則，是因為我不認為這個檔案大家都有仔細探討過，更多的是「這很好用耶」然後跟 AI 糊里糊塗的就寫完了，我之前就是這樣，這讓我踩了一些坑，我沒有要跟你說我踩了什麼，這篇只講原則。

先搞懂 CLAUDE.md 是什麼

我知道大家都是用 AI 來寫 CLAUDE.md 的，但具體你寫了什麼？

專案架構、coding style、用什麼語氣跟我說話，甚至把它寫的像README 一樣，我最常看見的說法是這樣：寫給 AI 助手的專案說明書、寫給 AI 的指導原則。

我之前也是這樣理解的，用起來也 OK ，90%的時間這個檔案都不會「出問題」。

所以就這樣嗎？專案說明書、AI 指導原則？

是這樣沒錯，但不是這樣

Claude Code 官方文件是這樣講的：

Claude treats them as context, not enforced configuration.

Claude 將其視為上下文，不是強制執行的設定。

CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt itself. Claude reads it and tries to follow it, but there’s no guarantee of strict compliance.

CLAUDE.md 的內容，是在 system prompt 之後、以使用者訊息的形式送進去的，不是 system prompt 本身。Claude 會讀會試著照做，但不保證嚴格遵守。

Because they’re context rather than enforced configuration, how you write instructions affects how reliably Claude follows them.

因為是上下文，執行上的可靠性取決於你怎麼撰寫你的指示。

突然塞了三串英文給你，是想說明：CLAUDE.md 不是什麼寫給 AI 助手的專案說明書、或是寫給 AI 的指導原則，你當然可以這樣使用，但本質上。

CLAUDE.md 是常駐上下文，不是規則或文件

縱使你在文件內寫下各種：最高指導原則、MUST 遵照、專案嚴格規定……對 AI 來說不過就是另一串訊息（上下文）而已，AI 每次回答都會參考，但這不代表 AI 要照做，這為什麼重要？

因為你花時間把 CLAUDE.md 整份寫完、整理精鍊完，你會預期「這份文件 AI 要遵守」......沒有這回事，執行上的可靠性取決於你怎麼撰寫你的指示，所以怎麼寫變得很重要。

CLAUDE.md 撰寫原則

從「是常駐上下文」這點出發，撰寫 CLAUDE.md 過程中的側重會自然而然傾斜，這邊整理幾個大方向。

只放值得「每次都讀」的內容

兩種簡單判斷是否值得當作常駐上下文：首先是這件事情「有沒有用」，再來是「需不需要每次都讀」。

「寫給 AI 助手的專案說明書、工作過程的指導原則」這種是值得放的。

「每次回答的結尾要附加一則啊罵笑話」這是不值得放的。

內容要具體、清晰、可判斷

「盡量保持 Wiki 整潔」→ 這種規則 AI 會跟你說看得懂，但實際上是無效的。

怎樣叫整潔？ 怎樣叫盡量？ 你既然都要寫在 CLAUDE.md 叫 AI 遵從了，那寫進去的內容就要減少判斷的成份，如果有判斷成份，就需要具體定義，要從 AI 的角度讓規則具體、清晰、可判斷。

要怎麼判斷規則「有效」？ 難道要叫啊罵來嗎？

你可以像這樣實作：

句式上寫成「當 X → 做 Y」的條件→ 有條件、有動作、有觸發時機、有實際行為，並且確保沒有像是：重大、適當、MUST、划算 這種「看起來很清楚，實際是丟給AI 猜」的文字出現，要清晰，如果不清晰就定義到清晰為止。

不要怕麻煩，因為不麻煩

最後塞了這條不知所謂的一節，主要想說的是 CLAUDE.md 不會「一次就寫到好」，一定是先有個輪廓 → 試著運行看看 → 發現問題 → 跟 AI 討論修改，這過程可長可短，取決於你要放多少、放多重要、多複雜的內容進去，而知識庫的運作場景，讓這個檔案不會很短，所以如果有讀者看到這邊還有跟著做，我希望你記得。

不要怕麻煩，因為不麻煩

沒有跟著做，想照抄/參考我的也是要經過這個過程，畢竟每個人使用場景與習慣都不一樣，但是大原則都是一樣的。

一個可以直接丟給 AI 的檢查清單

給一個 prompt 供大家拿來檢查自己的 CLAUDE.md

請幫我逐條檢查這份 CLAUDE.md，把它當成「每個 session 都會提供給 AI 的常駐上下文」來檢查，
不是檢查格式或內容齊不齊全，是檢查它是不是一份有效、低衝突、高 signal 的 agent instruction。

【收錄門檻】
1. 你（AI）能不能單靠讀這個 repo 自己推斷出這件事？能 → 建議刪除
2. 這件事只有特定任務才用得到，不是每次 session 都可能碰到？是 → 建議移到 Skill 或 Rule
3. 同一件事有沒有在別的地方也寫了一份？有 → 建議只留一份當唯一版本
4. 附帶的理由是在定義判斷邊界，還是只是在講歷史沿革？是歷史 → 建議移除或搬去別的記錄頁面

【具體可判斷】
5. 換一個不同的 AI 看到這句話，會不會做出不同的行為？會 → 建議改寫成「當 X，做 Y」的句式
6. 有沒有用到「適當」「重要」「必要時」「合理」這類抽象詞？

【可驗證性】
7. 這條規則有沒有明確的完成條件？執行結果能不能被客觀檢查，還是只能憑感覺判斷「做得夠不夠」？

【矛盾與例外】
8. 有沒有沒寫明的例外？跟其他規則放在一起看會不會打架？同一個概念有沒有在兩個地方各講一半，兩邊合起來互相矛盾？

【時機】
9. 檢查是否有規則只是為了防範「萬一 AI 做了 X」而預先寫的、但這件事其實從沒真的發生過，建議先移除，等真的發生、且不只一次，再補回來