RambleWiki

第六七篇 claude.md 捕捉

閱讀時間約 24 分鐘

第六七篇捕捉檔——CLAUDE.md 該有什麼與怎麼寫拆分

單篇任務型捕捉檔，綁定 iThome 鐵人賽第六、七篇（CLAUDE.md 主題拆分為「該有什麼」與「怎麼寫」兩篇）。內容併入 wiki 對應頁面（_index.md 進度表、決策歷程等）後，整份刪除，不保留本體。

跟另一個進行中任務的關係：「依照目前理解審視 DragonsHoard 現有 CLAUDE.md」這件事由另一個 session 處理，對應捕捉檔 chaos/CLAUDE.md 規則精修 捕捉.md，本檔不重複處理，只在上面「順便發現」列出的兩點（213 行過時數字、Lint/Query 程序放置方式）跟該任務有交集，實際調整以那份捕捉檔為準。

篇章定位（2026-09-06 討論定案）

  • 起因：潤稿現有第六篇（CLAUDE.md 撰寫四原則）時發現，四原則講的是「怎麼寫得好」的紀律層（別放什麼、要有目的觸發、別太長），不是「知識庫的 CLAUDE.md 該有什麼」這個內容規格層，兩者性質不同。
  • 查證目前大眾對 CLAUDE.md 內容的共識（Anthropic 官方＋社群），只到「軟體專案取向的類別清單」層級（commands/style/testing/repo 禮儀等），沒有知識庫場景的對應版本，判定值得補。
  • 決定拆成兩篇：新「第六篇」＝知識庫的 CLAUDE.md 該有什麼（內容規格清單），現有第六篇「CLAUDE.md 撰寫四原則」全文不動、篇號後移成「第七篇」；連帶現有第七～十六篇整批遞補為八～十七（跟決策歷程「二十六」五/六篇分拆同一種遞補規模）。
  • 跟第十一篇（直接公開作者 CLAUDE.md 全文）互補，不重複：新第六篇是抽象框架（該放什麼的判斷依據），第十一篇是具體案例（真的長什麼樣），順序上框架在案例之前，讀者才看得懂第十一篇那份 CLAUDE.md 為什麼那樣寫。

素材來源

五層機制模型（CLAUDE.md／.claude/rules/／Skill／Subagent／Hook 該放哪一層的判斷框架）＋兩次 AI 翻車實測案例，原始出自 chaos/模組二_白板.md（決策歷程「十二」有記錄，但該檔案目前在 chaos/ 資料夾裡找不到，需要確認素材下落）。

外部共識研究（2026-09-06，使用者與 ChatGPT 討論參考）

大眾對 CLAUDE.md 內容的共識濃縮成五類，共識程度只到「選擇標準」跟「內容分類」層級，沒有共識到「固定模板」層級：

  1. 專案操作指令（可直接執行，如 build/test/lint 指令）
  2. Claude 無法單靠讀 code 穩定推斷出來的專案慣例（非顯而易見）
  3. Hard constraints（不要做錯的事，比「寫乾淨的 code」這類空泛要求資訊密度高得多）
  4. 極簡 project map／architecture（官方建議約三句話，不是長篇介紹）
  5. Gotchas（專案特有、容易踩的坑，被認為是價值最高的一類）

明確不該放的：完整 API 文件、完整 style guide、README 重複內容、專案歷史/changelog、大量 code example、偶爾才用的工作流程、單一 module 才需要的規則——多步驟 procedure 應該做成 Skill，特定 code path 規則放 .claude/rules/，不常用的 reference material 不進 CLAUDE.md。

判斷樹（決定一條資訊放哪）：每次 session 都需要？→ CLAUDE.md；否則是不是某類檔案才需要？→ Rules；否則是不是某個任務/流程才需要？→ Skill；否則→一般文件/知識庫。

