CLAUDE.md 理解整理捕捉檔
單篇任務型捕捉檔，綁定「整理好對 CLAUDE.md 的理解」這件事本身。內容完成後 Promote 進 wiki/evergreen/topics/DragonsHoard建設歷程/（依內容性質分派到對應子頁），不是 iThome 第七篇文章草稿——文章素材另見 chaos/第七篇（新）CLAUDE.md 四原則＋外部共識 草稿.md。
素材來源：使用者另外用 ChatGPT 整理的一份 CLAUDE.md 撰寫原則報告（21 條＋核心命題），逐條 review 後已全數收斂進下方「真正的原則」與「補充材料」兩節，原始編號保留供回查；21 條全文本身不再保留於本檔。
真正的原則（逐條收斂完成，目的：寫文章）
1. CLAUDE.md 是常駐上下文，不是規則或文件
（合併核心命題＋原報告一「先理解 CLAUDE.md 到底是什麼」＋十六「CLAUDE.md 是指令不是保證」＋十七「不要濫用 MUST/NEVER」）
CLAUDE.md 本質上是配置給 AI 的常駐上下文，不是規則或文件；就算寫成「規則」「MUST」的形式，AI 收到的仍只是 context 的一部分，不是機械化照做的指令。「規則」是寫的人自己的分類幻覺，對 AI 不存在特殊待遇。
這是整份文章的框架層，不是跟後面平行的一條原則——後面每一條「為什麼」成立，都是這個本質的推論結果（要具體、要短、MUST/NEVER 不是保證……）。
正因為只是 context，再怎麼加重語氣（MUST、NEVER、IMPORTANT）都不會讓它變成真正的強制執行——真正不能失敗的硬約束要交給 hook／permission 這類機制；濫用強調詞只是自欺。真實對照：raw/ 唯讀從技術強制改回文件約定（建設歷程「十二」），承認的正是這件事——CLAUDE.md 終究只是講給 AI 聽的文字。
2. 收錄門檻是第一條的延伸：只放值得當常駐 context 的內容
（原報告二「五問篩選」＋三「資訊增量原則」＋四後半「保留影響判斷的理由」＋十一「一條規則只有一個 Source of Truth」＋二十「Signal-to-Noise 比字數重要」）
因為 CLAUDE.md 是常駐上下文，所以裡面的內容應該只有「值得當作常駐 context」的內容。長度是這個篩選確實執行後的結果，不是篩選的目的——不是「怕太長所以要篩」，是「每條都認真篩過，長度自然被控制住」；篩選是寫入當下的關卡，不是寫完之後回頭砍字數。200 行是警戒線，不是正確性邊界：一份 220 行、每行都通過篩選的 CLAUDE.md，會比 150 行但充滿重複／過時資訊的版本健康。
五問篩選（session都需要／repo推不出來／忘記會出錯／穩定／能簡短表達）留著當操作化的參考清單，不是獨立原則本身。
例外：規則可以附一句短理由——不用抽象測試公式判斷，直接依我們真實發生過的兩件事：
- 理由留下來：
raw/唯讀附「因為是 provenance layer」這句沒有刪——建設歷程「二十三」續（2026-08-21）記錄的真實理由是「這條規則主要是講給 AI 聽：ingest 時只讀不改的邊界如果沒明講，AI 可能『順手』改動來源檔」，是真實發生過的判斷依據，不是事後推論出來的測試。 - 歷史敘事砍掉、送去建設歷程：不是丟棄，是換到我們之後精修 CLAUDE.md 時真的會回頭查、會用到的地方——對應既有原則「CLAUDE.md 不該內嵌演變歷史」（協作與元規則「二十三」）。理論上這類內容本來就不該寫進 CLAUDE.md，但正因為我們會持續調整規則，才需要建設歷程這個參考位置。
單一 Source of Truth：同一份資訊不要存在兩個地方——收錄門檻決定「這個資訊該不該在」，這條決定「在的話，只能在一個地方」，本質都是「別讓不必要的東西占用常駐 context／別讓同一件事有兩份可能漂移的版本」。真實案例：Ingest/Query/Lint 完整演算法從 CLAUDE.md 卸載到 skill（規則精修捕捉檔）；report-format.md 沒跟上 hoard-query 演算法精修導致兩邊不同步（規則精修捕捉檔「問題七」）。
3. 內容要具體、清晰、可判斷
（原報告五「規則必須可以判斷」＋六「條件→動作」＋八「不要用沒定義的抽象詞」＋十二「Definition→Rule→Example」＋十九「少用需猜意圖的術語」——五條顆粒度不同，本質是同一件事，統一收斂成一條）
測試法：兩個不同的 Claude 看同一句規則，會不會做出不同行為？會，就不夠具體。
實作手段：
- 句式：寫成「當 X → 做 Y」的條件→動作句式，比敘事性說明句更不容易失真
- 詞彙：規則裡的抽象詞如果會改變分支結果，要嘛給操作型定義（順序是定義→規則→例子，例子不能取代定義），要嘛拿掉——拿掉之後操作規則沒有損失，就代表它只是解釋性噪音
4. 從 failure 長出規則，不要從想像長出規則
（原報告二十一，獨立成條——這是唯一講「規則什麼時候該被加進來」的時間軸原則，跟前面三條「規則該長什麼樣」是不同維度）
不要防禦式預先設計：不要因為「萬一 Claude 做了 A」就先加規則防範沒發生過的事。規則該在實際用出可重複的錯誤、確認是跨 session 會再發生的穩定問題後，才加進 CLAUDE.md；否則該進 Skill／Rule／文件，或乾脆不處理。
對應既有原則：知識庫建設哲學「七」、規則品質與判準「二十」同一個「先讓真實需求擠出來再長結構」的原則。真實案例：hoard-commit 一開始漏掉 chaos/ 的 commit staging 範圍，實際踩到才發現、才把「Lint 範圍」跟「commit staging 範圍」分開定義（規則品質與判準「二十四」）。
現有第七篇四原則 → 對照到「真正的原則」
（出自 第七篇 - CLAUDE.md 撰寫原則，2026-08-13 寫，213 行數字已過時待更新為 240）
| 現有第七篇原則 | 對照到 | 說明 |
|---|---|---|
| 1. 給人看的，請放在別的地方 | 第 2 條 | 「給人看的」內容過不了「AI 會不會需要」這把尺 |
| 2. 跟知識庫無關的，放地標就好 | 第 2 條 | 同一把尺的另一種情況，範圍不相關一樣過不了篩選 |
| 3. 每條規則要有明確目的、與觸發機制 | 拆兩半，分入第 2、3 條 | 「明確目的」＝第 2 條的例外（理由要能通過真實判斷依據）；「觸發機制」＝第 3 條「條件→動作」句式 |
| 4. 儘量不要太長 | 第 2 條 | 直接吃現有的 signal-to-noise 分析 |
四條全部落在第 2、3 條，完全沒有碰到第 1 條（CLAUDE.md 是常駐上下文）或第 4 條（從 failure 長規則）——這兩條是這次真正新挖出來的東西，不是舊內容換句話說，第七篇不會只是「原本四條的加強版」。
補充材料（重要，但不算 CLAUDE.md 撰寫原則）
不要照單全收，要有驗證機制
（原報告七「規則要可驗證」）
本質不是「CLAUDE.md 該怎麼寫」，是使用／協作技巧層的東西——底層邏輯是「不要照單全收，要有驗證機制」。可以當文章裡的小補充或使用技巧來寫，但不列入「真正的原則」清單。
定期抓「規則之間矛盾／例外沒講清楚」
（原報告九「分支要盡可能完整」＋十「避免規則彼此矛盾」——九是十最具體的案例，本質都是建立在「已經寫錯」這個前提上的稽核行為，不是動筆當下該遵守的寫作原則）
不是怎麼寫的原則，是寫完之後的維護／稽核習慣：定期檢查 invariant 有沒有連例外一起講清楚、同一個概念有沒有兩處各講一半互相打架。真實案例：我們自己 raw/ 不變性矛盾（規則精修捕捉檔「問題一」）——頂層寫「不得修改或搬移」，但專案歸檔跟 Promote 流程各自有搬移的例外，三處互相打架，最後靠拿掉不必要的耦合（歸檔不再動 raw/）解決，比單純「幫例外開白名單」更乾淨。
不要過度指定實作步驟
（原報告十三）
使用者評估這個前提——「把完整步驟塞進CLAUDE.md」——不是廣泛會出現的使用方式，只是自己剛好這樣設定過，重要性不高，不列入「真正的原則」清單。真實案例跟第 2 條 Ingest/Query/Lint 卸載到 skill 是同一件事的另一個角度。
範圍分工說明（不是原則）
（原報告十四「把永遠需要與任務需要分開」／Progressive Disclosure）
本質是「CLAUDE.md 的內容，負責邊界要劃清」，但這正是我們自己的「五層機制模型」，已經整篇寫成新第六篇《知識庫的 AI 協作內容該有什麼》。這裡不重新展開，只留分工宣告：CLAUDE.md 不是唯一容器，其餘四層（Rules／Skills／Subagents／Hooks）的完整討論見第六篇；第七篇只專講 CLAUDE.md 這一層本身該怎麼寫。
拆檔≠省 context（技術細節，不查證）
（原報告十五）
@import 檔案是否真的會在啟動時整份載入 context，使用者判斷不是通常使用情境，不列入原則，頂多算補充內容。不主動查證，除非之後實際動筆寫進文章。
一個欄位只承擔一個語意維度
（原報告十八）
出發點很獨特——建立在「有 frontmatter」這個前提上，不是廣泛適用的 CLAUDE.md 寫作情境，只是單一使用情境（schema 欄位設計）下該注意的事，不併入原則清單。真實案例：status 欄位曾經混了 track 軌道與文件完成度兩條軸線（規則精修捕捉檔「問題四」）。
加碼發現：disable-model-invocation: true（技術宣稱，不查證）
（原報告結尾）
宣稱 Claude Code Skill frontmatter 有 disable-model-invocation: true 欄位，可以讓 skill 完全不被 AI 自動判斷觸發、也不占用常駐 context，只有使用者手動 /skill-name 時才載入——如果為真，會是把「手動叫用，不自動觸發」這條 instruction layer 的規則，升級成 invocation mechanism layer 的真實案例。不主動查證，除非之後實際動筆寫進文章。