system-dev-template/CHANGELOG.md

更新紀錄 CHANGELOG

每次改了什麼，都記在這。版號對應 template/.claude/VERSION。 想更新到最新版？看 README → 一鍵更新。

版號規則（語意化版本，簡化版）：

• 大版號（1.x → 2.x）：破壞性變動，舊專案更新後可能要手動調整。
• 中版號（1.0 → 1.1）：加了新功能，向下相容，更新即用。
• 小版號（1.1.0 → 1.1.1）：修 bug、改文件，無新功能。

---

1.10.1 — install 防重複安裝：已裝過一律導去 update（杜絕 wiki 並存）

實測踩到：一個裝過舊版的專案，「先跑 install、發現裝過、再跑 update」→ install 先在 system-dev/ 建了空白範本，update 的遷移看到「目的地已存在」就冪等跳過 → 真資料卡在舊 .claude/wiki/、空殼佔新位置，兩套 wiki 並存內容不同。

職責切分：install 只管全新安裝，一切已裝過的後續（更新/遷移/補新檔）歸 update。

• install 防呆：偵測「裝過沒」（system-dev/ 或 .claude/wiki/ 或 .claude/VERSION 任一存在，不分新舊版）→ 不動任何東西，導去 update 並 exit。從源頭杜絕「重複 install 製造並存」。
• update 偵測並存：migrate_dir 遇「目的地已存在但舊位置仍有真資料」→ 警告 COEXIST「並存需合併」，不靜默跳過、不自動合併（絕不覆蓋用戶資料），引導叫 CC 逐檔合併。
• install↔update 互相導向（update 遇全新專案也導回 install），閉環無死結。

1.10.0 — wiki 資訊架構：push/pull 判準 + principles（原則）push 檔

從「用戶所有檔案一律改寫成 wiki」的新前提，用 push（CC 行動前必主動看見）vs pull（按需檢索） 重新推導 wiki/ 每個檔的存廢——因為 wiki 主要是給 AI 看的，判準是「CC 做事時會不會被動看見」，不是分類美學。對應 SDD：wiki-architecture。

• 新增 principles.md（push 全文）：收「跨全局設計原則」（如不污染用戶根目錄、目標用戶 low-code）。原則是「會被遺忘的盲區」——沒推到眼前 CC 設計時不會服從。一行一條、≤15 條，累積只改此檔不開新檔。
• mistakes 改 push 摘要：session-start hook 注入標題清單+一行症狀，全文按需展開（量大不撐爆 context）。
• decisions-summary 降級為 cards + INDEX 決策視圖：決策是知識內容＝card；既有的保留相容。
• INDEX 升級為「多角度視圖」的家：標籤角度、決策角度…新增角度只改 INDEX 一節，不開實體檔、不問用戶。
• session-start hook 三類 push：principles 全文（最前）→ status 全文 → mistakes 標題；principles >15 條警告。
• install.sh 補 principles download；update.sh 新增 add_if_missing（舊用戶升級補範本、已有則保留不覆蓋）。
• push/pull 判準寫進 wiki-init.md 與 SKILL.md，CC/Cowork 共用。

1.9.3 — 遷移後 CLAUDE.md 殘留舊路徑：hook 偵測並提示 CC 代修

升級到 1.9.x 後 wiki 已搬到 system-dev/，但 update.sh 鐵則「絕不碰 CLAUDE.md」（用戶資料），導致 CLAUDE.md 內仍寫舊路徑 .claude/wiki/，CC 照它找錯位置（KB 端升級後發現）。

• session-start-recall.sh 加偵測：wiki 已遷移、但 CLAUDE.md 內還有 .claude/wiki → 接關後附帶提示，請 CC 主動幫使用者把 CLAUDE.md 的舊路徑改成 system-dev/（raw source 宣告的 docs/ 保留不動）。
• 由 CC 代改而非腳本盲 sed：避免誤傷用戶自寫內容、不破壞「絕不碰 CLAUDE.md」鐵則。

1.9.2 — 修 SKILL.md「typed-edge 三元組」整節重複貼兩次（issue #10）

加 gloss 節時複製貼上沒清掉舊段，### 使用 typed-edge 三元組 在 SKILL.md 出現兩次、byte-identical（KB 端讀 skill 時發現）。

