在檢討的時候 AI 產出了這樣的一份報告，我認為這是一個很好的範例。

讓大家看看個人知識庫在實際工作情境是如何幫助使用者的，也順便讓大家知道第九篇寫的，Git 與建設歷程帶來的幫助，可不是空穴來風。

這段報告是全 AI 產製，但內容 100% 出自我的經驗。

有興趣的可以看完，沒興趣的可以跳過，分享完報告之後我會接著寫：

09/15-09/16 CLAUDE.md／skills 大改後，使用者回頭檢討這波改動，這份捕捉檔整理討論過程中的分析與整理。任務型，檢討告一段落後可刪除或視內容決定是否 Promote。

一、為什麼做出這麼大的改動（根因鏈）

不是單一 bug 觸發過度反應。真正驅動是一段時間累積的操作面痛點：某個 skill 沒有照著流程跑完、執行過程中 AI 對任務的理解開始被新進的 context 污染、執行方向跟使用者要的完全不一樣。這些反覆出現的小問題逼使用者去審視整個 harness，過程中接觸到 Harness Engineering 概念（使用者的理解：「管理 Agent 讀取的上下文」），一路查下去才確認 CLAUDE.md 與 skills 本身有很多結構性問題。

具體症狀案例（「七十七」記的起點）：AI 曾把管「頁面命名」的規則跨層級套用去否決一個「主題命名」提案——規則沒標明適用範圍，AI 只能自己猜規則管到哪，猜錯了。

詳細記錄見 [[evergreen/topics/DragonsHoard建設歷程/架構與流程|架構與流程]]「七十七」「七十八」。

二、現在的 Hoard 現狀（量化對比）

現在的四層：

