From 671503fd703e2d2d0308cb57a88bed4bbd26620f Mon Sep 17 00:00:00 2001 From: richblack Date: Fri, 26 Jun 2026 16:52:32 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20wiki=20=E8=B3=87=E8=A8=8A=E6=9E=B6?= =?UTF-8?q?=E6=A7=8B=20push/pull=20=E5=88=A4=E6=BA=96=20+=20principles=20?= =?UTF-8?q?=E5=8E=9F=E5=89=87=20push=20=E6=AA=94=20+=20bump=201.10.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 從「用戶所有檔案一律改寫成 wiki」前提,用 push(行動前必看見)vs pull(按需查) 重新推導 wiki/ 每個檔存廢——wiki 主要給 AI 看,判準是 CC 做事會不會被動看見。 對應 SDD: wiki-architecture(內部,依原則不推)。 - 新增 principles.md(push 全文):收跨全局原則(不污染根目錄、low-code…), 原則是會被遺忘的盲區,沒推到眼前 CC 設計時不服從。一行一條 ≤15。 - mistakes 改 push 摘要(標題+症狀,全文按需展開,量大不撐爆 context) - decisions-summary 降級為 cards + INDEX 決策視圖(既有相容) - INDEX 升級多角度視圖的家:新增角度只改 INDEX,不開檔不問用戶 - session-start hook 三類 push:principles 全文→status→mistakes 標題;>15 警告 - install 補 principles download;update 加 add_if_missing(補範本/已有則保留) - push/pull 判準寫進 wiki-init + SKILL,CC/Cowork 共用 - 沙盒驗證:三類注入順序與量受控、add_if_missing 不覆蓋用戶內容、全 bash -n 過 Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitignore | 3 ++ CHANGELOG.md | 12 +++++ docs/SKILL.md | 21 +++++++- scripts/install.sh | 14 +++--- scripts/update.sh | 15 ++++++ template/.claude/VERSION | 2 +- template/.claude/commands/wiki-init.md | 37 +++++++++++--- .../.claude/hooks/session-start-recall.sh | 45 ++++++++++++++--- template/system-dev/VERSION | 2 +- template/system-dev/docs/SKILL.md | 21 +++++++- template/system-dev/wiki/INDEX.md | 49 +++++++++++++------ template/system-dev/wiki/principles.md | 18 +++++++ 12 files changed, 197 insertions(+), 42 deletions(-) create mode 100644 template/system-dev/wiki/principles.md diff --git a/.gitignore b/.gitignore index bb87b47..48f45d1 100644 --- a/.gitignore +++ b/.gitignore @@ -14,12 +14,15 @@ skills/editorial-image/ # 根目錄自裝的開發 wiki — 內部記錄，不推 GitHub（用戶看的是 template/ 裡的範本） # 內容檔是我們開發此 template 的記錄；架構檔（INDEX/.wikiignore/hooks）是從 # template/ 複製來自用的，範本本體已在 template/ 推上去，這份不重複推。 +# 1.10 後 dev 自用 wiki 與 VERSION 也遷到根目錄的 system-dev/（與用戶端結構一致）。 +# 注意：只排除「根目錄」的 /system-dev/（前綴 /）；template/system-dev/ 是發佈源，要推。 .claude/wiki/ .claude/hooks/ .claude/commands/ .claude/VERSION .claude/settings.json .claude/settings.local.json +/system-dev/ # Dogfooding：我們把 system-dev-template 也裝進自己的 repo 自用（產生這些自裝產物）。 # 真正的範本本體在 template/ 底下，這些根目錄自裝副本不推雲端，用戶不需要。 diff --git a/CHANGELOG.md b/CHANGELOG.md index 4cf69f9..686fa42 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,18 @@ --- +## 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 端升級後發現）。 diff --git a/docs/SKILL.md b/docs/SKILL.md index 16b55ea..4bc3d55 100644 --- a/docs/SKILL.md +++ b/docs/SKILL.md @@ -62,9 +62,9 @@ else 進入 `system-dev/wiki/`，讀取： -- `INDEX.md`：目前已有哪些 wiki 頁面 +- `INDEX.md`：目前已有哪些 wiki 頁面（多角度視圖入口） - `status.md`：上次整理時間、進度 -- `log.md`（如果有）：誰動過什麼 +- `principles.md`（如果有）：本專案跨全局的設計原則——整理時必須服從 目的：**知道哪些已整理過，只處理新增或有變動的 raw source**，不重複整理。 @@ -72,6 +72,23 @@ else ## 第四步：整理規則 +### 核心判準：push vs pull（wiki 是給 AI 看的） + +整理任何內容前，先判斷它該進 **push 檔** 還 **cards（pull）**——判準是「**CC 做事時會不會被動看見**」： + +- **push 檔**（`status.md` / `mistakes.md` / `principles.md`）：CC session 開始就被 hook 注入。給「CC 不會主動查、但不看就出事」的東西。 +- **pull**（`cards/`）：CC 想到要查才看見。一切知識內容（原文摘要、AI 筆記、決策、概念…）都寫成 cards。 + +| 內容 | 去哪 | 理由 | +|------|------|------| +| 當前進度、下一步 | `status.md`（push 全文） | 時態狀態，不看會重做 | +| 跨全局設計原則（一行一條，≤15） | `principles.md`（push 全文） | 會被遺忘的盲區，CC 設計時必服從 | +| 踩坑、被糾正的誤解 | `mistakes.md`（push 摘要+按需展開） | 防 CC 不自覺的盲區 | +| 決策、原文摘要、概念知識、其餘一切 | `cards//`（pull） | 知識內容；CC 面對時自然會查 | + +> `decisions-summary.md` 已**降級為 cards + INDEX 決策視圖**（決策＝知識內容）。既有的保留為相容，不刪。 +> CC 與 Cowork **共用此判準**，產出一致：任一方寫進 push 檔或 cards，另一方看到就跳過或補充，不覆蓋。 + ### 讀 raw source 逐一讀取 raw source 的 `.md` 檔。跳過： diff --git a/scripts/install.sh b/scripts/install.sh index 071f227..68ba741 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -247,7 +247,7 @@ if $WANT_WIKI; then download_if_missing "system-dev/wiki/TAXONOMY.md" "$REPO_URL/system-dev/wiki/TAXONOMY.md" download_if_missing "system-dev/wiki/status.md" "$REPO_URL/system-dev/wiki/status.md" download_if_missing "system-dev/wiki/mistakes.md" "$REPO_URL/system-dev/wiki/mistakes.md" - download_if_missing "system-dev/wiki/decisions-summary.md" "$REPO_URL/system-dev/wiki/decisions-summary.md" + download_if_missing "system-dev/wiki/principles.md" "$REPO_URL/system-dev/wiki/principles.md" download_if_missing "system-dev/wiki/.wikiignore" "$REPO_URL/system-dev/wiki/.wikiignore" # wiki 改寫產物（AI 自讀定稿卡片）的正式落點：由工具建好，不靠用戶自救。 @@ -374,21 +374,21 @@ if [ -f "CLAUDE.md" ]; then echo "" if [ "$IS_ZH" = "yes" ]; then cat <<'SNIP' - ## Wiki 讀取順序 + ## Wiki 讀取順序（push：hook 開 session 自動注入） | 檔案 | 時機 | 用途 | |------|------|------| | `system-dev/wiki/status.md` | session 開始第一件事 | 當前進度 | - | `system-dev/wiki/mistakes.md` | 做新功能前 | 已知誤解 | - | `system-dev/wiki/decisions-summary.md` | 設計判斷時 | 架構決策 | + | `system-dev/wiki/principles.md` | 設計任何東西前 | 跨全局原則，必服從 | + | `system-dev/wiki/mistakes.md` | 做新功能前 | 已知踩坑 | SNIP else cat <<'SNIP' - ## Wiki reading order + ## Wiki reading order (push: auto-injected at session start) | File | When | Purpose | |------|------|---------| | `system-dev/wiki/status.md` | first thing at session start | current progress | - | `system-dev/wiki/mistakes.md` | before building a new feature | known misconceptions | - | `system-dev/wiki/decisions-summary.md` | when making design calls | architecture decisions | + | `system-dev/wiki/principles.md` | before designing anything | global principles, must obey | + | `system-dev/wiki/mistakes.md` | before building a new feature | known pitfalls | SNIP fi fi diff --git a/scripts/update.sh b/scripts/update.sh index d0fa318..90e99d6 100755 --- a/scripts/update.sh +++ b/scripts/update.sh @@ -149,6 +149,19 @@ keep_file() { [ -f "$1" ] && KEPT+=("$1") || true } +# 補新檔：舊版沒有、新版才有的「使用者資料檔」（如 principles.md）。 +# 不存在 → 抓範本下來（之後由使用者/CC 填）；已存在 → 當用戶資料保留，絕不覆蓋。 +add_if_missing() { + local dest="$1" src="$2" + if [ -f "$dest" ]; then + KEPT+=("$dest") + elif curl -sSL "$src" -o "$dest" 2>/dev/null && [ -s "$dest" ]; then + NEW+=("$dest") + else + rm -f "$dest" + fi +} + # 客製檔：使用者一定會手填內容（如 pre-write-guard.sh）。 # - 已存在 → 絕不覆蓋，但把最新模板版抓到 <檔名>.template.sh 旁邊，供使用者自行 diff 採納。 # - 不存在 → 視同新檔，直接抓本體（第一次安裝才會走這條）。 @@ -213,6 +226,8 @@ if $HAS_WIKI; then # wiki 的「使用者資料」：絕不碰 keep_file "system-dev/wiki/status.md" keep_file "system-dev/wiki/mistakes.md" + # principles.md（1.10）：舊版沒有 → 補範本；已有 → 當用戶資料保留 + add_if_missing "system-dev/wiki/principles.md" "$TEMPLATE_URL/system-dev/wiki/principles.md" keep_file "system-dev/wiki/decisions-summary.md" keep_file "system-dev/wiki/TAXONOMY.md" keep_file "system-dev/wiki/.wikiignore" diff --git a/template/.claude/VERSION b/template/.claude/VERSION index 7b0231f..ed21137 100644 --- a/template/.claude/VERSION +++ b/template/.claude/VERSION @@ -1 +1 @@ -1.9.3 \ No newline at end of file +1.10.0 \ No newline at end of file diff --git a/template/.claude/commands/wiki-init.md b/template/.claude/commands/wiki-init.md index c57c396..2fcca5e 100644 --- a/template/.claude/commands/wiki-init.md +++ b/template/.claude/commands/wiki-init.md @@ -67,15 +67,20 @@ wiki 採**三層 + 標籤橫切**架構（183 卡實證，issue #8）： ``` system-dev/wiki/ -├── INDEX.md ← 頂層：標籤視圖（不是資料夾列表） -├── TAXONOMY.md ← 標籤字典（分類骨架，受控擴充：先查重再登記） -├── status.md / mistakes.md / decisions-summary.md -└── cards/ - └── / ← 儲存桶（一般專案沿用 docs 分類；vault 由 AI 重新組織） +├── INDEX.md ← 索引：多角度視圖的家（標籤角度、決策角度、…） +├── TAXONOMY.md ← 標籤字典（cards 的分類元資料，受控擴充） +├── status.md ← [push] 時態狀態：當前進度、下一步 +├── mistakes.md ← [push] 踩過的坑、被糾正的誤解（防不自覺盲區） +├── principles.md ← [push] 跨全局的設計原則（行動前必服從） +└── cards/ ← [pull] 一切知識內容：原文摘要、AI 筆記、決策、概念… + └── / ← 儲存桶（分類由 frontmatter 標籤承載） ├── 00-INDEX.md ← 桶子索引（固定名，容器：只連不重寫，H2/H3 分節） └── <概念全名>.md ← 概念原子卡（一概念一檔，自包含） ``` +> **[push] / [pull] 是這套 wiki 的核心判準——因為 wiki 主要是給 AI（CC）看的。** +> 見下方「核心判準：push vs pull」。`decisions-summary.md` 已**降級為 cards + INDEX 決策視圖**（決策是知識內容＝card）；既有的 decisions-summary 若存在，保留為相容，不刪。 + 關鍵原則：**資料夾只是儲存桶，分類由 frontmatter 標籤承載**。資料夾名不該硬繼承原稿目錄——原稿目錄是「人為了整理草稿」分的，wiki 連分類都該由 AI 重新組織。 > **桶子索引固定叫 `00-INDEX.md`**（issue #6）：`00-` 前綴讓它排序最前、一眼可辨（像 README 之於資料夾），AI 載入任何 `cards//` 一律先讀它，不必猜。檔內 H1 仍寫主題名（如 `# PKM 知識管理`），語意不丟。 @@ -88,9 +93,29 @@ system-dev/docs/{1-vision,2-architecture/decisions,3-specs,4-guides,5-records/{i 檔案（不存在才建）： - `system-dev/wiki/INDEX.md`、`TAXONOMY.md` -- `system-dev/wiki/status.md`、`mistakes.md`、`decisions-summary.md` +- `system-dev/wiki/status.md`、`mistakes.md`、`principles.md`（三個 push 檔） - `system-dev/docs/README.md`（一般專案才需要） +--- + +## 核心判準：push vs pull（wiki 是給 AI 看的） + +整理任何內容前，先判斷它該 **push** 還 **pull**——判準是「**CC 做事時會不會被動看見**」： + +- **push**：CC 行動前必須主動出現在 context（session 開始就由 hook 注入）。給「CC 不會主動去查、但不看就出事」的東西。 +- **pull**：CC 想到要查、或載入相關卡時才看見。給「CC 面對它時自然會查」的知識。 + +**為什麼這是核心**：mistakes 防的是 CC「不自覺的盲區」——一個你不知道存在的錯，你不會主動去檢索它。靠 CC 自覺去查自己沒自覺的盲區是自相矛盾的，所以 pull 對盲區失效，**必須 push**。原則同理：沒被推到眼前的準繩，CC 設計時很可能沒想到要服從就做了。 + +| 內容 | push/pull | 注入形態（hook）| +|------|-----------|----------------| +| **status** | push | **全文**——CC 必須知道精確的下一步，摘要會漏 task 編號 | +| **principles** | push | **全文（一行一條）**——短而硬的約束，漏一條就違反；≤15 條，超過代表該下放成 card | +| **mistakes** | push | **標題清單 + 一行症狀**，全文按需 pull——量可能大，摘要足以觸發「我正撞到某條」的認出 | +| **decisions、原文摘要、概念知識、一切其餘** | pull | 寫成 cards；CC 面對時自然會查，INDEX 提供角度入口 | + +**principles 維護規則**：一行一條精煉準繩（如「不污染用戶根目錄」「目標用戶 low-code」「wiki 主要給 AI 看」）。發現新的跨全局原則 → append 一行；超過 ~15 條代表某些該合併或下放成 card。**累積原則只改 principles.md，不必問用戶開新檔。** + ### 第四步：訪談（每次一個問題） 依序問： diff --git a/template/.claude/hooks/session-start-recall.sh b/template/.claude/hooks/session-start-recall.sh index 6d8f855..16df4c0 100755 --- a/template/.claude/hooks/session-start-recall.sh +++ b/template/.claude/hooks/session-start-recall.sh @@ -11,6 +11,8 @@ set -euo pipefail STATUS_FILE="system-dev/wiki/status.md" +PRINCIPLES_FILE="system-dev/wiki/principles.md" +MISTAKES_FILE="system-dev/wiki/mistakes.md" # ── 舊結構防呆（1.9.0 遷移第 2 層保險）── # 新版 wiki 收進 system-dev/。若偵測到舊位置 .claude/wiki/ 還在、但新位置沒 status， @@ -24,16 +26,45 @@ if [ -d ".claude/wiki" ] && [ ! -f "$STATUS_FILE" ]; then exit 0 fi -# 沒有 wiki 就安靜退出（exit 0），不干擾還沒 /wiki-init 的專案 -if [ ! -f "$STATUS_FILE" ]; then +# 三個 push 檔都沒有 → 安靜退出，不干擾還沒 /wiki-init 的專案 +if [ ! -f "$STATUS_FILE" ] && [ ! -f "$PRINCIPLES_FILE" ] && [ ! -f "$MISTAKES_FILE" ]; then exit 0 fi -echo "════════════════════════════════════════════════" -echo "📍 接關：上次進度（來自 $STATUS_FILE 快照）" -echo "════════════════════════════════════════════════" -echo "" -cat "$STATUS_FILE" +# ── push 1/3：principles（全文，行動前必服從）── +# 放最前：原則是「會被遺忘的盲區」，要第一眼看見。全文成本低（一行一條、≤15 條）。 +if [ -f "$PRINCIPLES_FILE" ] && grep -q '^- ' "$PRINCIPLES_FILE" 2>/dev/null; then + echo "════════════════════════════════════════════════" + echo "📐 設計原則（行動前必服從，來自 principles.md）" + echo "════════════════════════════════════════════════" + grep '^- ' "$PRINCIPLES_FILE" # 只注入原則條目本身，不含說明區 + # context 保護：原則應 ≤15 條（push 全文）。超過 → 提示該合併或下放成 card，不截斷（截斷會漏原則）。 + P_COUNT=$(grep -c '^- ' "$PRINCIPLES_FILE") + if [ "$P_COUNT" -gt 15 ]; then + echo "" + echo "（⚠️ principles 已 ${P_COUNT} 條 > 15：請考慮合併相近原則、或把較細的下放成 card）" + fi + echo "" +fi + +# ── push 2/3：status（全文，當前進度）── +if [ -f "$STATUS_FILE" ]; then + echo "════════════════════════════════════════════════" + echo "📍 接關：上次進度（來自 $STATUS_FILE 快照）" + echo "════════════════════════════════════════════════" + echo "" + cat "$STATUS_FILE" +fi + +# ── push 3/3：mistakes（標題清單 + 一行症狀，全文按需展開）── +# 不全文注入（可能累積很多、含長 context）。只給「標題行」讓 CC 認出「我正撞到某條」→ 再去讀全文。 +if [ -f "$MISTAKES_FILE" ] && grep -q 'MISTAKE' "$MISTAKES_FILE" 2>/dev/null; then + echo "" + echo "────────────────────────────────────────────────" + echo "⚠️ 已知踩坑（標題；撞到時讀 $MISTAKES_FILE 全文）" + grep -E 'MISTAKE' "$MISTAKES_FILE" | sed 's/^/ /' +fi + echo "" echo "────────────────────────────────────────────────" echo "⚠️ 以上是 point-in-time 快照，非即時狀態。" diff --git a/template/system-dev/VERSION b/template/system-dev/VERSION index 7b0231f..ed21137 100644 --- a/template/system-dev/VERSION +++ b/template/system-dev/VERSION @@ -1 +1 @@ -1.9.3 \ No newline at end of file +1.10.0 \ No newline at end of file diff --git a/template/system-dev/docs/SKILL.md b/template/system-dev/docs/SKILL.md index 16b55ea..4bc3d55 100644 --- a/template/system-dev/docs/SKILL.md +++ b/template/system-dev/docs/SKILL.md @@ -62,9 +62,9 @@ else 進入 `system-dev/wiki/`，讀取： -- `INDEX.md`：目前已有哪些 wiki 頁面 +- `INDEX.md`：目前已有哪些 wiki 頁面（多角度視圖入口） - `status.md`：上次整理時間、進度 -- `log.md`（如果有）：誰動過什麼 +- `principles.md`（如果有）：本專案跨全局的設計原則——整理時必須服從 目的：**知道哪些已整理過，只處理新增或有變動的 raw source**，不重複整理。 @@ -72,6 +72,23 @@ else ## 第四步：整理規則 +### 核心判準：push vs pull（wiki 是給 AI 看的） + +整理任何內容前，先判斷它該進 **push 檔** 還 **cards（pull）**——判準是「**CC 做事時會不會被動看見**」： + +- **push 檔**（`status.md` / `mistakes.md` / `principles.md`）：CC session 開始就被 hook 注入。給「CC 不會主動查、但不看就出事」的東西。 +- **pull**（`cards/`）：CC 想到要查才看見。一切知識內容（原文摘要、AI 筆記、決策、概念…）都寫成 cards。 + +| 內容 | 去哪 | 理由 | +|------|------|------| +| 當前進度、下一步 | `status.md`（push 全文） | 時態狀態，不看會重做 | +| 跨全局設計原則（一行一條，≤15） | `principles.md`（push 全文） | 會被遺忘的盲區，CC 設計時必服從 | +| 踩坑、被糾正的誤解 | `mistakes.md`（push 摘要+按需展開） | 防 CC 不自覺的盲區 | +| 決策、原文摘要、概念知識、其餘一切 | `cards//`（pull） | 知識內容；CC 面對時自然會查 | + +> `decisions-summary.md` 已**降級為 cards + INDEX 決策視圖**（決策＝知識內容）。既有的保留為相容，不刪。 +> CC 與 Cowork **共用此判準**，產出一致：任一方寫進 push 檔或 cards，另一方看到就跳過或補充，不覆蓋。 + ### 讀 raw source 逐一讀取 raw source 的 `.md` 檔。跳過： diff --git a/template/system-dev/wiki/INDEX.md b/template/system-dev/wiki/INDEX.md index c87230c..32300ff 100644 --- a/template/system-dev/wiki/INDEX.md +++ b/template/system-dev/wiki/INDEX.md @@ -6,38 +6,55 @@ --- -## 核心檔案 +## push 檔（session 開始由 hook 主動注入，CC 行動前必看見） -| 檔案 | 何時讀 | 內容 | -|------|-------|------| -| `status.md` | session 開始第一件事 | 當前進度、下一步 | -| `mistakes.md` | 做新功能前 | 已知誤解、快速檢查清單 | -| `decisions-summary.md` | 遇到設計判斷時 | 架構決策摘要 | +| 檔案 | 注入形態 | 內容 | +|------|---------|------| +| `status.md` | 全文 | 當前進度、下一步（時態狀態）| +| `principles.md` | 全文（一行一條）| 跨全局設計原則，行動前必服從 | +| `mistakes.md` | 標題+一行症狀，全文按需展開 | 踩過的坑、被糾正的誤解（防不自覺盲區）| + +> 為什麼這三個 push 而非 pull：它們是「CC 不會主動查、但不看就出事」的盲區。詳見 `/wiki-init` 的「push vs pull」。 + +--- + +## pull：cards/（CC 按需檢索） + +一切知識內容——原文摘要、AI 筆記、決策、概念知識——都寫成 `cards//` 的概念原子卡。 +`decisions-summary.md` 已降級為 cards（決策＝知識內容）；既有的保留為相容。 --- ## 維護規則 -1. 只增不刪——記錄 append，決策改了加新條目說明「舊決策已更新」 -2. status.md 每次 session 結束更新 -3. mistakes.md 每次被糾正後 append -4. 發現新的重要決策 → 同時更新 decisions-summary.md 和 system-dev/docs/2-architecture/decisions/ +1. 只增不刪——記錄 append，內容改了加新條目說明「舊的已更新」 +2. status.md 每次 session 結束更新；mistakes/principles 一發現就 append +3. principles 一行一條、≤15 條（超過代表該合併或下放成 card） +4. **新增一個檢索角度 = 在下方「多角度視圖」加一節，不開新實體檔、不問用戶** --- -## 頂層索引：標籤視圖（由 /wiki-init 填入） +## 多角度視圖（由 /wiki-init、/wiki-capture 填入） -由 CC 改寫原文後填入。原文是唯讀 SSoT，wiki 是改寫過的記憶。 -頂層 INDEX 是**標籤視圖**（非資料夾列表），按 `TAXONOMY.md` 的軸聚類，指向各桶子索引： +INDEX 是**所有檢索角度的入口**，不只標籤。原文是唯讀 SSoT，wiki 是改寫過的記憶。 +新增角度只要在這裡加一節（如「決策角度」「原則角度」），指向對應 cards 或 push 檔——**不必新增實體特殊檔**。 + +### 標籤角度（按 `TAXONOMY.md` 的軸聚類，指向桶子索引） ```markdown -### 知識管理 +#### 知識管理 - [[pkm/00-INDEX]] — PKM 知識管理（N 卡） -### AI 協作 +#### AI 協作 - [[ai/00-INDEX]] — AI 協作（M 卡） ``` -> 結構：頂層 INDEX（標籤視圖）→ `cards//00-INDEX.md`（桶子索引，固定名）→ 概念原子卡。 +### 決策角度（取代舊 decisions-summary.md 的視圖） + +```markdown +- [[某決策卡]] — 一句話結論（YYYY-MM-DD） +``` + +> 結構：INDEX（多角度入口）→ `cards//00-INDEX.md`（桶子索引，固定名）→ 概念原子卡。 > 指 `00-INDEX` **一律帶路徑** `[[bucket/00-INDEX]]`（固定名跨桶撞名）；卡片間用裸 `[[卡名]]`。 > 分類由卡片 frontmatter `tags:` 承載，標籤字典見 `TAXONOMY.md`。詳見 `/wiki-init` 規範。 diff --git a/template/system-dev/wiki/principles.md b/template/system-dev/wiki/principles.md new file mode 100644 index 0000000..794745f --- /dev/null +++ b/template/system-dev/wiki/principles.md @@ -0,0 +1,18 @@ +# principles — 跨全局設計原則（push：CC 行動前必服從） + +> 這個檔由 hook 在 session 開始**全文注入**，讓 CC 設計任何東西前都先看見這些準繩。 +> 為什麼 push 而非寫成 card：原則是「會被遺忘的盲區」——沒推到眼前，CC 設計時很可能沒想到要服從就做了。 +> +> 規則：**一行一條**，精煉成準繩（不是長篇論述）。≤15 條；超過代表某些該合併、或下放成 card。 +> 發現新的跨全局原則 → append 一行。累積原則只改這個檔，**不必問用戶開新檔**。 +> 區分：原則 = 反覆適用的準繩（這裡）；單次選擇 = 決策（寫成 card）；踩過的坑 = mistakes.md。 + +--- + +## 原則 + + + +（尚未填入。由 /wiki-init 或 /wiki-capture 依本專案累積。）