CLAUDE.md 撰寫原則
這頁記的是「CLAUDE.md（AI 常駐上下文檔案）該怎麼寫」這件事本身的通用原則，適用於任何 AI 維護的個人 wiki，不限 DragonsHoard 這個實例——跟 Ingest 同一種定位（行為的通用理論，不是某個專案的套用紀錄）。DragonsHoard 自己套用這些原則時具體踩過的坑、修過的規則，歸 DragonsHoard 建設歷程 對應章節，這裡只做交叉引用，不重複記內容。
最初目的：iThome 鐵人賽第七篇（CLAUDE.md 撰寫原則）要大幅重寫，起因是使用者另外請 ChatGPT 整理了一份 21 條＋核心命題的 CLAUDE.md 撰寫原則報告。逐條跟 DragonsHoard 既有判準（規則有效性／精簡性／嚴謹度、五層機制模型）交叉核對，避免文章只是既有第七篇四原則的換句話說。
怎麼做：逐條 review 21 條原文，跟現有第七篇四原則放在一起交叉比對；過程中一度嘗試把 21 條聚類成 8 類，被判定下判斷太早、作廢，改回逐條討論，一條一條決定獨立、合併、降級成補充材料或捨棄。過程中修正過一次 AI 自己的錯誤——AI 曾經發明一套抽象的「效益測試」來解釋某個例外該不該成立，被指出這是憑空推導、不是真實依據，改用已經記錄過的真實案例（協作與元規則「二十三」續）取代。
最後變成什麼樣：21 條收斂成 4 條真正的原則。
四條原則
1. CLAUDE.md 是常駐上下文，不是規則或文件
CLAUDE.md 本質上是配置給 AI 的常駐上下文，不是規則或文件；就算寫成「規則」「MUST」的形式，AI 收到的仍只是 context 的一部分，不是機械化照做的指令。「規則」是寫的人自己的分類幻覺，對 AI 不存在特殊待遇。這是框架層，後面每一條「為什麼」成立都是這個本質的推論結果。
正因為只是 context，再怎麼加重語氣（MUST、NEVER、IMPORTANT）都不會讓它變成真正的強制執行——真正不能失敗的硬約束要交給 hook／permission 這類機制；濫用強調詞只是自欺。真實對照：raw/ 唯讀從技術強制改回文件約定（架構與流程「十二」），承認的正是這件事。
2. 收錄門檻是第一條的延伸：只放值得當常駐 context 的內容
因為 CLAUDE.md 是常駐上下文，裡面的內容應該只有「值得當作常駐 context」的內容。長度是這個篩選確實執行後的結果，不是篩選的目的——不是「怕太長所以要篩」，是「每條都認真篩過，長度自然被控制住」；篩選是寫入當下的關卡，不是寫完之後回頭砍字數。200 行是警戒線，不是正確性邊界。
例外：規則可以附一句短理由，判斷不用抽象測試公式，直接看真實案例——raw/ 唯讀附「因為是 provenance layer」這句沒有刪，因為是真實記錄過的判斷依據（協作與元規則「二十三」續，2026-08-21）：這條規則主要是講給 AI 聽，邊界沒明講 AI 可能「順手」改動來源檔。相對地，純歷史敘事該砍掉、送去建設歷程，不是丟棄，是換到之後精修時真的會回頭查的地方——對應「CLAUDE.md 不該內嵌演變歷史」（協作與元規則「二十三」）。
單一 Source of Truth：同一份資訊不要存在兩個地方，同一個篩選邏輯的另一面——收錄門檻決定「該不該在」，這條決定「在的話只能在一個地方」。真實案例：Ingest/Query/Lint 完整演算法從 CLAUDE.md 卸載到 skill（規則品質與判準）；report-format.md 沒跟上 hoard-query 演算法精修導致兩邊不同步。
常駐內容的四層分層判準：單一 Source of Truth 決定「內容只能在一個地方」，但沒回答「先判斷這件事本身該不該常駐」。可操作的判準是四個問題：Global（任何情境開始前都必須知道什麼）／Routing（現在這個情境，接下來去哪裡取得 context）／Workflow context（這個動作要怎麼完成）／Object spec（被操作的東西本身有什麼規則）。依賴方向單向：Global → Routing → Workflow →（需要時）Object spec，Routing 也可以直接指到 Object spec，不必繞經 Workflow。真實案例：DragonsHoard 這次重構前，CLAUDE.md 混雜四層在同一份常駐文件裡，物件規格（如 wiki 頁面 frontmatter 合法值）被迫常駐，即使只有 Ingest／Lint 兩支 workflow 會用到；重構後只剩 Global＋Routing 常駐，其餘按需讀取（架構與流程「七十七」）。
判斷某條規則該不該獨立成 Object spec，用消費者數量當判準：兩個以上 workflow 都要引用同一段規則，這段規則就該獨立成單一文件，不該被複製進任一支 workflow——複製會導致其中一份被改動時另一份沒跟上，比沒有 Source of Truth 更危險，因為表面上看起來每支 workflow 都「有」這條規則，實際上已經分岔。獨立出來的 Object spec 建議統一套用骨架：Object（物件名稱）／適用範圍（明確排除鄰近但不適用的情境）／規格本體／消費者（哪些 workflow 會讀）／驗證方式（機械可查 vs 需要語意判斷）。「適用範圍」這個欄位不是形式，是從真實 failure 長出來的：DragonsHoard 曾經把管「個別頁面命名」的規則跨層級套用去否決「主題命名」提案，因為規則寫的時候沒有明講管到哪裡，AI 只能自己猜（架構與流程「七十七」）——這也同時是第 4 條「從 failure 長出規則」的另一個真實案例，不是設計時預想出來的。完整重構過程與逐段分類紀錄留在原始任務型捕捉檔的 git 歷史（raw/evergreen/topics/LLM Wiki/CLAUDE.md 重構分析.md、raw/evergreen/topics/LLM Wiki/CLAUDE.md 規則範圍判讀可靠性 捕捉.md），不在此重複展開。
3. 內容要具體、清晰、可判斷
測試法：兩個不同的 Claude 看同一句規則，會不會做出不同行為？會，就不夠具體。
實作手段：句式上寫成「當 X → 做 Y」的條件→動作，比敘事性說明句更不容易失真；詞彙上，抽象詞如果會改變分支結果，要嘛給操作型定義（順序是定義→規則→例子，例子不能取代定義），要嘛拿掉——拿掉之後操作規則沒有損失，就代表它只是解釋性噪音。
4. 從 failure 長出規則，不要從想像長出規則
不要防禦式預先設計：不要因為「萬一 AI 做了 A」就先加規則防範沒發生過的事。規則該在實際用出可重複的錯誤、確認是跨 session 會再發生的穩定問題後，才加進 CLAUDE.md；否則該進 Skill／Rule／文件，或乾脆不處理。這是唯一講「規則什麼時候該被加進來」的時間軸原則，跟前三條「規則該長什麼樣」是不同維度。
對應既有原則：知識庫建設哲學「七」、規則品質與判準「二十」同一個「先讓真實需求擠出來再長結構」的原則。真實案例：hoard-commit 一開始漏掉 chaos/ 的 commit staging 範圍，實際踩到才發現、才把「Lint 範圍」跟「commit staging 範圍」分開定義（規則品質與判準「二十四」）。
跟現有第七篇四原則的關係
既有第七篇《CLAUDE.md 撰寫原則》四條（給人看的放別的地方／跟知識庫無關的放地標／每條規則要有明確目的與觸發機制／儘量不要太長）逐條對照後，全部落在第 2、3 條——第 1、4 條是這次真正新挖出來的框架，不是舊內容換句話說。
篩掉的部分
21 條原文裡有 7 項判定不進上述四條，理由各異——有的是使用技巧層而非撰寫原則（如「不要照單全收，要有驗證機制」）、有的建立在特殊前提上不是廣泛情境（如「一個欄位只承擔一個語意維度」建立在有 frontmatter 的前提）、有的是同一案例的另一個角度、有的是未查證的技術宣稱。逐條理由留在原始任務型捕捉檔的 git 歷史（raw/evergreen/topics/LLM Wiki/CLAUDE.md 理解整理 捕捉.md），不在此重複展開。