收斂成一條底層原則（本次討論歸納，非 ChatGPT 原文）：五類可以再收斂成一條篩選原則——「Claude 沒辦法穩定自己推斷出來，而且每個 session 都用得到」，五類只是這條原則在不同情境下的具體展現（指令＝流程層、慣例＝選擇層、禁止＝風險層、架構＝地圖層、坑＝經驗層）。

確認的落差：整份共識內容從頭到尾沒有脫離軟體專案語境（pnpm/API handler/migration/Docker 等），沒有處理「知識庫」情境，證實新第六篇要寫的東西是真正的空缺，不是漏查。

底層邏輯／原則整理（2026-09-06，基於外部共識研究收斂）

從上面五類共識收斂出的框架，刻意跟 code/build/API 這類詞彙脫鉤，方便直接套進知識庫情境：

核心：CLAUDE.md 是「常駐稅」——不管這次任務用不用得到，內容都要被讀一次，成本固定、效益浮動。夠格放進去的東西要通過「值不值得每次都繳這筆稅」的篩選。

篩選必要條件（兩個都要，缺一不可）：

  1. 高頻——幾乎每次工作都會碰到，不是只有特定任務才需要
  2. 不可推斷——無法從當下看得到的東西（程式碼、資料夾結構、既有文件）自己穩定推出來，只活在使用者腦中或機構記憶裡

只滿足一個都不夠格：高頻但可推斷不用寫；不可推斷但低頻該放別的地方，不該常駐。

通過篩選後落在五種知識類型（不是必填欄位，是同一條篩選邏輯的五種展現）：

  1. 程序型（怎麼做）——重複、每次都用同一套步驟的操作
  2. 選擇型（挑哪個）——多個都合理的做法中，這裡選定了哪一個
  3. 禁止型（不准做）——會造成傷害或不可逆後果的邊界
  4. 定位型（在哪裡）——整體輪廓，讓人知道大概該往哪找
  5. 經驗型（小心這個）——表面合理、實際是陷阱的反直覺事實

篩選之後還要卸載：多步驟只在特定任務觸發的程序 → 卸載成獨立可呼叫單元（Skill 的角色）；只對某子集有效的規則 → 卸載成範圍限定的規則（Rules 的角色）；不是每次都要但需要時能查的參考資料 → 留在一般文件，不進常駐層。CLAUDE.md 留下的是「卸載完剩下的最小核心」。

候選偵測是動態的：判準不是「我覺得這重要」，是行為訊號——「這件事我發現自己每次都要重講一次」，不是坐下來預先想像會用到什麼。

格式沒共識，但有共同底線：沒有固定模板，但內容是 context 不是 configuration（寫了不保證 100% 被遵守），檔案越長重要的東西越容易被稀釋——長度是負債不是資產。

跟 DragonsHoard 既有內容的關係：CLAUDE.md 裡已有的「CLAUDE.md 寫作準則」（可執行／只寫行為／判準明確／保持扁平）是原則層（怎麼寫得好），對應規劃中的第七篇；這裡整理的是內容選擇層（該放什麼），對應新第六篇，兩者不重疊，再次印證拆分方向正確。

範圍修正：從「CLAUDE.md 該有什麼」擴大成「跨工具分工」（2026-09-06）

討論到一半發現問題本身要重新定義：

  • 五層機制模型，不是三層：CLAUDE.md／Rules（.claude/rules/）／Skills／Subagents／Hooks 共五層，前面只討論到三層（前段 ChatGPT 共識研究本來就只涵蓋到 Skill，沒提到 Subagent／Hook）。
  • Hook：DragonsHoard 建設歷程有兩次真實評估紀錄（Lint 觸發機制、白板提醒機制），都判定不需要，理由具體且一致：Hook 的強項是「機械、不需語意判斷的保證觸發」，但知識庫規則大多需要 AI 自己判斷情境（語意判斷），跟 Hook 的強項不對盤；raw/ 唯讀保護是例外，該用檔案系統權限做，Hook 留作未來可能加強（架構與流程「十六」）。
  • Subagent：DragonsHoard 裡完全沒有評估紀錄，跟 Hook 不同（那是「認真評估後拒絕」，這是「從沒被拿出來討論過」）。使用者判斷＋AI 判斷一致：知識庫場景不需要——不是巧合沒遇到，是整個 wiki 架構（90KB 閱讀預算、index.md 摘要導航、策展優先於檢索）刻意設計成不需要大量委派讀取，Subagent 原本該解決的問題被架構本身消滅了。唯一保留：一次性超大量遷移可能有邊際價值，但屬罕見情境，不代表常態需要。
  • 問題重新定義：原本問「CLAUDE.md 該有什麼內容」是單一容器的內容篩選問題；正確的問法是「知識庫的協作內容，該怎麼分配到 CLAUDE.md／Rules／Skills？」（用「機制」取代「規則」，避免預設答案一定是宣告型內容）——Ingest/Query/Lint 這類東西是程序型知識，該卸載成 Skill，不是 CLAUDE.md 式規則，用「規則要寫什麼」問法會不小心把它們排除在外。

