system-dev-template/template/.claude/commands/wiki-init.md

/wiki-init — 初始化或接入 LLM Wiki 系統

初始化這個專案的 LLM Wiki 記憶系統。 新專案建立空白結構，已有專案掃描現有文件並建立 wiki。

---

兩種 wiki 形狀：索引 vs 改寫（先決定，決定整個 wiki 的樣子）

同一句「整理 wiki」，使用者要的可能是相反的兩件事。原文的角色不同，wiki 的形狀就完全不同：

	索引模式	草稿改寫模式（AI 當總編輯）
原文角色	成品，wiki 的目的地	一次性草稿（錄音轉錄、隨手記），萃取完可不看
AI 做什麼	分類、歸檔、建導航	改寫萃取成自包含、適於 AI 讀的條目
INDEX 連結	[[原文檔名]] 指回原文	指向 wiki 內部的改寫條目
使用者問問題	AI 說「去看原文 X」	AI 直接從 wiki 回答，不必回原文
適合誰	一般程式專案、規格文件	PKM / Logseq / Obsidian vault、知識部落格

核心概念：草稿改寫模式裡，人類寫的原文是 SSoT（真理來源），但實際要長期保存、被反覆讀的是 AI 改寫整理過的 wiki。AI 是「總編輯」——把降低書寫壓力而隨手寫下的草稿，改寫成自包含、概念原子化、互相連結的知識條目。

怎麼決定模式（第零步，最先做）

1. 偵測 vault 類型（同 install.sh 邏輯）：根目錄有 logseq/ → Logseq；有 .obsidian/ → Obsidian；都沒有 → 一般專案。
2. 挑預設並說明，給一次切換機會：
   • 偵測到 PKM vault（Logseq/Obsidian） → 預設草稿改寫模式。明確告知一句：

     「偵測到 [Logseq/Obsidian] vault，PKM 筆記通常是草稿——我會用草稿改寫模式：把原文萃取改寫成自包含 wiki，之後讀 wiki 就好。若你的筆記其實是成品、只想要指回原文的索引，回我『索引模式』。」

   • 一般專案 → 預設索引模式（分類歸檔、INDEX 指回原文）。一句帶過，使用者要改寫再說。
3. 模式定了再往下走。raw source 永遠唯讀——兩種模式都只往 .claude/wiki/ 寫，絕不改動、搬移、重新命名原文。

---

執行流程

第一步：偵測專案狀態

檢查以下項目，判斷是新專案還是已有專案：

• 根目錄有沒有 .claude/wiki/
• 根目錄有沒有 docs/（或 vault 的 pages/、journals/、根目錄 .md）
• 有沒有散落的 .md 檔案

新專案（幾乎空的）→ 直接建立結構，跳到第三步 已有專案（有文件）→ 執行第二步

第二步：已有專案的掃描（已有專案才執行）

1. 遞迴找出所有 .md 檔案（vault 模式只讀偵測到的 raw source：Logseq 的 pages/+journals/、Obsidian 根目錄 .md）
2. 先套用 .claude/wiki/.wikiignore：命中 pattern 的檔案整個排除，不讀不編入。
   • 若 .wikiignore 不存在，從範本建立一份（預設排除 .env/*.pem/*secret* 等）
   • 被排除的檔案在清單裡標「🚫 .wikiignore 排除」，不可被覆蓋
3. 對其餘檔案標注處理計畫（依模式不同）：
   • 索引模式：標注建議分類位置和信心度
   • 草稿改寫模式：標注「會萃取成哪些 wiki 條目」（一份原文可能拆成多個概念原子條目，多份原文也可能合併成一條）
4. 列出清單給使用者確認，停下來等確認

機敏防護（三層）：

• L1 .wikiignore：整檔排除（這一步）
• L2 行內標記：檔案要編入但某段不要 → 遇到 <!-- wiki:ignore --> … <!-- wiki:end --> 之間的內容略過，只留「（此處機敏，已略過）」
• L3 hook：萬一機敏值仍被寫進 wiki，wiki-secret-scan.sh 會 exit 2 擋下 編入任何檔案前，先檢查是否含密碼/金鑰/個資——有就改記「位置」而非「值」。

索引模式的分類規則（草稿改寫模式跳過，改用第五步的萃取格式）：

有明確子系統 + 設計內容 → docs/3-specs/[子系統]/
解釋為什麼做某個決定   → docs/2-architecture/decisions/
說明怎麼操作           → docs/4-guides/
記錄發生過的事         → docs/5-records/
給外部使用者看的       → docs/6-user/
不確定                → 列為「待確認」，問使用者

第三步：建立缺少的結構

只建立不存在的目錄和檔案，已有的一律不動：

目錄：

docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{incidents,test-reports},6-user}
.claude/wiki/

（純 PKM vault 不需要 docs/ 分類樹時，可只建 .claude/wiki/。）

檔案（不存在才建）：

• .claude/wiki/INDEX.md
• .claude/wiki/status.md
• .claude/wiki/mistakes.md
• .claude/wiki/decisions-summary.md
• docs/README.md（一般專案才需要）

第四步：訪談（每次一個問題）

依序問：

1. 這個專案做什麼？（一句話）
2. 有哪些絕對不能違反的限制？（技術棧、架構原則等）
3. 現在進行到哪個階段？
4. 有沒有 CC 曾經犯過的錯要先記下來？

把答案填進 CLAUDE.md（如果存在）或建立新的。

第五步：產出 wiki（依模式分流）

（第二步確認後執行）

索引模式

按照確認好的分類移動/歸檔檔案，完成後更新 CLAUDE.md 的路徑引用，INDEX.md 列出 [[原文檔名]] 導航。

草稿改寫模式（AI 當總編輯）

不搬動原文。逐份讀 raw source，改寫萃取成 .claude/wiki/ 裡的自包含條目：

• 概念原子化：一個 wiki 頁面講一個主題，不是一篇原文對一頁。原文太雜就拆，多份相關草稿就合。
• 自包含：讀 wiki 條目就懂，不必回去翻原文。把口語、重複、時間順序的流水帳，改寫成結構化的知識。
• 保留來源指針：每條標 **來源**：原文相對路徑，是為了可追溯，不是要使用者回去讀。
• 互相連結：用 [[頁面名稱]] 連到相關條目（Karpathy LLM Wiki 的核心——知識互連，不是孤島）。

wiki 條目格式：

# [主題名稱]

**來源**：`[raw source 相對路徑]`
**最後更新**：YYYY-MM-DD

## 摘要
[2-3 句說明這個主題的核心]

## 重點
- [改寫後的要點，自包含、不依賴原文]

## 關聯
- [[相關 wiki 頁面]]

INDEX.md 在此模式是概念索引，指向 wiki 內部條目（非原文）：

## 概念索引
| 條目 | 來源 | 一句話 | 最後更新 |
|------|------|--------|----------|
| [[主題名稱]] | `raw/path.md` | 一句話摘要 | YYYY-MM-DD |

與 claude.ai Cowork 的 docs/SKILL.md 改寫邏輯一致，兩條路徑（CC / Cowork）產出同一種 wiki。

第六步：完成報告

告知：

✅ wiki-init 完成（模式：索引／草稿改寫）
建立了：[列出新建的目錄和檔案]
跳過了：[列出已有因此不動的]
[草稿改寫模式] 萃取了：[N 份原文 → M 條 wiki 條目]
下一步：用 /wiki-capture 把重要決策存進 wiki