• 刪掉重複的第二份，保留第一份（在卡片模板+架構說明之後，順序合理；gloss 節緊接其後）。
• 兩個來源檔同步修：docs/SKILL.md 與 template/system-dev/docs/SKILL.md。

1.9.1 — 修舊版（1.8.x）升級到 1.9.0 撞 404 + VERSION 被污染

1.9.0 把 VERSION 從 template/.claude/VERSION 搬到 template/system-dev/VERSION，但 1.8.x 舊用戶本機的 update.sh 寫死抓舊路徑 → curl 對 404 會把「404: Not Found」當內容回傳（非空），舊腳本沒驗證就把它寫進 .claude/VERSION，畫面顯示 Latest version: 404:NotFound、且第一次跑不會遷移（要再跑一次）。

• 發佈源保留相容墊片 template/.claude/VERSION：讓 1.8.x 舊腳本仍抓得到版號、不再 404。（bump 時與 system-dev/VERSION 同步）
• 新版 update.sh 加版號格式驗證：REMOTE_VER 必須像 X.Y.Z，否則（404 字串／HTML 錯誤頁／空）一律視為「取不到」，永不寫進 VERSION。未來任何路徑變動都不會再污染版號檔。
• 提醒：照 README 那行 curl … main/scripts/update.sh | bash 升級的人本就抓遠端新腳本、一次遷移成功不受影響；只有手動跑本機舊 bash scripts/update.sh 才會遇到，這版一併修掉。

1.9.0 — 安裝結構收進 system-dev/（不再污染用戶根目錄）+ 舊版自動遷移

工具產物原本散在用戶根目錄（docs/ 七層、update 時的 scripts/），又把 wiki/、VERSION 寄生在 CC 原生的 .claude/ 裡，用戶分不清「哪個 docs 是工具的、哪個是我的」。這版徹底收斂：除了 CC 死綁的 .claude/（settings/commands/hooks）和 CLAUDE.md 留根，工具所有資料收進 system-dev/。對應 SDD：system-dev/docs/3-specs/install-layout/。