五層機制，一句話定義（2026-09-06）

  1. CLAUDE.md——always-on，每次 session 自動載入的常駐 context。
  2. Rules（.claude/rules/）——依檔案路徑/類型自動生效的範圍限定規則，符合條件才載入，不是每次都在。
  3. Skills——明確呼叫或情境判斷才觸發的可重複程序，平常不佔用 context。
  4. Subagents——有獨立 context 視窗跟工具權限的子代理，用來隔離／委派子任務，結果濃縮後才回主線。
  5. Hooks——harness 保證觸發的 shell 指令，掛在特定事件上（如 PreToolUse、SessionStart），不需 AI 判斷、機械執行。

下一步討論順序：先列「知識庫的 AI 協作內容，具體有什麼」，再逐項判斷「該放哪一層」——內容盤點在前，分層判斷在後。

知識庫 AI 協作內容盤點（2026-09-06，以 DragonsHoard 現有 CLAUDE.md 為實證基礎）

  1. 資料結構定義——資料夾骨架與各層用途
  2. 分類判準——怎麼決定一則內容屬於哪裡
  3. 核心工作流程——收錄／查詢／健檢的觸發條件、步驟、輸出格式
  4. 內容模型／schema——固定欄位、允許值、連結寫法慣例
  5. 維護規則——輔助結構（索引/時間軸）什麼時候更新、怎麼歸檔
  6. 邊界與禁止事項——AI 不能自己動的範圍
  7. 協作風格——溝通語氣、決策權分配、用語慣例
  8. 元規則——規則本身該怎麼寫才合格

抽象上是「知識庫的例行動作」的具體命名（DragonsHoard 版本是 Ingest/Query/Lint），對其他知識庫應該也通用，命名可再調整。

八類內容分層判斷（2026-09-06，套用判斷樹：每次都需要→CLAUDE.md／特定路徑才需要→Rules／特定任務才需要→Skill）

類別分層理由
1. 資料結構定義CLAUDE.md定位型知識，幾乎每個任務都要用到當背景，且無法從檔案本身推斷
2. 分類判準拆兩半：判準本身留 CLAUDE.md（短、跨任務通用）；「怎麼一步步做分類決策」的完整程序歸 Skill（屬於 Ingest 一部分）定義 vs 執行程序要分開看
3. 核心工作流程（步驟本身）Skills多步驟、任務觸發、不需常駐，跟 CLAUDE.md 規則精修 捕捉.md 現在推的卸載方向一致
4. 內容模型／schemaCLAUDE.md高頻、任意選擇、不可推斷；但「驗證」執行程序歸 Skill（Lint）
5. 維護規則（門檻/時機）CLAUDE.md份量小，前例：使用者否決過為小規則另開 skill（見觸發機制演變）
6. 邊界與禁止事項理論上適合分流到 Rules（大多是路徑限定：raw/、chaos/、materials/ 各自規則只在碰那個資料夾時相關），但 DragonsHoard 規模小，維持 CLAUDE.md 更划算規模判斷，不是設計鐵律
7. 協作風格CLAUDE.md每次互動都用得到，主觀選擇、無法推斷
8. 元規則CLAUDE.md（結構性例外）自我指涉，規範 CLAUDE.md 該怎麼寫的規則本來就得跟被規範對象放一起，不看頻率