• Global／Routing（CLAUDE.md，68 行）：角色定義、4 條行為邊界、語言慣例、一張 routing 表。
• Workflow（12 支 .claude/skills/*/SKILL.md，平均 26 行）：做什麼、幾個步驟、呼叫哪個 spec／script。hoard-lint 是這波新拆出來的獨立 skill（原混在 hoard-commit 裡的結構健檢）。
• Object spec（.claude/specs/ 六份：wiki-page／raw-lifecycle／chaos-capture／materials／claude-authoring／public-site-eligibility）：跨檔案多消費者規則的單一事實來源。public-site-eligibility.md 是 09/16 才補的，把誤留在 workflow 層的公開內容判準搬正。
• 新增的機械層：wiki_link_check.py——孤兒頁面／死鏈（正向+反向）／ambiguous 連結／新增頁面最低連結數，四項機械判斷，hoard-lint 讀 exit code 決定要不要往下走。

審視時抓到並已修正兩處文字瑕疵：hoard-commit description 殘留編輯指令文字「只留「」」、hoard-lint description 多打一個句號。

三、大改前做得不好的地方

依據稽核紀錄 raw/evergreen/topics/LLM Wiki/CLAUDE.md 重構分析.md 與「七十七」：

1. 依賴方向是反的：5 支 skill 自己的規格都寫「見 CLAUDE.md」，skill 專屬規格被迫常駐在 global 檔案，估計佔 CLAUDE.md 四成內容。
2. 同一物件的規則散在多處，且沒標適用範圍：「wiki 頁面」規格分散四處，「raw/assets 生命週期」講三次，「evergreen／project 分類」講三次。「連結慣例」沒寫清楚「僅限頁面命名，不含 topic/project 目錄名稱」，直接導致上述根因案例的誤用。
3. Always-loaded 預算雙層重複：11 支 skill description 總共約 3300 字元，CLAUDE.md「工作流程」「Git」「Promote」「同步」四段又把同樣 routing 重寫一次。
4. 規格早就跟現實漂移，沒機制抓：log.md 檔首三欄格式 vs CLAUDE.md 舊版兩欄格式不一致，查證後確認是 CLAUDE.md 舊版寫錯、從建庫第一筆起就沒被真正遵守過。
5. 同時服務 AI 執行與人類閱讀兩種受眾：CLAUDE.md 裡 7 處「決策過程見」wikilink 對 AI 是死重量，只對人類讀者有用，兩邊沒分開。
6. 第一輪重構本身也犯了同一種錯：曾把 Object spec 內容直接複製進五支 skill，違反「消費者 ≥ 2 就該獨立」判準，等於把重複從「CLAUDE.md → 各處」換成「多支 skill → 各處」，是被回頭抓出來才改正。
7. 寫作準則本身違反自己訂的準則：舊版「只寫行為」第 2 條，條文本身卻混進了理由說明。

一句話總結：根本問題不是「內容太多」，是「規則沒有標明自己管什麼範圍、也沒有標明誰在用」，導致同一件事被抄了好幾份、AI 會拿錯層級的規則去套用不該套用的情境。

四、大改前的方向 vs 大改的方向：不是同一個維度

使用者確認記憶：大改前處理的方向是「把 CLAUDE.md/skills 寫得更方便照做」並要求「AI 有產出、執行有依據」。查證屬實，對應到具體條目：

• 「二十五」2026-08-23「規則有效性判準」：兩條判準——觸發綁定可機械判斷的事件（對應「執行有依據」）、執行後留下具體可驗證的產出（對應「AI 有產出」）。當天逐條檢查 CLAUDE.md 全文，砍掉好幾條「定義了但沒用」的規則。
• 「三十四」2026-09-01「嚴謹度」判準：判準要能逐項套用、條件分支互斥、保持扁平的「條件→動作」敘述，逐條套用重寫既有規則。對應「寫得更方便照做」。
• 「五十八」2026-09-08：把這套水準從 Query 推廣檢查其餘六個 skill。

這輪（08-23～09-08）處理的是單條規則的品質——這條規則本身寫得夠不夠精確、能不能被機械觸發、有沒有可驗證產出。「七十七」那波不是同一個維度——抓到的問題是規則之間的關係：同一件事被寫了好幾份、沒標明誰該讀、依賴方向反了。先前那輪已經把每一條規則磨得夠利，但沒處理「這些規則該放在哪一層、誰是它的消費者」，所以磨得再利的規則還是會被複製四份、還是會被跨層級誤用。

五、做了什麼（四個具體動作，供第二十三篇逐項展開）

使用者事後回想這波大改分四塊；以下逐項補上細節。數字皆為重新量測的精確值，非估算——跟「七十七」記的約略數字有落差時以這裡為準（見下方各項備註）。

1. CLAUDE.md 四層重構，瘦身到只剩 Global／Routing

• 起點：AI 曾把管「頁面命名」的規則跨層級套用去否決一個「主題命名」提案——規則沒標明適用範圍，AI 只能自己猜規則管到哪，猜錯了。
• 四層定義：Global／Routing（留在 CLAUDE.md）→ Workflow（.claude/skills/*/SKILL.md）→〔需要時〕Object spec（.claude/specs/ 或物件自我描述）。單向依賴：Global → Routing → Workflow →〔需要時〕Object spec，Routing 也可以直接指到 Object spec。
• 過程犯過一次同樣的錯：第一輪把 Object spec 內容直接複製進五支 skill，違反「消費者 ≥2 就該獨立」判準——等於把重複從「CLAUDE.md → 各處」換成「多支 skill → 各處」，是回頭被抓出來才改正，不是一次到位。
• 結果（重新量測，精確字元數）：CLAUDE.md 254 行／15156 字元 → 68 行／6617 字元；只剩角色定義、4 條行為邊界、語言慣例、一張 routing 表。

2. Skills 完整重構（分兩波，都在 09-16）

• 上午（d63f67c）：拆出 hoard-lint 為獨立 skill，統一結構健檢職責（原本混在 hoard-commit 裡）；hoard-archive／hoard-ingest／hoard-materials-sync／hoard-pull／hoard-status 同步拿掉跟 description／CLAUDE.md routing 重複的觸發條件敘述。
• 下午（afbecef）：精簡 hoard-materials-sync／hoard-polish／hoard-promote／hoard-pull／hoard-status／hoard-title／hoard-ingest 步驟，把跟既有 spec 或方法論重複的敘述改成「委派讀取當下規則」，刪掉被機制取代或跟 description／routing 重複的「邊界」章節；hoard-public-site-sync 步驟改寫並新增 public-site-eligibility spec，把公開內容資格判準從誤留在 workflow 層的位置搬回 Object spec 層。
• 結果（重新量測，精確字元數，取代「七十七」記的約略數字「約3300→約1362」）：11 支 skill description 總字數 3310 字元 → 現在 12 支（新增 hoard-lint）共 562 字元，降幅約 83%。

