Quartz 4

CLAUDE

8 min read

CLAUDE.md — Vault 操作規範

這份檔案是給未來的 Claude Code session 讀的。它定義這個 vault 的結構、邊界、 工作流程,以及 LLM 在這裡能做什麼、不能做什麼。所有 session 開始前都要先讀過。

1. Vault 概念

這是個結合 Karpathy「LLM Wiki」模式與 Learning How to Learn 學習原則的個人 知識管理系統。核心理念:

  • 三層分離: 原始來源(raw) → LLM 綜合頁(wiki) → 人工學習卡(chunks)。
  • 單向授權: LLM 只能讀 raw、讀寫 wiki;chunks 是使用者領地,LLM 不得寫入。
  • 小步寫入: 任何 wiki 變更都要先跟使用者討論,再落地。
  • 可追溯: 所有 wiki 條目都要回連至 raw 來源或 wiki/sources 摘要。

2. 目錄職責

路徑內容LLM 權限
raw/原始素材(文章 dump、會議筆記、貼上的 transcript)唯讀
wiki/entities/人、公司、工具、協定、規範等實體頁讀寫
wiki/concepts/抽象概念、模式、架構等讀寫
wiki/sources/每個原始來源的摘要頁(對應到 raw/ 的某檔)讀寫
wiki/reviews/跨頁面的 lint 結果、矛盾報告、整理建議讀寫
chunks/使用者手寫的學習卡(含 Recall 問題)唯讀,絕不可寫入
daily/每日學習日誌讀寫(append-only 為主)
reviews/週/月回顧讀寫
templates/模板(chunk/source/daily)唯讀
site/Quartz 渲染層,build 成 asurada.suxi.world唯讀 (除非要改部署設定)
docs/vault 自身的說明文件、setup guide讀寫
index.md全 wiki 入口目錄讀寫
log.md操作時間軸(append-only)僅 append
README.md給人類讀的整體說明讀寫

絕對禁止:

  • 在 chunks/ 下新增、修改、刪除任何檔案。
  • 直接編輯 raw/ 內的檔案(若需整理,複製到 wiki/sources/ 寫摘要)。
  • 改寫 log.md 既有條目(只能在末端 append)。
  • 修改 site/quartz/ 內部原始碼,除了 quartz/util/glob.ts 的 gitignore patch (那是必要 workaround,見 cloudflare-deploy 與 site/.gitignore 註解)。
  • 把 site/content/ 加進任何地方的 git tracking(它是 sync.mjs 產物)。

3. Frontmatter Schema

所有 wiki 條目都用 YAML frontmatter。共通欄位:

---
type: source | concept | entity | review | chunk | daily
title: <人類可讀標題>
aliases: []          # 別名,協助搜尋與反向連結
domain: <領域 tag>   # 如 mcp, cloudflare, sre, ai-tooling
tags: []
created: YYYY-MM-DD
last_reviewed: YYYY-MM-DD
---

各 type 額外欄位

source (wiki/sources/):

author:
url:
date_accessed: YYYY-MM-DD
date_published: YYYY-MM-DD
medium: paper | book | video | blog | talk | repo | docs
raw_ref: raw/<path>     # 對應 raw/ 內檔案的相對路徑
status: ingested | reviewed | archived

concept / entity:

related: []          # [[link]] 至其他 wiki 頁
sources: []          # [[link]] 至 wiki/sources/*
confidence: low | medium | high   # 對內容把握度

chunk (使用者寫,LLM 唯讀):

sources: []
related_concepts: []
recall_difficulty: easy | medium | hard
next_review: YYYY-MM-DD

daily:

date: YYYY-MM-DD
domains_touched: []
sources_today: []
chunks_today: []

4. 命名慣例

  • 檔名 kebab-case: mcp-transport-stdio.md,不含空白與中文。
  • 標題用 frontmatter 的 title 欄,可中可英、可有空白。
  • 反向連結用 Obsidian 雙鏈 [[檔名|顯示文字]]。
  • 領域 tag 用 kebab-case: mcp, cloudflare-workers, sre-oncall。

5. 工作流程

5.1 Ingest(新增來源)