順帶回答 Rules 這層知識庫用不用得到：第 6 類理論上最適合 Rules，但套到 DragonsHoard 實際規模（資料夾就那幾個、每類規則就幾行），分流省下的 token 不夠付「多開一個檔案」的管理成本。跟 Subagent 結論同方向、不同機制——Subagent 是語意判斷跟機制特性不合，Rules 是規模太小、路徑分流效益還沒跑贏維護成本，量大了才會翻盤（例如 raw/ 底下混進好幾種完全不同 schema 的來源類型，各自規則長到值得抽出來）。

跟 DragonsHoard 現況吻合：.claude/ 現在真的只有 skills/，沒有 rules/、agents/，也沒有 hook 設定——五層裡實際在用的只有 CLAUDE.md 跟 Skills 兩層，跟這輪推導結論一致，不是巧合。

真實案例：專案歸檔該不該抽成 Skill，AI 推理錯誤又被糾正的過程（2026-09-06）

  • 背景：chaos/CLAUDE.md 規則精修 捕捉.md 定案後，複查新版 CLAUDE.md（249 行，比舊版 332 行減少），發現「專案歸檔」是個 5 步驟完整 SOP，卻明確寫「歸檔不另設 skill，依上述流程執行」，跟 Ingest/Query/Lint/Git 全部抽成 Skill 的模式不一致。
  • AI 第一次的錯誤判斷：查 wiki/index.md 發現這個 repo 只歸檔過一個專案，判斷「頻率太低，還沒到值得抽出去的門檻」，套用了「份量小的單行規則可以留著」的先例。
  • 使用者糾正，AI 承認錯誤：這個類比套錯了——CLAUDE.md 常駐稅邏輯的必要條件本來就是「高頻」，低頻直接不合格，跟程序長短、抽出去的力氣無關；而且 Skill 平常只在清單裡佔一行 description，抽出去的成本很低，內嵌在 CLAUDE.md 卻是每個 session 都要付的稅，不管這次有沒有要歸檔。低頻不是「還沒資格抽」的理由，反而是「更該抽」的理由。錯誤在於把「這東西該不該存在於 CLAUDE.md」跟「現在動手抽值不值得」兩件事混在一起。
  • 修正結果：使用者已自行動手，新增 hoard-archive skill，把 5 步驟歸檔程序抽出去，CLAUDE.md 對應段落改回一句話指向 skill，跟 Ingest/Query/Lint/Git 模式一致。
  • 寫作價值：這是一次真實的「AI 推理錯了、被使用者當場抓到糾正」的過程，比單純講原理更有說服力，跟系列既有的坦承檢討調性（第十、十一篇）一致，適合直接寫進第六篇當案例。

Rules 什麼情況下推薦使用（2026-09-06）

DragonsHoard 現況：.claude/ 只有 skills/，沒有 rules/，使用者確認「用了成本反而比不用高」，因為資料內容規模不夠大。收斂出的推薦條件，三條同時成立才推薦改用 Rules：

  1. 真的有異質分區——資料夾/檔案類型之間的規則彼此不相干，甚至互相是雜訊（例如 monorepo 裡 Python 後端 vs TypeScript 前端）。
  2. 每個分區的規則量本身不小——量小的話統一放 CLAUDE.md 的常駐成本本來就低到可忽略，做條件式載入反而多一層檔案管理成本。
  3. 實際工作很少同時橫跨多個分區——如果常常同時碰好幾個分區，條件式載入省下的效益會被「反正大部分規則還是要一起載入」吃掉。

DragonsHoard 三條全部不成立：只有一個人、資料夾之間高度互相依賴（Ingest 要同時懂 raw/wiki，Promote 要同時懂 chaos/wiki/raw），每個分區規則本來就短。

