Initial commit

template/.claude/commands/sdd-check.md

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -0,0 +1,14 @@
+# 架構決策摘要
+
+> 遇到設計判斷時查這裡。
+> 完整脈絡在 docs/2-architecture/decisions/。
+
+---
+
+（初始化時為空，隨專案進行 append）
+
+格式：
+## [主題] — [YYYY-MM-DD]
+**結論**：[一句話]
+**原因**：[簡短說明]
+**詳細**：docs/2-architecture/decisions/[對應檔案]

template/.claude/wiki/mistakes.md

@@ -0,0 +1,25 @@
+# CC 已知誤解 + 避坑方法
+
+> 做新功能前讀一遍。
+> 格式：每條必須有症狀 + 正確做法 + 原因。
+
+---
+
+## 快速檢查清單（做任何事前）
+
+- [ ] 有對應 SDD 嗎？沒有 → 停手
+- [ ] 這次修改會影響哪些模組？有沒有連帶破壞？
+- [ ] 驗收標準是什麼？有客觀證據嗎？
+
+---
+
+## 誤解記錄
+
+（初始化時為空，隨專案進行 append）
+
+格式：
+⚠️ MISTAKE: [錯誤描述，一句話]
+   症狀: [CC 通常怎麼表現這個錯]
+   正確做法: [應該怎麼做]
+   原因: [為什麼會錯]
+   日期: [YYYY-MM-DD]

template/.claude/wiki/status.md

@@ -0,0 +1,22 @@
+# 當前狀態
+
+> 更新時間：[初始化時填入]
+> 每次 session 結束必須更新此檔。
+
+---
+
+## 正在做
+
+（初始化後填入）
+
+## 下次 session 第一件事
+
+（初始化後填入）
+
+## 待負責人確認
+
+（無）
+
+## 已知問題
+
+（無）

template/CLAUDE.md

@@ -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

@@ -0,0 +1,30 @@
+# [主題] — Architecture Decision Record
+
+> 日期：[YYYY-MM-DD]
+> 狀態：[提議中 / 已採納 / 已廢棄]
+> 影響範圍：[哪些子系統 / 模組]
+
+---
+
+## 背景
+
+[遇到了什麼問題，需要做這個決定？]
+
+## 決定
+
+**[結論，一句話。]**
+
+## 原因
+
+[詳細說明為什麼這樣決定。]
+
+## 放棄的選項
+
+| 選項 | 放棄原因 |
+|------|---------|
+| [選項 A] | [原因] |
+| [選項 B] | [原因] |
+
+## 影響與後續
+
+[這個決定影響哪些地方？有什麼技術債或需要注意的事？]

template/docs/3-specs/TEMPLATE-sdd/design.md

@@ -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

@@ -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

@@ -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` | 架構決策摘要 | 重大決策後 |