• 新結構：system-dev/{VERSION, wiki/, docs/, scripts/}。.claude/ 只剩 CC 機制檔。
• wiki 改寫產物落點正式化：install 直接建 system-dev/wiki/cards/（含 .gitkeep），不再讓用戶自己長出來、自行 git init。
• docs 雙語義拆開：工具文件 → system-dev/docs/；用戶 raw source（原始文件來源）維持原處（用戶的 docs/、Logseq pages/+journals/、Obsidian vault），工具只讀、不搬。
• scripts 一開始就裝：install 把 install.sh/update.sh 放進 system-dev/scripts/，之後更新直接 bash system-dev/scripts/update.sh。
• 舊版自動遷移（雙保險）：① update.sh 偵測舊位置 → 冪等搬進 system-dev/（wiki 含 cards/ 與內含 .git 一起搬，docs 只搬工具白名單、不動用戶自填內容）；② session-start hook 偵測到舊結構未遷移 → 出聲提示，CC 可當場代為遷移。給「只會叫 CC 做事」的 low-code 用戶兜底。
• 機敏防護路徑跟進：wiki-secret-scan.sh 觸發路徑改 system-dev/wiki/**（否則新結構下寫入不啟動、防護失效）。
• 全套路徑引用同步更新：CLAUDE.md、SKILL.md、wiki-init、wiki-recall、wiki-capture、sdd-check、sdd-guard、session-start-recall、INDEX、decisions-summary、README（中英）。

升級提醒：舊用戶跑一次 update.sh 即自動遷移；沒跑也會在開 session 時被 hook 提示。屬向下相容的中版號（非破壞性手動遷移）。

1.8.2 — 修 update.sh 在 curl | bash 下崩潰（bash 3.2 多位元組字元，1.7.0 漏修到的同類 bug）

1.7.0 修了 install.sh 的「多位元組字元旁變數要用 ${VAR} 包」，但 update.sh 第 54 行漏網： 已是最新版（$LOCAL_VER） 的中文全形括號緊貼裸變數 $LOCAL_VER，curl | bash 串流在多位元組 邊界切斷時，bash 3.2 把後續位元組誤當變數名 → LOCAL_VER�: unbound variable 崩潰。偏偏觸發點在 「本機版本＝遠端版本」分支，所以「以為沒更新、再跑一次」必中。

• 第 54-55 行 $LOCAL_VER → ${LOCAL_VER}。已用 bash set -u 模擬該分支驗證不再崩。

1.8.1 — 補裝 Cowork 的 wiki skill（docs/SKILL.md）+ CLAUDE.md 加 wiki/gloss 導航

發現 Cowork（claude.ai）整理 wiki 的規則檔 docs/SKILL.md（含 typed-edge、frontmatter 標籤、gloss）從來沒被安裝到用戶端：install.sh 沒下載它，連 template/docs/ 發佈源都缺這檔 → claude.ai 來掃時身上沒任何 wiki 規則。同時 CC 平時讀的 CLAUDE.md 沒指向採集規則，導致「CC 說找不到 gloss 指引」。這版把兩條路徑都補上。

• 補發佈源：template/docs/SKILL.md 新增（從根 docs 同步），install.sh 才有得下載。
• install.sh：wiki 模組加一行下載 docs/SKILL.md。
• update.sh：加 update_file docs/SKILL.md，舊專案更新會帶上（規則檔，可覆蓋）。
• CLAUDE.md 模板：新增「整理 wiki 的方法」導航段，明示 CC（/wiki-init）與 Cowork（docs/SKILL.md）的採集規則所在地，gloss 不再「藏」在指令內文裡讓 CC 找不到。

1.8.0 — wiki 採集加「萃 gloss」（每個 node 一句說明，供下游語義 normalize）

下游 KBDB 要做語義 normalize：對「entity 名 + gloss（一句說明）」一起 embedding 求相似度自動歸一同義詞。但本地 wiki 採集只萃三元組、沒萃 gloss。原則是 gloss 該在知識生產當下由 local CC/Cowork 建（下游只有單檔／跨庫視角編不出好 gloss），不留給下游 ingest 臨時補。（issue #9）

• 卡片 frontmatter 加 gloss:：每張卡＝一個 entity/graph node，補一句機器可 normalize 的定義句。
• 選填、deep tier 才產：淺萃不浪費；deep 改寫時每卡補一句。
• gloss ≠ 摘要：gloss 是 frontmatter 給機器的定義句，## 摘要 是給人讀的核心句，兩處兩用途。
• 對齊下游 envelope：gloss: 對應 ingest envelope 的 nodes[].gloss，ingest 直接取用。
• 兩條路徑同步：wiki-init.md（CC）與 docs/SKILL.md（Cowork）都加上，產出一致。

1.7.0 — install/update 雙語化 + 修 macOS bash 3.2 安裝崩潰

非台灣使用者看不懂中文安裝訊息（curl | bash 出來整片中文），加上 macOS 內建 bash 3.2 在 set -u 下會崩。這版一起修：

• 修崩潰：install.sh 在 macOS bash 3.2 下會噴 VAULT_TYPE…: unbound variable / SKIPPED[*]: unbound variable。根因是 bash 3.2 + set -u 展開「空陣列」會炸，加上一行多餘的 ${SKIPPED[*]} no-op。修法：空陣列展開前先檢查、移除廢行、多位元組字串旁的變數一律用 ${VAR} 包好（避免 curl | bash 串流在多位元組字元邊界被切斷而誤判變數名）。
• install/update 訊息雙語：依 locale 自動選語言，預設英文（curl | bash 常是 LANG=C，外國人預設就看得懂），zh_TW 自動切回繁中。
• 寫進 CLAUDE.md 的 raw source 宣告也雙語：依 locale 只寫一種語言進 CLAUDE.md（雙語會讓每個 session 的 context 更滿）。
• 修措辭：一般開發案不再顯示誤導的「偵測到 vault 類型：docs」。偵測到 logseq/obsidian 筆記庫 → 出聲「會保留你的筆記結構」；不是筆記 → 默默裝完。
• README 多語：新增 README.en.md，頂部繁中 ↔ English 切換連結，利於被搜尋到。

1.6.1 — 釐清 taxonomy 是「受控擴充」非「凍結」

1.6.0 把標籤字典寫成「禁止自創」，措辭過嚴：碰到現有軸裝不下的新內容時，會逼 AI 硬塞錯標籤或偷偷自創，兩者都比受控擴充差。改成正確的機制：

• 禁止的是「繞過字典在卡片直接冒新標籤」，不是「新增標籤」。字典可擴充。
• 流程：遇到裝不下的內容 → ① 先查既有（是真新軸還是同義詞？知識管理 vs KM 別重造）→ ② 確實是新軸才登記進字典（附定義）再用。不必停下來問人，但「先查重再登記」不能省。
• 字典是 per-repo：跨 repo 引擎靠各 repo 自己一致的 taxonomy 接合，不是逼所有 repo 共用一份。
• 新增領域軸要慎（影響全庫聚類），形態軸擴充較安全；不確定就先用最接近的並註記「待人類複核」。

同步 wiki-init.md、docs/SKILL.md、TAXONOMY.md 三處措辭。

---

1.6.0 — wiki 完整規劃方式（183 卡實證）：三層架構 + frontmatter 標籤 + 多層索引（issue #8/#6/#7）

在一個中文 Logseq vault（234 篇 pages + journals → 183 張原子卡、571 條 typed-edge）完整跑了一輪 LLM Wiki，把「對 AI 最優」的規劃方式定案。一次納入 wiki-init.md 與 docs/SKILL.md（CC / Cowork 兩路徑一致）：

新增

• 三層 + 標籤橫切架構：頂層 INDEX.md（標籤視圖）→ cards/<bucket>/00-INDEX.md（桶子索引）→ 概念原子卡。資料夾只是儲存桶，分類由標籤承載，不繼承原稿目錄。
• frontmatter 標籤分類（issue #8）：分類走 frontmatter tags:，不靠資料夾、不靠行內 #tag——內文常用 #（如 #猜想），行內標籤會讓下游 ingest 分不清「分類」與「內文範例」污染 graph。雙軸 taxonomy（領域 + 形態）寫進新檔 TAXONOMY.md 當字典，禁止自創標籤。
• 桶子索引固定名 00-INDEX.md（issue #6）：00- 排序最前、一眼可辨，AI 載入任何桶一律先讀它。
• 麵包屑帶路徑 wikilink（issue #7）：卡片 H1 次行 ← [[<bucket>/00-INDEX]]。固定名 00-INDEX 跨桶撞名，故指它一律帶路徑；卡片間連結仍用裸 [[卡名]]。
• 新檔 template/.claude/wiki/TAXONOMY.md：標籤字典範本。install.sh download_if_missing、update.sh keep_file（使用者客製，永不覆蓋）。

踩坑警語寫進 wiki-init

• subagent 改寫時會誤把卡寫進 raw source → 目標一律給絕對路徑到 cards/<bucket>/，事後 git status --short pages/ journals/ 驗證原文 0 異動。
• 檔名＝卡片全名，冒號用全形「：」、斜線用全形「／」，全程一種字元避免斷鏈。
• 量大用 Haiku 並行改寫，主模型只切概念邊界 + 審稿 + 修斷鏈。

---

1.5.0 — wiki 連結升級成 typed-edge 三元組（issue #5）

背景：## 關聯 原本只列裸 [[頁面]]（沿用 Karpathy LLM Wiki）。但裸 [[A]] 是弱連結——只說「A 和本卡有關」，沒說關係是什麼。下游要從 wiki 抽 knowledge graph 時，拿到一堆無類型 edges，仍得回讀兩張卡才知道關係，等於關係沒被預編譯、退回 O(N²)。

變更

• wiki-init.md 與 docs/SKILL.md 的 ## 關聯 升級成 typed-edge 三元組：[[A]] >> 謂詞 >> [[B]]。下游 ingest 可直接 parse 出帶類型的有向邊，全局 graph 不必再讀卡片內容就知道關係。
• 規則：① 方向性——A >> 謂詞 >> B 須讀成「A（謂詞）B」一句通順的話，順序＝主→賓真實方向；② 謂詞用動詞/動詞短語（天然帶方向）；③ 謂詞自由書寫不受控詞彙（下游 embedding 會聚類同義謂詞，但方向靠書寫順序保證）；④ 向後相容：純 [[A]] 仍合法（無類型邊）。
• >> 為分隔語法，repo 可自選符號，全程一致即可。

---

1.4.1 — wiki = AI 改寫的記憶（拿掉索引模式）+ 量大建議 Haiku（issue #4）

修正 1.4.0 的方向：1.4.0 把「索引 vs 改寫」做成兩種並列模式，預設一般專案走索引、只有 vault 走改寫。這方向錯了——

記憶系統的目的是讓 AI 之後讀得快。 不管 vault 還是一般開發專案，人類原文都是亂的（重複、流水帳、半成品）。若 wiki 只是指回原文的索引，每次未來用都得重新解析那團亂＝沒省到。wiki 的價值就在「改寫一次，之後每次讀都便宜」。

變更

• wiki-init.md 拿掉索引模式，改寫成 wiki 是所有專案的唯一預設（vault 與一般開發一致）。原文＝唯讀 SSoT，wiki＝AI 改寫過的記憶，AI 是總編輯。
• 唯一例外：原文是不可改動的正式文件（簽署規格／法規／合約，須逐字讀）才用指針指回原文並註明「逐字依原文」。
• 量大建議用 Haiku：逐份原文改寫成 wiki 格式是重複、機械、判斷成本低的工作，正適合 Haiku。原文數量多時，命令會主動建議派 Haiku subagent 並行改寫，主模型只負責切概念、定條目邊界、審稿與互連。
• INDEX.md 範本：統一成「概念索引指向 wiki 內部條目」，不再提索引模式。

---

1.4.0 — wiki-init 新增「草稿改寫模式」：AI 當總編輯（issue #4）

背景：在 Logseq vault（234 篇 pages + journals）壓測 /wiki-init，發現它整套指令語言只有「分類歸檔／導航」，把人和 AI 都導向做出一個 [[原文檔名]] 指回原文的索引。但 PKM / vault 使用者的心智模型常是相反的——原文只是草稿（轉錄稿、隨手記），要 AI 改寫萃取成自包含 wiki，之後讀 wiki 就好、不必回原文。template 沒區分這兩種，且預設了「原文是成品」。

新增

• wiki-init.md 開頭新增模式分岔（第零步）：索引模式 vs 草稿改寫模式（AI 當總編輯），附對照表講清楚原文角色、INDEX 連結、回答方式的差異。
  • 偵測到 PKM vault（Logseq/Obsidian）→ 預設草稿改寫模式，但明確問一句讓使用者可切回索引模式。
  • 一般專案 → 預設索引模式（維持原行為，向下相容）。
• 草稿改寫模式的產出規則（第五步）：概念原子化、自包含、保留來源指針（可追溯但不必回讀）、[[wikilink]] 互連——與 claude.ai Cowork 的 docs/SKILL.md 改寫邏輯一致，CC / Cowork 兩條路徑產出同一種 wiki。
• INDEX.md 範本：草稿模式下改成「概念索引」指向 wiki 內部改寫條目，而非指回原文。

不變：raw source 永遠唯讀，兩種模式都只往 .claude/wiki/ 寫，絕不搬移/改名原文。

---

1.3.1 — 修：update.sh 不再覆蓋客製的 pre-write-guard.sh（issue #3）

修正

• scripts/update.sh 原本把 pre-write-guard.sh 列在「覆蓋更新」區，無條件用模板空殼蓋掉。 但此檔的定位是「使用者手填的 guardrail 客製檔」（CHANGELOG 1.2.0），下游通常已塞滿自己的 enforcement， 且 update_file 覆蓋無 .bak 備份——跑一次 update 等於無聲關掉整套 guardrail（如 Arcrun 的 KNOWN_SDDS 白名單、薄殼原則強制等數百行）。
• 改法（issue 建議方案 1）：新增 keep_with_template()，把 pre-write-guard.sh 移出覆蓋區。 原檔永不覆蓋，改把最新模板版另存成 pre-write-guard.template.sh 旁邊，更新結尾印出 diff 指令供使用者自行採納。 首次安裝（原檔不存在）才會直接抓本體。install.sh 路徑本就用 download_if_missing（已存在即跳過），無此問題。

---

1.3.0 — vault 偵測（Logseq / Obsidian）+ Cowork 整理 skill

新增

• install.sh 在建立 CLAUDE.md 前自動偵測資料夾類型，把對應的「原始文件來源（raw source）」寫進 CLAUDE.md：
  • logseq/ → raw source pages/、journals/
  • .obsidian/ → raw source 根目錄下所有 .md
  • 都沒有 → docs/（維持原行為） 寫入的宣告是給 AI 讀的指令，對 vault 明令不得搬動/改名/重新分類 .md，整理結果一律只寫進 .claude/wiki/， 面對筆記 vault 不會破壞它原本的結構。已有 CLAUDE.md 一律不覆蓋，改在結尾列出該補的宣告提醒手動貼。
• docs/SKILL.md：給 claude.ai Cowork 的 wiki-cowork-scan skill。 與 CC 的 /wiki-init、/wiki-capture 共用同一套規則，用與 install.sh 一致的偵測邏輯掃描 ~/Documents 下所有裝了本模板的資料夾，只讀 raw source、只往 .claude/wiki/ 增補（不覆蓋、不刪除）， 絕不動 raw source、CLAUDE.md、logseq/、.obsidian/、assets/。讓整理 wiki 不再只限終端機裡的 CC。

變更

• README 新增「不只程式碼，也認得 Logseq / Obsidian vault」「Cowork 也能整理 wiki」兩節，並更新目錄樹。

---

1.2.0 — GitHub issue 指引 + pre-write-guard 定位釐清

新增

• /issue-handle slash command（template/.claude/commands/issue-handle.md）： CC 處理 GitHub issue 的普世指引，三層界線—— ①讀/回/結案自己 repo 的 issue（直接做）； ②發 issue 給別的 repo（先問人，不擅自）； ③禁止掛 Actions/cron/webhook 自動輪詢 issue（會觸發 GitHub 異常偵測、被 rate limit）。 屬共用指引，install/update 不分模組都裝。（issue #1）

變更

• pre-write-guard.sh 釐清定位（issue #2）：它是「按需手填的空插槽」，不是裝上就生效的警察。
  • 檔頭明講：有 CC 在場時，直接叫 CC 寫貼合的 guard hook 更好，這個空殼範本只對「手動 DIY」用戶有價值。
  • 解決安全錯覺：install.sh / update.sh 安裝它時提示「預設不攔任何東西，要手填+掛 settings 才生效」， 讓用戶不會誤以為裝了就有保護。（hook 執行時維持安靜，避免每次 Write 洗版。）

---

1.1.0 — 一鍵更新

新增

• scripts/update.sh：已安裝舊版的人，一行指令更新到最新版。 只覆蓋模板/邏輯檔（hooks、commands、TEMPLATE-*），完全不碰使用者資料 （wiki/status.md、mistakes.md、decisions-summary.md、.wikiignore、settings.json、CLAUDE.md）。 會先比對版本、列出新功能、依已裝模組自動偵測該更新什麼，跑完自我更新。
• template/.claude/VERSION：版本基準檔，讓「檢查新版」有依據。
• CHANGELOG.md（本檔）。

第一次更新的雞生蛋問題：舊版本機還沒有 update.sh，所以第一次靠 README 那行 curl 從遠端抓更新器來跑；跑完它把自己裝進 scripts/update.sh，之後直接跑本機的即可。

---

1.0.0 — 模組化安裝（基準版）

此版本之前無 VERSION 檔，以下為依 git 歷史回溯的功能基準。

• scripts/install.sh 模組化安裝：--wiki / --sdd / --all，無參數則互動詢問。
• LLM Wiki：CC 記憶系統（INDEX / status / mistakes / decisions-summary）
  • 接關 hook（session-start-recall）+ 對應 slash commands。
• wiki 機敏防護三層：.wikiignore（檔案層）＋行內標記（局部）＋ wiki-secret-scan.sh（機械兜底攔截）。
• SDD 強制：動 code 前必須有 design.md，由 sdd-guard.sh hook 把關，附 TEMPLATE 範本。
• docs 分類結構（1-vision ~ 6-user）與 ADR 範本。