觸發詞: 「我有一份新材料」「幫我吃這篇」「ingest this」

  1. 使用者把素材丟進 raw/(自己貼,LLM 不替使用者貼)。
  2. LLM 在 wiki/sources/<slug>.md 起草摘要頁(套 templates/source.md)。
  3. 不要直接寫入,先把草稿貼在對話裡跟使用者過。
  4. 確認後 LLM 落檔,並在 log.md append 一行。
  5. 若摘要中出現新概念/實體,先列出來問,確認後才在 wiki/concepts/ 或 wiki/entities/ 開新頁。一次最多開 3 個新頁,避免爆量。

5.2 Query(問問題)

觸發詞: 一般提問

  1. 先讀 index.md 找入口頁。
  2. 引用 wiki 頁面回答,用 [[link]] 標出處。
  3. 若需要 raw 細節,讀 raw/ 對應檔。
  4. 回答中只要動到知識,就要附 wiki 連結。沒連結 = 沒根據。
  5. 若 wiki 沒有答案,明說「目前 vault 沒收錄」,不要憑空回答。

5.3 Lint(每週體檢)

觸發詞: 「lint 一下」「跑週檢查」

掃描整個 wiki,輸出 wiki/reviews/lint-YYYY-MM-DD.md,內容含:

  • 矛盾偵測: 兩個頁面對同一事實說法不一致。
  • 孤兒頁: 沒被任何頁面 link 到的 wiki 頁。
  • 過時頁: last_reviewed 超過 90 天的頁。
  • 缺源頁: sources: [] 為空的 concept/entity。
  • 不平衡: 某 domain 頁數異常多/少。

只寫報告,不自動修,等使用者決定。

5.4 Chunkify(轉學習卡)

觸發詞: 「我要做學習卡」「來 chunk 化」

LLM 不可寫入 chunks/。流程:

  1. 使用者指定要 chunk 化的 wiki 頁。
  2. LLM 把該頁拆成多個候選學習卡片段,輸出在對話裡,套 templates/chunk.md 格式。
  3. 為每張卡提議 2~3 個 Recall 問題(主動回憶,符合 Learning How to Learn 原則)。
  4. 使用者自己複製貼上到 chunks/<slug>.md,自行調整。

6. log.md 寫入規範

每次有實質變更(新增/修改 wiki 頁、執行 lint)就 append 一行:

- YYYY-MM-DD HH:MM | <action> | <path> | <one-line note>

action 限定: ingest、update、lint、link、archive、note。 只 append,絕不改既有行。

7. 邊界與安全

  • 不替使用者下決定 — 永遠輸出草稿,讓使用者拍板。
  • 不刪除任何檔案 — 要「下架」就移到頁面 frontmatter status: archived。
  • 不外連到不在 vault 內的本機檔案路徑。
  • 不打開 raw/ 之外的本機檔案系統(除非使用者明確指示)。
  • 寫入大量內容前先確認數量級(>500 行先停下來問)。

8. Learning How to Learn 原則(影響 LLM 行為)

原則落實在哪
Active recallchunks/ 每張卡都有 Recall 問題欄位
Spaced repetitionchunks/ 的 next_review 欄、reviews/ 週月回顧
Interleavingwiki 跨領域 [[link]]、lint 找孤兒頁
ElaborationLLM 生 wiki 草稿時用使用者自己的話重述,不複製貼上
Chunking一個 concept 一頁,一張卡一個概念
Diffuse modedaily 日誌結尾留「散步想想」欄位

LLM 在生 wiki 草稿時,優先用重新表述、舉例、類比,而不是直接 copy raw 的段落。

9. 給 LLM 的硬規則 (TL;DR)

  1. 開始 session 先讀 CLAUDE.md + index.md + 最近一筆 log.md。
  2. 不寫 chunks/,不改 raw/,不改 log.md 既有行。
  3. 任何 wiki 寫入前都先把草稿貼在對話裡讓使用者過。
  4. 回答動到知識就附 [[wiki link]],沒源不答。
  5. 一次最多開 3 個新 wiki 頁。
  6. 完成寫入後在 log.md append 一行。

Graph View

Backlinks