Leo
e9d6d78032
- 修崩潰：bash 3.2 + set -u 展開空陣列會炸 unbound variable；移除多餘
${SKIPPED[*]} no-op；多位元組字串旁變數改用 ${VAR} 防 curl|bash 串流切斷
- install/update 訊息依 locale 雙語，預設英文（curl|bash 常 LANG=C），zh_TW 切繁中
- 寫進 CLAUDE.md 的 raw source 宣告依 locale 只寫一種語言（不撐爆 context）
- 修措辭：一般開發案不再顯示誤導的「偵測到 vault 類型：docs」
- 新增 README.en.md（繁中↔English 切換）
- gitignore dogfooding 自裝產物（CLAUDE.md/docs 子目錄/.claude/settings*）
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
# system-dev-template
|
||
|
||
**繁體中文** | [English](README.en.md)
|
||
|
||
> 讓 Claude Code 從「猛衝的工程師」變成「有紀律的工程師」。
|
||
|
||
CC 是個優秀的工程師，但不是個好的專案經理。它會猛衝完成工作——小專案很好，大專案就會：
|
||
- **改這個壞那個**：沒有全局觀，缺乏 SDD 約束
|
||
- **文件越來越亂**：內建記憶不可靠，知識隨對話消失，而且它很喜歡寫文件，寫完也不去讀，還到處亂擺
|
||
|
||
這個模板用兩套系統解決這兩個問題：
|
||
|
||
| 系統 | 解決什麼 | 核心機制 |
|
||
|------|---------|---------|
|
||
| **SDD 系統** | 全局觀、先想再做 | 動手前必須有 design.md + tasks.md |
|
||
| **LLM Wiki** | 記憶累積、文件有序 | 雙空間：原始文件（人寫）+ .claude/wiki/（AI 整理）|
|
||
|
||
> **不只程式碼專案、不只 Claude Code。** LLM Wiki 現在也認得 **Logseq / Obsidian vault**——
|
||
> 安裝時自動偵測你在哪種資料夾，把對應的「原始文件來源」寫進 `CLAUDE.md`，整理 wiki 時只讀那裡、
|
||
> 絕不搬動 vault 結構（見下方「不只程式碼，也認得 Logseq / Obsidian vault」）。
|
||
> 整理者也不限 Claude Code——**claude.ai 的 Cowork** 可以用同一套規則掃描、整理你本機的所有 wiki
|
||
> （見下方「Cowork 也能整理 wiki」）。
|
||
|
||
- SDD：它已經很流行了，做的最徹底應該是 Amazon Kiro，但台灣無法付費，用這個方式比什麼酷炫方式更好，逼 CC 不隨心所欲。
|
||
- LLM Wiki：是大神 Karpathy 提出的最新的 RAG 想法，這是 Pre-compile 做法，比你公司買的用嵌入模型切割文件成向量的方式更優更不瑣碎，而且執行容易。
|
||
|
||
---
|
||
|
||
## 兩種使用方式
|
||
|
||
### 方式一：新專案
|
||
|
||
```bash
|
||
git clone https://github.com/uncle6me-web/system-dev-template
|
||
cp -r system-dev-template/template/. your-new-project/
|
||
cd your-new-project
|
||
```
|
||
|
||
然後在 CC 對話裡：
|
||
```
|
||
/wiki-init
|
||
```
|
||
|
||
### 方式二：已有專案（接入）
|
||
|
||
```bash
|
||
cd your-existing-project
|
||
curl -sSL https://raw.githubusercontent.com/uncle6me-web/system-dev-template/main/scripts/install.sh | bash
|
||
```
|
||
|
||
腳本只建立缺少的東西，**已有的檔案一律不動**。
|
||
|
||
**只要一塊？** 兩套系統可分開裝（有時只需要 wiki，不需要 SDD）：
|
||
|
||
```bash
|
||
# 下載後帶參數執行
|
||
curl -sSL .../install.sh -o install.sh && bash install.sh --wiki # 只裝 LLM Wiki
|
||
bash install.sh --sdd # 只裝 SDD
|
||
bash install.sh --all # 兩個都裝（預設）
|
||
```
|
||
|
||
在終端機直接跑（有 tty）時，不帶參數會**互動詢問**要裝哪一塊——對非工程背景的使用者最友善。`curl | bash` 無 tty 則安全預設為 `--all`。settings.json 的 hooks 會依選的模組自動組裝。
|
||
|
||
安裝完後在 CC 對話裡：
|
||
```
|
||
/wiki-init
|
||
```
|
||
|
||
CC 會掃描現有文件、建立 wiki、整理 docs 結構。
|
||
|
||
> CC 很喜歡寫文件到處亂擺，隨着專案越大、越久，檔案夾會很亂，但又不敢亂搬，現在把檔案夾如規範寫好，可以一次幫你把文件歸檔。
|
||
> LLM Wiki 不會動你的原檔案，但它會另外建立 Wiki，修正你的入口就是 CLAUDE.md，所以它雖然搬動，你的文件不會消失。
|
||
|
||
---
|
||
|
||
## 🔄 已安裝舊版？一鍵更新
|
||
|
||
聽到出新功能了，想升級到最新版，跑這一行就好：
|
||
|
||
```bash
|
||
cd your-project
|
||
curl -sSL https://raw.githubusercontent.com/uncle6me-web/system-dev-template/main/scripts/update.sh | bash
|
||
```
|
||
|
||
它會先比對你的版本和最新版，告訴你**多了哪些新功能**，然後：
|
||
|
||
| 動作 | 對象 |
|
||
|------|------|
|
||
| 🆕 **補上**新功能（舊版沒有的 hook / command / 範本） | 模板檔 |
|
||
| ⬆️ **更新**模板邏輯（hooks、commands、TEMPLATE-* 換成新版） | 模板檔 |
|
||
| 🔒 **完全不碰**你的內容與設定 | `wiki/status.md`、`mistakes.md`、`decisions-summary.md`、`.wikiignore`、`settings.json`、`CLAUDE.md` |
|
||
|
||
> **為什麼第一次要用 curl？** 舊版本機還沒有 `update.sh`，所以第一次得從遠端抓它下來跑。
|
||
> 跑完它會把自己也裝進 `scripts/update.sh`，**之後更新直接跑** `bash scripts/update.sh` 就好，不用再 curl。
|
||
|
||
更新只會動「已安裝的模組」（裝了 wiki 就更新 wiki，裝了 SDD 就更新 SDD），偵測自動完成。
|
||
若 `settings.json` 缺了新版才有的 hook，它不會幫你改設定，但會在結尾**列出來提醒你手動補**（不擅自動你的設定）。
|
||
|
||
📜 想知道每次改了什麼、現在是哪一版？看 **[更新紀錄 CHANGELOG](CHANGELOG.md)**。
|
||
|
||
---
|
||
|
||
## 不只程式碼，也認得 Logseq / Obsidian vault
|
||
|
||
LLM Wiki 原本假設「原始文件放在 `docs/`」，但 Logseq、Obsidian 這類筆記 vault 有自己的目錄慣例。
|
||
現在 `install.sh` 會在建立 `CLAUDE.md` 之前**自動偵測資料夾類型**，把對應的「原始文件來源（raw source）」寫進 `CLAUDE.md`：
|
||
|
||
| 偵測到 | vault 類型 | raw source（原始文件來源）|
|
||
|--------|-----------|---------------------------|
|
||
| `logseq/` 資料夾 | Logseq | `pages/`、`journals/` |
|
||
| `.obsidian/` 資料夾 | Obsidian | 根目錄下所有 `.md` |
|
||
| 都沒有 | 一般專案 | `docs/`（維持原行為）|
|
||
|
||
寫進 `CLAUDE.md` 的這段宣告是**給 AI 讀的指令**——它告訴整理者「原始文件在哪、整理 wiki 時只讀那裡」，
|
||
而且對 vault **明令不得搬動、改名、重新分類 `.md`**，整理結果一律只寫進 `.claude/wiki/`。
|
||
這樣面對筆記 vault 也不會破壞它原本的結構，筆記不會變得不可讀。
|
||
|
||
> **已有 `CLAUDE.md`？** 一律不覆蓋（維持「已有的不動」原則），改在安裝結尾**列出該補的宣告**提醒你手動貼。
|
||
|
||
---
|
||
|
||
## Cowork 也能整理 wiki
|
||
|
||
整理 wiki 的人不再只有終端機裡的 Claude Code——**claude.ai 的 Cowork** 也可以。
|
||
`docs/SKILL.md` 提供一個給 Cowork 用的 skill（`wiki-cowork-scan`），它與 CC 的 `/wiki-init`、`/wiki-capture`
|
||
**共用同一套規則**：
|
||
|
||
- 掃描 `~/Documents` 下所有裝了 system-dev-template（含 `.claude/wiki/`）的資料夾
|
||
- 用**和 `install.sh` 一致的偵測邏輯**判斷每個資料夾是一般專案 / Logseq / Obsidian
|
||
- 只讀 raw source、只往 `.claude/wiki/` 增補（不覆蓋、不刪除），**絕不動** raw source、`CLAUDE.md`、`logseq/`、`.obsidian/`、`assets/`
|
||
|
||
**CC 與 Cowork 輸出格式相同**，任一方整理過的內容，另一方看到就跳過或補充，不重複也不覆蓋。
|
||
適合掛在 Cowork 的定期排程，讓本機所有 wiki 自動保持更新。
|
||
|
||
> 想用：把 `docs/SKILL.md` 提供給你的 Cowork 當 skill 參考，再對它說「整理 wiki」即可。
|
||
|
||
---
|
||
|
||
## 目錄說明
|
||
|
||
```
|
||
system-dev-template/
|
||
├── template/ ← 複製到新專案的骨架
|
||
│ ├── CLAUDE.md ← 填空版導航牌
|
||
│ ├── docs/ ← 文件結構（六層分類）
|
||
│ └── .claude/
|
||
│ ├── wiki/ ← CC 的記憶空間（含 .wikiignore 機敏排除）
|
||
│ ├── commands/ ← Slash commands
|
||
│ ├── hooks/ ← 硬攔截（接關 + SDD 協議 + wiki 機敏掃描）
|
||
│ └── settings.json ← 掛 hooks（install.sh 依模組組裝）
|
||
│
|
||
├── skills/
|
||
│ └── llm-wiki/ ← 複製到 Legacy-Workspace/.claude/skills/
|
||
│
|
||
├── scripts/
|
||
│ ├── install.sh ← 已有專案接入腳本
|
||
│ └── update.sh ← 舊版一鍵更新（只換模板，不碰你的資料）
|
||
│
|
||
└── docs/ ← 這個 repo 自己的說明
|
||
├── why.md ← 設計理念
|
||
├── wishlist.md ← 待補功能與已完成記錄
|
||
└── SKILL.md ← 給 claude.ai Cowork 的 wiki 整理 skill（wiki-cowork-scan）
|
||
```
|
||
|
||
---
|
||
|
||
## Slash Commands
|
||
|
||
安裝後在任何 CC 對話裡可用：
|
||
|
||
| Command | 做什麼 |
|
||
|---------|-------|
|
||
| `/wiki-init` | 初始化 wiki（新專案或接入已有專案）|
|
||
| `/wiki-recall` | Session 開始，手動接關（hook 沒啟動時的 fallback）|
|
||
| `/wiki-capture` | 把這次對話的結論存進 wiki |
|
||
| `/wiki-update` | Session 結束，更新 status.md |
|
||
| `/sdd-check` | 確認當前任務有沒有對應 SDD |
|
||
| `/issue-handle` | 處理 GitHub issue（讀回自己 repo / 跨 repo 發要先問 / 禁自動輪詢）|
|
||
|
||
命名閉環：init(建) → update(存，session 末) ↔ recall(接，session 初) → capture(隨時存結論)。
|
||
|
||
---
|
||
|
||
## Hooks（軟規範 → 硬攔截）
|
||
|
||
規範不再只是 CLAUDE.md 的軟提醒，加了底線機制：
|
||
|
||
| Hook | 角色 |
|
||
|------|------|
|
||
| `session-start-recall.sh` | 開 session 自動注入 status 重點，不靠 CC 自覺 |
|
||
| `sdd-guard.sh` | 動 code 檔但沒有任何 SDD → 攔（exit 2），對應 `/sdd-check` 的自動版 |
|
||
| `wiki-secret-scan.sh` | 機敏值要寫進 `.claude/wiki/` → 攔（exit 2），密碼/金鑰/個資的機械底線 |
|
||
| `pre-write-guard.sh` | 專案自訂禁令範本骨架（預設停用，填 pattern 才生效）|
|
||
|
||
---
|
||
|
||
## Wiki 機敏防護（不想被編入的內容）
|
||
|
||
像 `.gitignore` 一樣，讓不想進 wiki 的內容（密碼、金鑰、個資）不被編入。三層：
|
||
|
||
| 層 | 機制 | 擋什麼 | 性質 |
|
||
|----|------|--------|------|
|
||
| **L1** | `.claude/wiki/.wikiignore`（glob） | 整個機敏檔不編入 | 協議（CC 遵守）|
|
||
| **L2** | 行內標記 `<!-- wiki:ignore -->`…`<!-- wiki:end -->` | 檔案內某段不編入 | 協議（CC 遵守）|
|
||
| **L3** | `wiki-secret-scan.sh` hook | 機敏值真的寫進 wiki → exit 2 擋 | **硬攔截（機械偵測）**|
|
||
|
||
L1/L2 是你主動標記，L3 是自動兜底——萬一 CC 漏掉前兩層，寫進 wiki 的那一刻會被 regex 攔下（密碼賦值、PEM 私鑰、AWS/GitHub/Slack 金鑰、JWT、連線字串帳密、身分證、信用卡號）。
|
||
|
||
> 誠實限制：L1/L2 靠 CC 自律，L3 靠特徵比對（有偽陽/偽陰）。
|
||
> 這是「減少**意外**外洩」的機制，不是保險箱——真正的密鑰本就不該進版控。
|
||
> 誤判時：該行尾加 `wiki-secret-ok` 放行；整檔機敏則加進 `.wikiignore`。
|
||
|
||
> 誠實限制：hook 擋語法層明顯違規（直接寫檔），擋不了藏在 helper / bash 裡的繞道。
|
||
> 價值是「想跳過會被抓到 + 留痕可審」，不是技術防偽——文檔（mindset）+ hook（底線）都不可省。
|
||
|
||
---
|
||
|
||
## 設計原則
|
||
|
||
- **疊加，不覆蓋**：接入已有專案時，現有規範保留，wiki 系統疊上去
|
||
- **結構即協議**：CC 和你共用同一個分類系統，不需要每次解釋
|
||
- **CLAUDE.md 不增長**：超過 100 行就是架構出問題，不是加更多內容
|
||
- **對話結論當場 capture**：討論完用 `/wiki-capture`，知識不再消失
|
||
|
||
---
|
||
|
||
## 致謝
|
||
|
||
這個模板站在巨人的肩膀上：
|
||
|
||
- **[Andrej Karpathy](https://gist.github.com/karpathy)** — LLM Wiki 概念的提出者。本模板的雙空間記憶系統直接源自他 2026 年 4 月的構想：用 LLM 把知識「pre-compile」成互相連結的 markdown，而非每次查詢都重跑 embedding 檢索。他的一句話道盡精神：*"Obsidian is the IDE, the LLM is the programmer, the wiki is the codebase."*
|
||
- 概念延伸閱讀：[The Andrej Karpathy LLM Wiki Idea](https://reliabilitywhisperer.substack.com/p/the-andrej-karpathy-llm-wiki-idea)、[Beyond RAG (Level Up Coding)](https://levelup.gitconnected.com/beyond-rag-how-andrej-karpathys-llm-wiki-pattern-builds-knowledge-that-actually-compounds-31a08528665e)
|
||
|
||
- **[Amazon Kiro](https://aws.amazon.com/documentation-overview/kiro/)** — 本模板的 SDD（Spec-Driven Development）做法學自 Kiro。它把「動手前先有結構化規格」這件事做到最徹底；台灣雖然付費不便，但它的方法論值得致敬與借鑑。
|
||
|
||
- **Claude（Claude Code / Anthropic）** — 本模板的 hooks、機敏防護、模組化安裝與這份說明，都是與 Claude 結對開發完成的。模板本身就是為了讓 Claude Code「從猛衝的工程師變成有紀律的工程師」——它既是工具，也是共同作者。
|