什麼情況會翻盤：通常是規模或協作模式變了，不是內容變了——多人共用知識庫、各自只碰自己負責的主題資料夾；或 raw/ 底下混進好幾種完全不同 schema 的來源類型，各自要一整套處理規則；或知識庫大到分裂成好幾個明顯不相干的子領域。這些都是「異質性＋規模」同時出現才會發生，個人單一知識庫本質上很難走到那裡。

新第六篇文章結構定案（2026-09-06）

  • 這篇不講「CLAUDE.md 怎麼寫」，講的是跨五層機制的整體分配問題，範疇比 CLAUDE.md 本身更大、更早：知識庫要能跑起來，得先設定好跟 AI 協作的細節，這篇負責回答「有什麼、放哪裡」，不負責「放進 CLAUDE.md 的東西該怎麼寫得好」。
  • 結構（A-E）：
    • A. 開場——接續第五篇（上下文管理問題），拋出需求：知識庫要能跑，得先設定好跟 AI 協作的細節
    • B. 知識庫需要跟 AI 協作的內容有哪些——八類內容盤點
    • C. 有哪些機制可以承載這些內容——五層機制，一句話帶過
    • D. 最後會用到哪幾層——narrowing down（個人知識庫大多落在 CLAUDE.md／Skills，Rules/Subagent/Hook 現階段用不到，結論帶過、完整推導留建設歷程）
    • E. 具體怎麼設定——八類內容的分層判斷（實際操作方法）
  • 原第六篇（現第七篇）不用推翻：整個 A-E 流程沒有「規則建立／怎麼寫規則」，跟第七篇「CLAUDE.md 撰寫四原則」性質不重疊，兩篇維持獨立。
  • 外部共識研究（五類共識/判斷樹）改歸第七篇：這塊本來就是針對 CLAUDE.md 這一層本身的內容共識，跟第七篇「CLAUDE.md 專講」範疇對得上，不放進新第六篇。
  • 專案歸檔「AI 推理錯誤又被糾正」案例，兩篇都不放：留在本捕捉檔／未來可能併入建設歷程當內部紀錄，不進讀者導向正文。

概念框架階段結論（2026-09-06）

五層機制盤點、知識庫內容盤點、分層判斷三步驟都完成，概念討論告一段落。剩下的工作是等 chaos/CLAUDE.md 規則精修 捕捉.md 那邊定案實際修改文字後，才進入草擬新第六篇正文的階段（見下方待辦）。

順便發現，跟拆分本身無關但需要處理

  • 現有第六篇（未來第七篇）正文「我自己的 CLAUDE.md 是 213 行」已過時，DragonsHoard/CLAUDE.md 現在實際 332 行（2026-08-13 寫稿之後長大），之後潤稿要更新這個數字。
  • DragonsHoard 自己的 Lint／Query 完整多步驟流程目前寫在 CLAUDE.md 正文裡，Skill 檔案只回頭指向執行，跟「多步驟 procedure 該做成 Skill」的共識方向相反——可能就是使用者說「CLAUDE.md 還有調整空間」指的東西，待確認要不要在問題三一併處理。

待辦

  • 確認五層機制模型／翻車案例素材是否還在
  • 討論篇號整批遞補（六～十六→七～十七）的省事執行方式，不要重演上次逐檔手動改的高成本做法
  • 草擬新第六篇正文——已於 2026-09-07 promote 進 wiki，見 文章/第六篇（新）（暫定編號，決策歷程「二十七」），原草稿檔已 git mv 至 raw/projects/iThome鐵人賽2026/
  • 更新第七篇（原第六篇）「213 行」過時數字
  • 決定 Lint／Query 程序放置方式要不要跟著這次一起調整——已在 chaos/CLAUDE.md 規則精修 捕捉.md「決定：Ingest／Query／Lint 卸載到 Skill」定案為「要」，連 Ingest 一併卸載

本檔尚未整份 Promote：仍綁定第六～七篇篇號整批遞補與第七篇過時數字更新兩項待辦，兩者處理完才會清空刪除本檔。