feat: wiki 資訊架構 push/pull 判準 + principles 原則 push 檔 + bump 1.10.0
從「用戶所有檔案一律改寫成 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) <noreply@anthropic.com>
This commit is contained in:
@@ -67,15 +67,20 @@ wiki 採**三層 + 標籤橫切**架構(183 卡實證,issue #8):
|
||||
|
||||
```
|
||||
system-dev/wiki/
|
||||
├── INDEX.md ← 頂層:標籤視圖(不是資料夾列表)
|
||||
├── TAXONOMY.md ← 標籤字典(分類骨架,受控擴充:先查重再登記)
|
||||
├── status.md / mistakes.md / decisions-summary.md
|
||||
└── cards/
|
||||
└── <bucket>/ ← 儲存桶(一般專案沿用 docs 分類;vault 由 AI 重新組織)
|
||||
├── INDEX.md ← 索引:多角度視圖的家(標籤角度、決策角度、…)
|
||||
├── TAXONOMY.md ← 標籤字典(cards 的分類元資料,受控擴充)
|
||||
├── status.md ← [push] 時態狀態:當前進度、下一步
|
||||
├── mistakes.md ← [push] 踩過的坑、被糾正的誤解(防不自覺盲區)
|
||||
├── principles.md ← [push] 跨全局的設計原則(行動前必服從)
|
||||
└── cards/ ← [pull] 一切知識內容:原文摘要、AI 筆記、決策、概念…
|
||||
└── <bucket>/ ← 儲存桶(分類由 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/<bucket>/` 一律先讀它,不必猜。檔內 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,不必問用戶開新檔。**
|
||||
|
||||
### 第四步:訪談(每次一個問題)
|
||||
|
||||
依序問:
|
||||
|
||||
Reference in New Issue
Block a user