Leo/system-dev-template
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
richblack
2026-06-08 16:06:18 +08:00
commit 8aa1b68ca0
19 changed files with 1284 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+9
View File
@@ -0,0 +1,9 @@
# .gitignore
# macOS
.DS_Store
# 環境變數
.env
.env.*
!.env.example
README.md
+100
View File
@@ -0,0 +1,100 @@
# system-dev-template
> 讓 Claude Code 從「猛衝的工程師」變成「有紀律的工程師」。
CC 是個優秀的工程師，但不是個好的專案經理。它會猛衝完成工作——小專案很好，大專案就會：
- **改這個壞那個**：沒有全局觀，缺乏 SDD 約束
- **文件越來越亂**：內建記憶不可靠，知識隨對話消失，而且它很喜歡寫文件，寫完也不去讀，還到處亂擺
這個模板用兩套系統解決這兩個問題：
| 系統 | 解決什麼 | 核心機制 |
|------|---------|---------|
| **SDD 系統** | 全局觀、先想再做 | 動手前必須有 design.md + tasks.md |
| **LLM Wiki** | 記憶累積、文件有序 | 雙空間：docs/（人寫）+ .claude/wiki/（CC 整理）|
- SDD：它已經很流行了，做的最徹底應該是 Amazon Kiro，但台灣無法付費，用這個方式比什麼酷炫方式更好，逼 CC 不隨心所欲。
- LLM Wiki：是大神 Kaparthy 提出的最新的 RAG 想法，這是 Pre-compile 做法，比你公司買的用嵌入模型切割文件成向量的方式更優更不瑣碎，而且執行容易。
---
## 兩種使用方式
### 方式一：新專案
```bash
git clone https://github.com/richblack/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/richblack/system-dev-template/main/scripts/install.sh | bash
```
腳本只建立缺少的東西，**已有的檔案一律不動**。
安裝完後在 CC 對話裡：
```
/wiki-init
```
CC 會掃描現有文件、建立 wiki、整理 docs 結構。
> CC 很喜歡寫文件到處亂擺，隨着專案越大、越久，檔案夾會很亂，但又不敢亂搬，現在把檔案夾如規範寫好，可以一次幫你把文件歸檔。
> LLM Wiki 不會動你的原檔案，但它會另外建立 Wiki，修正你的入口就是 CLAUDE.md，所以它雖然搬動，你的文件不會消失。
---
## 目錄說明
```
system-dev-template/
├── template/ ← 複製到新專案的骨架
│ ├── CLAUDE.md ← 填空版導航牌
│ ├── docs/ ← 文件結構（六層分類）
│ └── .claude/
│ ├── wiki/ ← CC 的記憶空間
│ └── commands/ ← Slash commands
│
├── skills/
│ └── llm-wiki/ ← 複製到 Legacy-Workspace/.claude/skills/
│
├── scripts/
│ └── install.sh ← 已有專案接入腳本
│
└── docs/ ← 這個 repo 自己的說明
├── why.md ← 設計理念
├── sdd-guide.md ← SDD 系統說明
└── llm-wiki-guide.md
```
---
## Slash Commands
安裝後在任何 CC 對話裡可用：
| Command | 做什麼 |
|---------|-------|
| `/wiki-init` | 初始化 wiki（新專案或接入已有專案）|
| `/wiki-capture` | 把這次對話的結論存進 wiki |
| `/wiki-update` | Session 結束，更新 status.md |
| `/sdd-check` | 確認當前任務有沒有對應 SDD |
---
## 設計原則
- **疊加，不覆蓋**：接入已有專案時，現有規範保留，wiki 系統疊上去
- **結構即協議**：CC 和你共用同一個分類系統，不需要每次解釋
- **CLAUDE.md 不增長**：超過 100 行就是架構出問題，不是加更多內容
- **對話結論當場 capture**：討論完用 `/wiki-capture`，知識不再消失
docs/why.md
+70
View File
@@ -0,0 +1,70 @@
# 為什麼需要這個模板
## CC 是個優秀的工程師，但不是個好的專案經理
Claude Code 執行力強、速度快。小專案裡這是優點，大專案裡變成問題：
**問題一：改這個壞那個**
CC 沒有全局觀。它在每個 session 裡從零開始，不知道上次做了什麼、哪些東西不能動、
為什麼做了這個決定。結果就是：修了 A，壞了 B，下次又把 B 修回來，再壞了 A。
**問題二：文件越來越亂，記憶不可靠**
隨著開發，對話裡累積了大量決策、踩坑記錄、架構說明。但這些知識：
- 存在對話歷史裡，新 session 全部消失
- 就算寫成文件，散落在根目錄、各種 md 裡，CC 找不到
- 即使找到了，是給人看的語言，不是給 LLM 的格式
最後的結果：**你變成那個唯一的記憶**。你要重複解釋同樣的事，
CC 要重複犯同樣的錯。
---
## 兩套系統，解決兩個問題
### SDD 系統：給 CC 全局觀
靈感來自 Kiro 的做法。核心原則只有一條：**動手前必須有設計文件**。
```
使用者提需求
↓
CC 找對應 SDD（docs/3-specs/[子系統]/design.md）
↓
找到 → 讀 design.md + tasks.md，宣告範圍再動手
找不到 → 停手問使用者，不自行猜測
```
SDD 強制 CC 在動手前先思考：這個修改影響哪些地方？有沒有超出範圍？
有沒有違反既定的技術限制？
### LLM Wiki：給 CC 可累積的記憶
靈感來自 Andrej Karpathy 的 LLM Wiki 概念——不用 embedding，
只靠 pre-compile 把知識整理成 LLM 友善的格式。
**雙空間設計：**
- `docs/`：人寫的原始文件，依照開發生命週期分類
- `.claude/wiki/`：CC 整理的 LLM 友善知識，每次 session 累積
每次 session 開始，CC 讀 wiki，不需要重新學習。
每次 session 結束，CC 更新 wiki，知識不再消失。
---
## 設計原則
**疊加，不覆蓋**
接入已有專案時，現有的規範、文件、CLAUDE.md 全部保留，
新系統疊加上去，不破壞已有的東西。
**結構即協議**
固定的目錄結構讓 CC 和你共用同一套分類規則。
你把任何文件丟進來，CC 知道要收到哪裡。
**CLAUDE.md 不增長**
CLAUDE.md 是導航牌，不是內容倉庫。超過 100 行就是架構出問題，
不是加更多內容的信號。
**對話結論必須 capture**
最重要的知識往往在對話裡，不在文件裡。
`/wiki-capture` 解決這個問題：討論完當場存，知識不再隨對話消失。
scripts/install.sh
+113
View File
@@ -0,0 +1,113 @@
#!/bin/bash
# system-dev-template installer
# 已有專案接入腳本——只建立缺少的東西，已有的一律不動
set -e
REPO_URL="https://raw.githubusercontent.com/richblack/system-dev-template/main/template"
CREATED=()
SKIPPED=()
echo ""
echo "🔧 system-dev-template installer"
echo "================================="
echo "只建立缺少的目錄和檔案，已有的不動。"
echo ""
# ── 目錄 ──────────────────────────────────────────
create_dir() {
if [ ! -d "$1" ]; then
mkdir -p "$1"
CREATED+=("$1/")
else
SKIPPED+=("$1/ (已存在)")
fi
}
create_dir "docs/1-vision"
create_dir "docs/2-architecture/decisions"
create_dir "docs/3-specs"
create_dir "docs/4-guides"
create_dir "docs/5-records/incidents"
create_dir "docs/5-records/test-reports"
create_dir "docs/6-user"
create_dir ".claude/wiki"
create_dir ".claude/commands"
# ── 檔案（從 repo 下載，只在不存在時）──────────────
download_if_missing() {
local dest="$1"
local src="$2"
if [ ! -f "$dest" ]; then
curl -sSL "$src" -o "$dest"
CREATED+=("$dest")
else
SKIPPED+=("$dest (已存在，跳過)")
fi
}
# wiki 核心檔案
download_if_missing ".claude/wiki/INDEX.md" "$REPO_URL/.claude/wiki/INDEX.md"
download_if_missing ".claude/wiki/status.md" "$REPO_URL/.claude/wiki/status.md"
download_if_missing ".claude/wiki/mistakes.md" "$REPO_URL/.claude/wiki/mistakes.md"
download_if_missing ".claude/wiki/decisions-summary.md" "$REPO_URL/.claude/wiki/decisions-summary.md"
# slash commands
download_if_missing ".claude/commands/wiki-init.md" "$REPO_URL/.claude/commands/wiki-init.md"
download_if_missing ".claude/commands/wiki-capture.md" "$REPO_URL/.claude/commands/wiki-capture.md"
download_if_missing ".claude/commands/wiki-update.md" "$REPO_URL/.claude/commands/wiki-update.md"
download_if_missing ".claude/commands/sdd-check.md" "$REPO_URL/.claude/commands/sdd-check.md"
# docs/README.md（分類地圖）
download_if_missing "docs/README.md" "$REPO_URL/docs/README.md"
# CLAUDE.md：只在完全不存在時建立
if [ ! -f "CLAUDE.md" ]; then
download_if_missing "CLAUDE.md" "$REPO_URL/CLAUDE.md"
else
SKIPPED+=("CLAUDE.md (已存在，請手動加入 wiki 讀取順序區塊)")
fi
# ── 輸出結果 ──────────────────────────────────────
echo ""
echo "✅ 建立了："
for item in "${CREATED[@]}"; do
echo " + $item"
done
if [ ${#SKIPPED[@]} -gt 0 ]; then
echo ""
echo "⚠️ 跳過（已存在）："
for item in "${SKIPPED[@]}"; do
echo " - $item"
done
fi
echo ""
echo "─────────────────────────────────"
# 如果 CLAUDE.md 已存在，提醒手動加入 wiki 區塊
if [ -f "CLAUDE.md" ]; then
if ! grep -q "wiki/status.md" CLAUDE.md; then
echo ""
echo "📌 CLAUDE.md 已存在但缺少 wiki 讀取順序。"
echo " 請手動加入以下區塊："
echo ""
echo ' ## Wiki 讀取順序'
echo ' | 檔案 | 時機 | 用途 |'
echo ' |------|------|------|'
echo ' | `.claude/wiki/status.md` | session 開始第一件事 | 當前進度 |'
echo ' | `.claude/wiki/mistakes.md` | 做新功能前 | 已知誤解 |'
echo ' | `.claude/wiki/decisions-summary.md` | 設計判斷時 | 架構決策 |'
fi
fi
echo ""
echo "🚀 下一步：在 Claude Code 對話裡執行："
echo " /wiki-init"
echo ""
echo " CC 會掃描現有文件、建立 wiki、整理 docs 結構。"
echo ""
skills/llm-wiki/SKILL.md
+134
View File
@@ -0,0 +1,134 @@
---
name: llm-wiki
description: >-
為任何開發專案建立或維護 LLM Wiki 記憶系統——一套讓 CC（Claude Code）不再重複犯錯、
不忘決策脈絡的雙空間文件結構。觸發時機：
（1）新專案 init——「幫我建立 wiki 系統」「新專案要設置文件結構」；
（2）老專案 migrate——「幫我整理文件」「文件太亂了」「散落的 md 幫我收一收」；
（3）對話結論 capture——「把剛才的討論記下來」「這個決定要存起來」「我不想再解釋一次」；
（4）wiki 更新——「更新 status」「記錄這個 mistake」「加一條決策」。
只要涉及「讓 CC 記住某件事」或「整理專案文件讓 CC 好找」，都用這個 skill。
---
# LLM Wiki Skill
讓 CC 不再是失憶的協作者。這個 skill 幫你在任何專案裡建立一套
**人寫文件 + CC 整理 wiki** 的雙空間系統，讓每次 session 都能無縫接上。
靈感來源：Andrej Karpathy 的 LLM Wiki 概念——不用 embedding，
只靠 pre-compile 把知識整理成 LLM 友善的格式。
---
## 四種使用情境
| 情境 | 觸發訊號 | 跳到 |
|------|---------|------|
| **A. 新專案 init** | 空專案、剛開始 | → [流程 A](#流程-a新專案-init) |
| **B. 老專案 migrate** | 已有文件但很亂 | → [流程 B](#流程-b老專案-migrate) |
| **C. 對話結論 capture** | 剛討論完某個決策 | → [流程 C](#流程-c對話結論-capture) |
| **D. Wiki 日常更新** | session 結束、踩到坑 | → [流程 D](#流程-d-wiki-日常更新) |
---
## 雙空間架構
```
專案根目錄/
├── CLAUDE.md ← 導航牌，≤100 行，永遠不增長
├── docs/ ← 原始文件空間（人寫，CC 讀）
│ ├── README.md
│ ├── 1-vision/
│ ├── 2-architecture/decisions/
│ ├── 3-specs/
│ ├── 4-guides/
│ ├── 5-records/{incidents,test-reports}/
│ └── 6-user/
└── .claude/wiki/ ← CC 整理的知識（CC 寫）
├── INDEX.md
├── mistakes.md
├── status.md
└── decisions-summary.md
```
三條原則：docs/ 人寫 CC 不改 | wiki/ CC 維護 | CLAUDE.md ≤100 行
詳細格式見 `references/templates.md`。
---
## 流程 A：新專案 Init
1. 建立目錄結構
2. 依 `references/templates.md` 建立六個核心檔案
3. 訪談（每次一個問題）：做什麼 / 技術限制 / 技術棧 / 現有規範
4. 填入 CLAUDE.md，完成確認
---
## 流程 B：老專案 Migrate
⚠️ 三個階段，每階段等確認再繼續。
**階段一：掃描 + 分類計畫**
遞迴找所有 .md，標注建議位置和信心度，列清單等確認。
分類規則：
```
子系統設計文件 → docs/3-specs/[子系統]/
為什麼做某決定 → docs/2-architecture/decisions/
怎麼操作 → docs/4-guides/
歷史記錄 → docs/5-records/
給使用者看的 → docs/6-user/
不確定 → 列為「待確認」，問使用者
```
**階段二：讀文件，建 wiki**
每個文件讀完後提取到對應 wiki 檔案，全部讀完後展示結果等確認。
**階段三：歸檔**
按確認好的分類移動，根目錄只留必要項目，更新 CLAUDE.md 路徑。
---
## 流程 C：對話結論 Capture
這是最容易被忘記、也最重要的情境。
| 內容類型 | 存到哪 |
|---------|-------|
| 架構決策 | `decisions-summary.md` + `docs/2-architecture/decisions/[日期]-[主題].md` |
| CC 誤解被糾正 | `mistakes.md` |
| 狀態更新 | `status.md` |
操作：辨識 → 列清單給使用者確認 → 寫入 → 告知存到哪裡
**Mistakes 格式：**
```
⚠️ MISTAKE: [錯誤描述]
症狀: [CC 的表現]
正確做法: [應該怎麼做]
原因: [背景]
日期: [YYYY-MM-DD]
```
---
## 流程 D：Wiki 日常更新
Session 結束時固定更新 status.md：
- 這次做了什麼
- 遇到什麼問題
- 下次從哪裡開始
- 有新誤解 → 同時 append mistakes.md
- 有新決策 → 同時 append decisions-summary.md
---
## 維護規則
1. `docs/` 只讀不改
2. `.claude/wiki/` 只增不刪
3. `CLAUDE.md` 不增長，超過 100 行就是放錯地方
4. 分類不確定就問
5. 對話結論當場 capture
skills/llm-wiki/references/templates.md
+250
View File
@@ -0,0 +1,250 @@
# LLM Wiki 範本集
---
## CLAUDE.md 範本
```markdown
# CLAUDE.md — [專案名稱]
> 導航牌。細節在兩個地方，不在這裡。
> Hook 機制在 `.claude/hooks/`（如果有的話）。
---
## 絕對鐵律（違反 = 停手）
1. [專案最重要的限制，例如：任何 code 變動前必須先讀 SDD]
2. [技術棧限制]
3. [...]
找不到對應文件 → **停手問 [負責人名稱]**，不要自行決定。
---
## 工作流程（強制）
開始任一任務，按順序：
1. 讀 `.claude/wiki/status.md`（3 分鐘）
2. 確認有對應 SDD（`docs/3-specs/`）
3. 動手前宣告範圍
4. 完成後更新 wiki
---
## Wiki 讀取順序
| 檔案 | 時機 | 用途 |
|------|------|------|
| `.claude/wiki/status.md` | session 開始第一件事 | 當前進度、下一步 |
| `.claude/wiki/mistakes.md` | 做新功能前 | 已知誤解 + 快速檢查清單 |
| `.claude/wiki/decisions-summary.md` | 遇到設計判斷時 | 架構決策快速查 |
| `.claude/wiki/INDEX.md` | 找不到東西時 | wiki 導引 |
---
## 規範索引
| 檔案 | 內容 |
|-----|------|
| [規範檔路徑] | [說明] |
---
## 文件位置
| 類別 | 位置 |
|------|------|
| 原始文件 | `docs/`（見 `docs/README.md`） |
| 架構決策 | `docs/2-architecture/decisions/` |
| SDD | `docs/3-specs/` |
| 操作手冊 | `docs/4-guides/` |
| 事件記錄 | `docs/5-records/incidents/` |
```
---
## docs/README.md 範本
```markdown
# [專案名稱] 文件分類索引
## 分類規則
| 目錄 | 放什麼 | 例子 |
|------|--------|------|
| **1-vision/** | 為什麼做這個 | 產品願景、北極星 |
| **2-architecture/** | 系統怎麼設計的 | MVP 架構、元件關係 |
| **2-architecture/decisions/** | 架構決策（為什麼選A不選B）| ADR 文件 |
| **3-specs/** | 需求和 SDD | design.md + tasks.md |
| **4-guides/** | 操作手冊：怎麼做 | 部署、CLI 用法 |
| **5-records/** | 歷史記錄 | 壓測報告、問題追蹤 |
| **5-records/incidents/** | 生產問題復盤 | 故障原因、改進方案 |
| **5-records/test-reports/** | 測試結果 | 功能驗收、效能測試 |
| **6-user/** | 對外文件 | self-hosted 安裝、FAQ |
## 分類判斷規則
- 子系統設計文件 → `3-specs/[子系統]/`
- 決策記錄（為什麼）→ `2-architecture/decisions/`
- 操作說明（怎麼做）→ `4-guides/`
- 歷史記錄（發生過）→ `5-records/`
- 給外部使用者看的 → `6-user/`
- 不確定 → 列為「待確認」，問使用者
```
---
## .claude/wiki/INDEX.md 範本
```markdown
# .claude/wiki/ — [專案名稱] LLM 記憶系統
> 新 session 開始時從這裡導航。
> 目的：讓 CC 不需要重新學習已知的事。
## 核心檔案
| 檔案 | 何時讀 | 內容 |
|------|-------|------|
| `status.md` | session 開始第一件事 | 當前進度、下一步 |
| `mistakes.md` | 做新功能前 | 已知誤解、快速檢查清單 |
| `decisions-summary.md` | 遇到設計判斷時 | 架構決策摘要 |
## 維護規則
- `mistakes.md`：只 append，不刪除
- `status.md`：每次 session 結束更新
- `decisions-summary.md`：重大決策後更新
- 所有 wiki 檔案：CC 維護，不是人類維護的地方
```
---
## .claude/wiki/mistakes.md 範本
```markdown
# CC 已知誤解 + 避坑方法
> 做新功能前讀一遍。格式：每條必須有症狀 + 正確做法 + 原因。
## 快速檢查清單
- [ ] 有對應 SDD 嗎？沒有 → 停手
- [ ] 這次修改影響哪些模組？有沒有連帶破壞？
- [ ] 驗收標準是什麼？有客觀證據嗎？
## 誤解記錄
（初始化時為空，隨專案進行 append）
```
---
## .claude/wiki/decisions-summary.md 範本
```markdown
# 架構決策摘要
> 遇到設計判斷時查這裡。完整脈絡在 docs/2-architecture/decisions/。
（初始化時為空，隨專案進行 append）
格式：
## [主題] — [YYYY-MM-DD]
**結論**：[一句話]
**原因**：[簡短說明]
**詳細**：docs/2-architecture/decisions/[對應檔案]
```
---
## ADR 範本（docs/2-architecture/decisions/YYYY-MM-DD-topic.md）
```markdown
# [主題]
**日期**：[YYYY-MM-DD]
**狀態**：[提議中 / 已採納 / 已廢棄]
## 背景
[為什麼需要做這個決定？]
## 決定
[結論，一句話]
## 原因
[詳細說明]
## 放棄的選項
| 選項 | 放棄原因 |
|------|---------|
| [選項 A] | [原因] |
## 影響
[影響哪些地方，有什麼後續要注意]
```
---
## SDD design.md 範本（docs/3-specs/[子系統]/design.md）
```markdown
# [子系統] — Design
> 狀態：[草稿 / 已採納]
> 建立：[YYYY-MM-DD]
## 一句話說明
## 背景與問題
## 範圍
In Scope：
Out of Scope：
## 設計
### 架構概覽
### 關鍵決策
### API 定義
### 資料模型
## 技術限制
## 驗收標準
- [ ] [可客觀驗證的條件]
```
---
## SDD tasks.md 範本（docs/3-specs/[子系統]/tasks.md）
```markdown
# [子系統] — Tasks
> 動手前標 [🔄]，完成立刻標 [x]，不批次更新。
## Phase 1：[名稱]
- [ ] 1.1 [task 描述]
- 驗收：[客觀標準]
## 狀態說明
| 標記 | 意義 |
|------|------|
| `[ ]` | 未開始 |
| `[🔄]` | 進行中 |
| `[x]` | 完成 |
| `[~]` | 暫緩 |
| `[!]` | 阻擋中 |
```
template/.claude/commands/sdd-check.md
+55
View File
@@ -0,0 +1,55 @@
# /sdd-check — 確認當前任務有沒有對應 SDD
動手前執行。確保 CC 有全局觀，不會在沒有設計文件的情況下猛衝。
---
## 執行流程
### 第一步：理解任務
確認使用者要做什麼：
- 涉及哪個子系統？
- 是新功能還是修改現有功能？
- 影響範圍？
### 第二步：尋找對應 SDD
在 `docs/3-specs/` 下尋找對應的子系統目錄，確認有沒有：
- `design.md`（設計文件）
- `tasks.md`（任務清單）
### 第三步：根據結果回應
**情況 A：找到對應 SDD**
```
✅ 找到 SDD：docs/3-specs/[子系統]/
📋 design.md：[確認]
📋 tasks.md：[確認，列出相關 task]
🎯 對應 task：[編號和描述]
繼續嗎？
```
**情況 B：找不到 SDD，任務明確**
```
⚠️ 找不到對應 SDD
任務：[描述]
建議在 docs/3-specs/[建議子系統名]/ 建立 SDD
要我幫你起草 design.md 嗎？（需要你確認後才動手）
```
**情況 C：找不到 SDD，任務模糊**
```
⚠️ 找不到對應 SDD，而且任務範圍不夠清楚
請先回答：
1. 這個功能屬於哪個子系統？
2. 完成的標準是什麼？
3. 有沒有不能動的邊界？
```
### 注意
- 找不到 SDD **不等於可以直接動手**
- 小修改（修 bug、改文字）可以豁免，但要明確說「這是小修改，範圍是 X」
- 新功能、架構變動、跨模組的修改 → 一定要有 SDD
template/.claude/commands/wiki-capture.md
+61
View File
@@ -0,0 +1,61 @@
# /wiki-capture — 把對話結論存進 wiki
把這次對話中產生的決策、誤解釐清、或重要結論存入 wiki。
解決「討論過了但知識消失」的問題。
---
## 執行流程
### 第一步：辨識對話中的可記錄內容
掃描當前對話，找出：
| 類型 | 判斷標準 | 存到哪 |
|------|---------|-------|
| 架構決策 | 「為什麼選A不選B」「我們決定用X」 | `decisions-summary.md` + `docs/2-architecture/decisions/` |
| CC 的誤解被糾正 | CC 說了某件事，使用者說「不是，是...」 | `mistakes.md` |
| 重要狀態更新 | 完成了某件事、阻擋了某件事 | `status.md` |
| 技術發現 | 踩到坑、找到解法、重要行為確認 | `mistakes.md` 或對應 SDD |
### 第二步：列出清單給使用者確認
格式：
```
這次對話我整理了以下內容要存入 wiki：
1. [MISTAKE] CC 誤解了 X，正確是 Y
2. [DECISION] 決定用 A 不用 B，原因是 C
3. [STATUS] 完成了 task 2.3，下一步是 2.4
確認後存入，有需要修改的嗎？
```
**停下來等確認。**
### 第三步：寫入
確認後，依照格式寫入對應檔案：
**mistakes.md 格式：**
```
⚠️ MISTAKE: [錯誤描述]
症狀: [CC 的表現]
正確做法: [應該怎麼做]
原因: [背景]
日期: [YYYY-MM-DD]
```
**decisions-summary.md 格式：**
```
## [主題] — [YYYY-MM-DD]
**結論**：[一句話]
**原因**：[簡短說明]
**詳細**：docs/2-architecture/decisions/[檔名]
```
重大決策同時在 `docs/2-architecture/decisions/` 建立 ADR 檔案。
### 第四步：確認
告知存到哪些檔案，共幾條記錄。
template/.claude/commands/wiki-init.md
+77
View File
@@ -0,0 +1,77 @@
# /wiki-init — 初始化或接入 LLM Wiki 系統
初始化這個專案的 LLM Wiki 記憶系統。
新專案建立空白結構，已有專案掃描現有文件並建立 wiki。
---
## 執行流程
### 第一步：偵測專案狀態
檢查以下項目，判斷是新專案還是已有專案：
- 根目錄有沒有 `.claude/wiki/`
- 根目錄有沒有 `docs/`
- 有沒有散落的 `.md` 檔案
**新專案**（幾乎空的）→ 直接建立結構，跳到第三步
**已有專案**（有文件）→ 執行第二步
### 第二步：已有專案的掃描（已有專案才執行）
1. 遞迴找出所有 `.md` 檔案
2. 對每個檔案標注建議位置和信心度
3. 列出清單給使用者確認，**停下來等確認**
分類規則：
```
有明確子系統 + 設計內容 → 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/
```
檔案（不存在才建）：
- `.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`（如果存在）或建立新的。
### 第五步：已有專案的文件歸檔
（第二步確認後執行）
按照確認好的分類移動檔案，完成後更新 `CLAUDE.md` 的路徑引用。
### 第六步：完成報告
告知：
```
✅ wiki-init 完成
建立了：[列出新建的目錄和檔案]
跳過了：[列出已有因此不動的]
下一步：用 /wiki-capture 把重要決策存進 wiki
```
template/.claude/commands/wiki-update.md
+50
View File
@@ -0,0 +1,50 @@
# /wiki-update — Session 結束，更新狀態
每次 session 結束時執行。更新 status.md，確保下次 session 能無縫接上。
---
## 執行流程
### 第一步：整理這次 session 的結果
從對話中提取：
- 完成了哪些 tasks（標記為 [x]）
- 進行中但未完成的（標記為 [🔄]）
- 遇到什麼問題或阻擋
- 下次應該從哪裡開始
### 第二步：更新 tasks.md
把對應 SDD 的 tasks.md 狀態更新（如果這次有動到的話）。
### 第三步：更新 status.md
用以下格式覆蓋 status.md：
```markdown
# 當前狀態
> 更新時間：[YYYY-MM-DD]
## 正在做
- [🔄] [task 描述] — 阻擋點：[如果有]
## 下次 session 第一件事
[具體的第一個動作，越具體越好]
## 待負責人確認
- [描述] — 等待：[什麼決定]
## 已知問題
| 問題 | 優先級 | 狀態 |
|------|--------|------|
| [問題] | 🔴/🟡/⚪ | [狀態] |
```
### 第四步：如果有新的誤解或決策
順帶執行 `/wiki-capture` 的邏輯，把這次的誤解和決策也存進去。
### 第五步：確認
告知 status.md 更新完成，下次 session 從哪裡開始。
template/.claude/wiki/INDEX.md
+30
View File
@@ -0,0 +1,30 @@
# .claude/wiki/ — LLM 記憶系統
> 新 session 開始時從這裡導航。
> 目的：讓 CC 不需要重新學習已知的事。
> 維護者：CC（人不手動編輯這裡）
---
## 核心檔案
| 檔案 | 何時讀 | 內容 |
|------|-------|------|
| `status.md` | session 開始第一件事 | 當前進度、下一步 |
| `mistakes.md` | 做新功能前 | 已知誤解、快速檢查清單 |
| `decisions-summary.md` | 遇到設計判斷時 | 架構決策摘要 |
---
## 維護規則
1. 只增不刪——記錄 append，決策改了加新條目說明「舊決策已更新」
2. status.md 每次 session 結束更新
3. mistakes.md 每次被糾正後 append
4. 發現新的重要決策 → 同時更新 decisions-summary.md 和 docs/2-architecture/decisions/
---
## 快速導航（由 /wiki-init 填入）
（初始化後由 CC 根據專案特性填入）
template/.claude/wiki/decisions-summary.md
+14
View File
@@ -0,0 +1,14 @@
# 架構決策摘要
> 遇到設計判斷時查這裡。
> 完整脈絡在 docs/2-architecture/decisions/。
---
（初始化時為空，隨專案進行 append）
格式：
## [主題] — [YYYY-MM-DD]
**結論**：[一句話]
**原因**：[簡短說明]
**詳細**：docs/2-architecture/decisions/[對應檔案]
template/.claude/wiki/mistakes.md
+25
View File
@@ -0,0 +1,25 @@
# CC 已知誤解 + 避坑方法
> 做新功能前讀一遍。
> 格式：每條必須有症狀 + 正確做法 + 原因。
---
## 快速檢查清單（做任何事前）
- [ ] 有對應 SDD 嗎？沒有 → 停手
- [ ] 這次修改會影響哪些模組？有沒有連帶破壞？
- [ ] 驗收標準是什麼？有客觀證據嗎？
---
## 誤解記錄
（初始化時為空，隨專案進行 append）
格式：
⚠️ MISTAKE: [錯誤描述，一句話]
症狀: [CC 通常怎麼表現這個錯]
正確做法: [應該怎麼做]
原因: [為什麼會錯]
日期: [YYYY-MM-DD]
template/.claude/wiki/status.md
+22
View File
@@ -0,0 +1,22 @@
# 當前狀態
> 更新時間：[初始化時填入]
> 每次 session 結束必須更新此檔。
---
## 正在做
（初始化後填入）
## 下次 session 第一件事
（初始化後填入）
## 待負責人確認
（無）
## 已知問題
（無）
template/CLAUDE.md
+62
View File
@@ -0,0 +1,62 @@
# CLAUDE.md — [專案名稱]
> 導航牌。細節在兩個地方，不在這裡。
> 這個檔案不增長——超過 100 行就是放錯地方了。
---
## 絕對鐵律（違反 = 停手）
1. **任何 code 變動前必須有對應 SDD**（`docs/3-specs/[子系統]/design.md`）
2. [技術棧限制，例如：前端只用 React，不引入其他框架]
3. [其他專案特定限制]
找不到對應 SDD → **停手問 [負責人]**，不要自行建立。
---
## 工作流程（強制）
開始任一任務，按順序：
1. 讀 `.claude/wiki/status.md`（3 分鐘，了解當前狀態）
2. 確認有對應 SDD（`docs/3-specs/`）
3. 在回覆開頭宣告：
```
📋 已讀 SDD：<路徑>
🎯 對應 task：<編號>
🚧 執行範圍：<會動哪些檔案>
```
4. 完成後更新 `.claude/wiki/status.md`
---
## Wiki 讀取順序
| 檔案 | 時機 | 用途 |
|------|------|------|
| `.claude/wiki/status.md` | session 開始第一件事 | 當前進度、下一步 |
| `.claude/wiki/mistakes.md` | 做新功能前 | 已知誤解 + 快速檢查清單 |
| `.claude/wiki/decisions-summary.md` | 遇到設計判斷時 | 架構決策快速查 |
---
## 規範索引
| 檔案 | 內容 |
|------|------|
| `docs/README.md` | 文件分類規則 |
| `docs/3-specs/` | 所有 SDD |
| `docs/2-architecture/decisions/` | 架構決策記錄 |
---
## 文件位置速查
| 類別 | 位置 |
|------|------|
| 架構決策 | `docs/2-architecture/decisions/` |
| SDD | `docs/3-specs/[子系統]/` |
| 操作手冊 | `docs/4-guides/` |
| 事件記錄 | `docs/5-records/incidents/` |
| 測試報告 | `docs/5-records/test-reports/` |
template/docs/2-architecture/decisions/TEMPLATE-adr.md
+30
View File
@@ -0,0 +1,30 @@
# [主題] — Architecture Decision Record
> 日期：[YYYY-MM-DD]
> 狀態：[提議中 / 已採納 / 已廢棄]
> 影響範圍：[哪些子系統 / 模組]
---
## 背景
[遇到了什麼問題，需要做這個決定？]
## 決定
**[結論，一句話。]**
## 原因
[詳細說明為什麼這樣決定。]
## 放棄的選項
| 選項 | 放棄原因 |
|------|---------|
| [選項 A] | [原因] |
| [選項 B] | [原因] |
## 影響與後續
[這個決定影響哪些地方？有什麼技術債或需要注意的事？]
template/docs/3-specs/TEMPLATE-sdd/design.md
+76
View File
@@ -0,0 +1,76 @@
# [子系統名稱] — Design
> 狀態：[草稿 / 審核中 / 已採納 / 已廢棄]
> 建立：[YYYY-MM-DD] | 最後更新：[YYYY-MM-DD]
> 負責人：[名稱]
---
## 一句話說明
[這個子系統做什麼，一句話。]
---
## 背景與問題
[為什麼需要這個子系統？解決了什麼問題？]
---
## 範圍
### 包含（In Scope）
- [這個 SDD 涵蓋的功能]
### 不包含（Out of Scope）
- [明確排除的功能，避免 CC 自行延伸]
---
## 設計
### 架構概覽
[用文字或 ASCII 描述系統結構]
```
[元件 A] → [元件 B] → [元件 C]
```
### 關鍵決策
| 決策 | 選擇 | 原因 | 放棄的選項 |
|------|------|------|----------|
| [問題] | [選擇] | [原因] | [其他選項] |
### API / 介面定義
[端點、資料格式、輸入輸出規格]
### 資料模型
[資料結構、欄位說明]
---
## 技術限制
- [不能用什麼]
- [必須相容什麼]
- [效能要求]
---
## 驗收標準
完成的定義（CC 完成任何 task 前必須確認）：
- [ ] [可客觀驗證的條件，例如：POST /api/xxx 回傳 200]
- [ ] [...]
---
## 相關文件
- [連結到相關 ADR]
- [連結到相關 SDD]
template/docs/3-specs/TEMPLATE-sdd/tasks.md
+50
View File
@@ -0,0 +1,50 @@
# [子系統名稱] — Tasks
> 權威來源：此檔案是進度真相，不是 CLAUDE.md 或對話。
> 規則：動手前標 [🔄]，完成立刻標 [x]，不批次更新。
---
## Phase 1：[Phase 名稱]
### 前置條件
- [ ] [這個 Phase 開始前必須完成的事]
### Tasks
- [ ] 1.1 [task 描述]
- 驗收：[客觀可驗證的完成標準]
- 注意：[CC 容易犯的錯，可選]
- [ ] 1.2 [task 描述]
- 驗收：[...]
---
## Phase 2：[Phase 名稱]
> 前置條件：Phase 1 全部完成
- [ ] 2.1 [task 描述]
- 驗收：[...]
---
## 完成定義
整個 SDD 完成 = 以下全部達成：
- [ ] 所有 tasks 標 [x]
- [ ] 驗收標準通過（有客觀證據）
- [ ] design.md 與實作一致（如有出入需更新）
---
## 狀態說明
| 標記 | 意義 |
|------|------|
| `[ ]` | 未開始 |
| `[🔄]` | 進行中（當前 session）|
| `[x]` | 完成（有驗收證據）|
| `[~]` | 暫緩（說明原因）|
| `[!]` | 阻擋中（說明阻擋原因）|
template/docs/README.md
+56
View File
@@ -0,0 +1,56 @@
# 文件分類索引
> CC 整理文件時的分類依據。找不到分類就問，不要猜。
---
## 分類規則
| 目錄 | 放什麼 | 判斷標準 |
|------|--------|---------|
| **1-vision/** | 為什麼做這個 | 產品願景、北極星、設計哲學 |
| **2-architecture/** | 系統怎麼設計的 | 架構圖、技術棧、元件關係 |
| **2-architecture/decisions/** | 為什麼這樣設計 | ADR，選A不選B的原因 |
| **3-specs/** | 要做什麼 | SDD，每個子系統一個目錄 |
| **4-guides/** | 怎麼做 | 部署、開發流程、CLI 用法 |
| **5-records/** | 發生過什麼 | 歷史記錄，不修改只增加 |
| **5-records/incidents/** | 生產問題復盤 | 故障原因、時間線、改進方案 |
| **5-records/test-reports/** | 測試結果 | 壓測報告、驗收記錄 |
| **6-user/** | 給使用者看的 | README、安裝教學、FAQ |
---
## CC 整理文件時的判斷流程
```
這個文件是...
├── 有明確子系統 + 設計內容？ → docs/3-specs/[子系統]/
├── 解釋為什麼做某個決定？ → docs/2-architecture/decisions/
├── 說明怎麼操作？ → docs/4-guides/
├── 記錄發生過的事？ → docs/5-records/
├── 給外部使用者看的？ → docs/6-user/
└── 以上都不確定？ → 列為「待確認」，問負責人
```
---
## SDD 結構（docs/3-specs/ 下每個子系統）
```
docs/3-specs/[子系統名]/
├── design.md ← 設計文件（要做什麼、怎麼做、邊界在哪）
└── tasks.md ← 任務清單（[ ] 未開始 [🔄] 進行中 [x] 完成）
```
CC 動手前必須有這兩個檔案。找不到就停手。
---
## .claude/wiki/ — CC 的記憶空間（CC 維護，人不手動編輯）
| 檔案 | 用途 | 更新時機 |
|------|------|---------|
| `INDEX.md` | wiki 導引 | 新增 wiki 檔案時 |
| `mistakes.md` | CC 已知誤解 + 避坑 | 每次被糾正後 |
| `status.md` | 當前進度 + 下一步 | 每次 session 結束 |
| `decisions-summary.md` | 架構決策摘要 | 重大決策後 |