挑出幾篇講用 Claude Code 管理 Obsidian 知識庫(llm-wiki)的架構、起手式與 skill 設計,適合想自己蓋一個的人按順序讀。
- 專案頁:llm-wiki
挑出幾篇講用 Claude Code 管理 Obsidian 知識庫(llm-wiki)的架構、起手式與 skill 設計,適合想自己蓋一個的人按順序讀。

前兩天都在講這個筆記庫的儲存層——搬家的決定,和雲端同步碟咬出來的三類症狀。今天正式介紹它本身。Karpathy 的 LLM Wiki 架構是 Raw / Wiki / Schema 三層分工,我加的是「域優先」——用生活域當頂層資料夾,讓查詢有路徑可循,LLM 每次只讀 2 到 4 個檔而不是掃全庫。這篇講五個取捨:為什麼不用 RAG、為什麼域優先、為什麼 raw 不到五個檔不准開 wiki、為什麼規範要用 hook 擋、以及 skill 怎麼從原子指令收斂成管線。附三個實際踩過的判斷錯誤。

Day10 結尾給了四句起步順序,今天把它展開成可以照做的版本。CLAUDE.md 201 行逐段盤完之後最反直覺的一筆是:行為準則只佔 14 行,路由與結構佔掉一半。skill 從 9 個開始,現在 15 個,中間有 10 個名字已經退場。這篇講五步起手式、每步配一個我實際付過的代價,12 條寫進 skill 才會生效的使用習慣,加上我實際的 routines(半年只有 42 個活躍天,斷過兩次一整個月)。文末附一段可以直接複製給 AI 的建置 prompt,它會先訪談你 12 個問題,再照你的答案長出你自己的骨架。

vault 從 iCloud 搬到 git 時,防的是兩台機器互相覆蓋;但實際用法已經變成同一台電腦同時開好幾個 Claude session。共用一個工作目錄時 git 不會產生 merge conflict,只會靜默覆蓋。記錄一次真實撞車、一份八條的協定和它第一版建立在錯誤前提上的地方、log 月檔改用 merge=union 之後合併仍然出錯的兩種情況,以及接下來可能遇到的問題和走法。

用 git 同步 vault 十天後的四個觀察:log 和 TODO 這種每個動作都會碰的檔一直衝突、手機能互動很實用、本機所有 session 都踩在 main 上互相卡住、GitHub 網頁可以直接當閱讀介面。今天一次 push 被另一個 session 沒 commit 的變更擋下來,於是把「每個 session 都開 worktree、不分任務大小」寫成規則,並用 SessionStart 與 PreToolUse 兩層 hook 擋住在主目錄寫檔。記錄過程中的取捨(為什麼不是看情況才開、為什麼保留 Obsidian 自動 pull、規則之外要不要用 hook 硬擋、收件重複要查 git 歷史還是另記一本帳、過期的決策檔怎麼刪),四個坑(hook 擋到自己要寫的另一個 repo、剛開的 worktree 被判成可清、log 同一個 hunk 混著兩個 session 的條目、在 worktree 裡長指令被拒),以及接下來要觀察的九件事。

vault 的 log 月檔從根目錄一份改到切月檔加 union,每次都在解衝突;git 和 PR 已經記下同樣的東西,我也從不翻,於是停寫、交給 git。

停寫 log 月檔只改了指示和資料;用 hook 擋卻被審查退回三次:讀工作區會執行程式、走路徑會連上網路、解析 shell 永遠有漏洞,最後只留下 Write/Edit 的字串比對。
東西怎麼進到 vault:隨時捕捉,有東西進來時再觸發整理。
| 節奏 | 做什麼 | 讀哪裡 |
|---|---|---|
| 隨時,有東西進來時觸發 | inbox-triage | Day11 Routines、Day17 範本 |
文章準備中。

Day11 列過 llm-wiki 的 15 個 skill,但只有名字、一句話用途和行數。今天附上 inbox-triage、wiki-query、wiki-build、note-enrich、note-explore、vault-maintain 的範本,拿掉個人資訊和我這個 vault 特有的部分。每個 skill 附上什麼時候用、自己客製化時要注意哪幾條。把 llm-wiki 看成一台引擎:wiki-build 是核心,inbox-triage 負責加燃料,wiki-query 產出答案,vault-maintain 定期檢修,note-enrich 和 note-explore 分別顧思考的廣度與深度。另外說明其他 skill 為什麼不放,以及一個容易誤解的地方:這六個不是各自獨立的指令,它們共用 index.md、log、TODO.md 幾個慣例,也會互相呼叫。

note-enrich 跑完的 raw 常常已經夠格當 wiki 頁,但要升格時卡在一件事:原本「就近融入」的規則讓我寫的句子和網路查來的句子混在一起,升格只能動 LLM 寫的部分,卻分不出是哪幾句。這篇記錄把輸出改成「原文一塊、## 補充一塊、## 來源清單」的取捨,為什麼不從 raw 全面改、已經 enrich 過的 20 幾篇為什麼不回頭拆,以及 enrich 結束時怎麼判斷該不該提議 wiki-build –promote。也記錄兩份規格各寫各的 frontmatter,悄悄分歧出 kebab tag 和被挪用的 source 欄位。