3. 可機械化內容抽成 scripts，不依靠 LLM 執行

• 具體對象：wiki 連結結構檢查——孤兒頁面、正向＋反向死鏈、ambiguous 連結、新增頁面最低連結數，共四項。
• 之前：這四項檢查靠 AI 讀過一遍 wiki 自己判斷，容易漏、容易被當下的 context 干擾判斷品質。
• 之後：新增 xcripts/wiki_link_check.py（417 行），hoard-lint 只需執行 python xcripts/wiki_link_check.py，依 exit code 處理——0 通過；1 讀 stdout 的 JSON 回報 orphan／deadlink_forward／deadlink_reverse／ambiguous／minlink 五類異常；2 script 本身執行失敗，停止並回報 stderr。
• 這是「引導 vs. 指令堆疊」判準最直接的落地：不是把檢查步驟寫得更清楚給 AI 照做，而是把能被機械判斷的部分整個搬出 LLM 執行範圍，讓「有沒有異常」變成程式回傳值，不是 AI 的當場判斷。

4. Object spec 抽取

• 起點：同一物件的規則散在多處，且沒標適用範圍——例如「wiki 頁面」規格分散四處、「raw/assets 生命週期」講三次、「evergreen／project 分類」講三次；「連結慣例」沒寫清楚「僅限頁面命名，不含 topic/project 目錄名稱」，直接導致上面第 1 項的根因案例。
• 兩種定位方式：有天然單一檔案的用自我描述（log.md、index.md、建設歷程路由頁檔首）；跨檔案多消費者的新建 .claude/specs/。
• 目前 6 份：wiki-page／raw-lifecycle／chaos-capture／materials／claude-authoring／public-site-eligibility（最後一份是 09-16 下午新增，見上方第 2 項）。
• 判準：消費者數量 ≥2 就該獨立成 spec，不要複製貼上到每個消費者——第 1 項提到「過程犯過一次同樣的錯」就是違反這條判準的具體案例，後來才用它反過來修正自己。

報告結束，有因有果，有實作方式，有完成數據，有理論，有影響內容，說真的除了這份報告我沒什麼要補充的。

除了懶得看報告，或者不想看 AI 產出的內容的讀者

我這邊幫大家抓這整份報告的重點。

AI 的異樣感

對任務的理解與回答開始被新進的 Context 污染之後，必然會發生的一件事：

變笨

寫好的規範會突然不照著做、平常的問答變得莫名其妙，想必常用 AI 的人時不時地會感受到

這些明明很聰明，但又很笨的現象。我稱之為「AI 的異樣感」。

解決方式

將所有餵給 AI 的執行內容（例如 CLAUDE.md、Skills）分成四類：

• Global／Routing 全任務內容／對應路線表：AI 的角色定義、行為邊界、語言慣例、以及各種情境發生時，該去哪裡找 Context。
• Workflow 工作流：做什麼、幾個步驟、呼叫哪個 spec／script。大部分可被寫成 Skills。
• Object spec 物件文檔：跨檔案多消費者規則的單一事實來源。例如 Wiki 文檔的規格、範圍、交叉引用的方式等。
• 能機械化的：所有可以寫成機械化步驟的內容，將用程式改寫為腳本，不依賴 LLM 而是依賴程式執行。

具體調整數據

可以看到，不只大幅節省了 Always-loaded 的內容，也確保資訊只在需要時導入 Context。

這樣改動，AI 的回答更理智、執行效果更可靠、維護知識庫成本直線下降、與 AI 共事的抓狂率更低。

而且，像是打掃一樣，專案更乾淨，乾淨就是很好。