Claude Code 新推出了 mod,我試著導入 llm-wiki。主軸是為什麼要用 mod:先分清 skill、hook、MCP、plugin、mod 各管什麼,再從最直觀的介面開始,在 session 裡畫出 vault 儀表板:側邊面板列出 TODO.md 未完成項與近期新增 wiki,點項目就把對應 skill 指令填進輸入框、點 wiki 頁直接在 Obsidian 開;面板下半部畫各域 wiki 數與 raw 堆積;輸入框上方的橫條放今日隨機三頁,狀態列放待辦/Inbox/本週新增數。接著往下看 mod 的 hook:旁觀、改寫、接手三種行為,以及它排在既有守門 hook 前面這件事。也記錄怎麼算「近期新增」、怎麼打開 Obsidian、mod 放在哪、raw 堆積的第一版為什麼不能用,以及幾個驗證錯誤。

接續 Day26,這篇寫 navi 這個 mod 的畫面設計:橫條、狀態列、輸入框、側邊面板各自負責一種注意力;統計分頁以「哪裡還沒連起來、哪裡值得再寫、書的概念流到哪些域」三個問題分區,每個數字旁邊都附一個只填不送的動作;趣味分頁放單篇事實。記錄每個畫面要我關注什麼、門檻怎麼定、以及看到畫面之後改掉的地方。

再寫一個 mod:thinking-line 在 Claude 執行中接管 spinner 那一列,顯示細分的階段、step 序號、平行工具合併、每個 subagent 在跑什麼,以及輸出 token 與每秒速度。記錄 Spinner 能改哪些欄位、token 為什麼一半是實值一半是估算、chunk 太密怎麼節流,以及桌面版畫不出多行時改走的路。

我的 vault 有兩個都叫 navi 的工具,這篇記錄怎麼用一輪拷問定下分工規則:綁在 Claude Code 輸入框、session 或 git 上的留在 mod,其餘交給 Obsidian,以及搬家時數字對不起來、手機版沒有輸入欄這幾個坑。
進來的東西整理好之後,靠兩種排程把整個 vault 維持住:
| 節奏 | 做什麼 | 讀哪裡 |
|---|---|---|
| 每週 | vault-maintain 巡檢 | Day17 範本、Day44 |
| 每月 | claude-doctor 健檢 | Day31、Day37 |

vault 的 CLAUDE.md、16 個 skill、navi 與 hooks 累積了一個月,換到新模型後沒有人檢查它們還合不合用。這篇記錄 /claude-doctor 的設計:為什麼內建的 /doctor 不夠、為什麼每次稽核前都先做一輪研究、換模型的提醒為什麼從 hook 搬到 navi 狀態列、又為什麼不必每 30 秒檢查一次。支線是第一輪稽核的結果:CLAUDE.md 從 251 行瘦到 179 行,10 個 skill 的強調標記從 476 個降到 41 個。也記錄稽核腳本把 glob 當成粗體、以及 subagent 回報的問題本身判斷錯的兩個坑。

/claude-doctor 交出 7 條應改、17 條建議之後,接著是照單修。這篇記錄修正輪裡的三個取捨:報告原本不在 repo 裡、接手時得回 GitHub 去撈,改成一次健檢一個檔;與其修好沒在用的 skill,不如直接刪掉 6 個;vault-maintain 每次在暫存區重寫掃描腳本、每筆修補都派 agent 覆核,改成一支常駐的 lint.py,修完重跑它就是驗證。也記錄 lint.py 第一次跑全 vault 時數字三次都不對的原因。

llm-wiki 的 raw 是還沒整理成 wiki 的素材,沒被任何 wiki 引用就算「堆積」,儀表板會一直標出來。這篇記錄怎麼讓用不到的 raw 退場:先修掉堆積數的誤報,再用 frontmatter 的 status: retired 標記退場(不刪不搬),接著為「退場太多」補上三道關卡:理由必填、滿 180 天又沒人連入就列出建議刪除、退場比例過高時狀態列提醒。也記錄第一批 9 篇剛標完退場,當天就被 wiki 引為來源而撤回的經過。

vault 儀表板 navi 只活在 Claude Code 的終端機裡,打開 Obsidian 看筆記時什麼也看不到。這篇記錄 Obsidian 版 navi 的做法:為什麼不用 Dataview、也不產生靜態 Markdown,而是寫一個免建置的小外掛隨 git 同步;健診頁的健康分數怎麼扣分、趣味頁的今日三頁與「今日媒人」怎麼算。也記錄用 mock 資料驗證時的兩個坑,以及真的在 Obsidian 打開後,分數從 mock 的 89 掉到 66:mock 只認 wikilink,漏掉了從 Heptabase 搬過來、沒整理過的約 183 條 Markdown 死連結。

andrej-karpathy-skills 用九個「LLM 做錯 vs 該怎麼做」的範例說明行動前陳述、最小化、手術式修改、目標驅動驗證四條原則。我把九個範例逐一拿來對照 llm-wiki vault 的 CLAUDE.md:哪些失敗模式在這份設定裡有對應的規則、規則長什麼樣,哪一個完全沒有對應。