commit 8aa1b68ca0a165b87b35e72200c06e92addc6bf0 Author: richblack Date: Mon Jun 8 16:06:18 2026 +0800 Initial commit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cfd17e1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +# .gitignore + +# macOS +.DS_Store + +# 環境變數 +.env +.env.* +!.env.example diff --git a/README.md b/README.md new file mode 100644 index 0000000..097a1ed --- /dev/null +++ b/README.md @@ -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`，知識不再消失 diff --git a/docs/why.md b/docs/why.md new file mode 100644 index 0000000..9bb4bc3 --- /dev/null +++ b/docs/why.md @@ -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` 解決這個問題：討論完當場存，知識不再隨對話消失。 diff --git a/scripts/install.sh b/scripts/install.sh new file mode 100644 index 0000000..ced9958 --- /dev/null +++ b/scripts/install.sh @@ -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 "" diff --git a/skills/llm-wiki/SKILL.md b/skills/llm-wiki/SKILL.md new file mode 100644 index 0000000..c2e292c --- /dev/null +++ b/skills/llm-wiki/SKILL.md @@ -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 diff --git a/skills/llm-wiki/references/templates.md b/skills/llm-wiki/references/templates.md new file mode 100644 index 0000000..a56c4ad --- /dev/null +++ b/skills/llm-wiki/references/templates.md @@ -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]` | 完成 | +| `[~]` | 暫緩 | +| `[!]` | 阻擋中 | +``` diff --git a/template/.claude/commands/sdd-check.md b/template/.claude/commands/sdd-check.md new file mode 100644 index 0000000..54c97d2 --- /dev/null +++ b/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 diff --git a/template/.claude/commands/wiki-capture.md b/template/.claude/commands/wiki-capture.md new file mode 100644 index 0000000..5b00230 --- /dev/null +++ b/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 檔案。 + +### 第四步：確認 + +告知存到哪些檔案，共幾條記錄。 diff --git a/template/.claude/commands/wiki-init.md b/template/.claude/commands/wiki-init.md new file mode 100644 index 0000000..4cb7bfd --- /dev/null +++ b/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 +``` diff --git a/template/.claude/commands/wiki-update.md b/template/.claude/commands/wiki-update.md new file mode 100644 index 0000000..1d5ecfe --- /dev/null +++ b/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 從哪裡開始。 diff --git a/template/.claude/wiki/INDEX.md b/template/.claude/wiki/INDEX.md new file mode 100644 index 0000000..6bbfa30 --- /dev/null +++ b/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 根據專案特性填入） diff --git a/template/.claude/wiki/decisions-summary.md b/template/.claude/wiki/decisions-summary.md new file mode 100644 index 0000000..e539e3d --- /dev/null +++ b/template/.claude/wiki/decisions-summary.md @@ -0,0 +1,14 @@ +# 架構決策摘要 + +> 遇到設計判斷時查這裡。 +> 完整脈絡在 docs/2-architecture/decisions/。 + +--- + +（初始化時為空，隨專案進行 append） + +格式： +## [主題] — [YYYY-MM-DD] +**結論**：[一句話] +**原因**：[簡短說明] +**詳細**：docs/2-architecture/decisions/[對應檔案] diff --git a/template/.claude/wiki/mistakes.md b/template/.claude/wiki/mistakes.md new file mode 100644 index 0000000..daf92b6 --- /dev/null +++ b/template/.claude/wiki/mistakes.md @@ -0,0 +1,25 @@ +# CC 已知誤解 + 避坑方法 + +> 做新功能前讀一遍。 +> 格式：每條必須有症狀 + 正確做法 + 原因。 + +--- + +## 快速檢查清單（做任何事前） + +- [ ] 有對應 SDD 嗎？沒有 → 停手 +- [ ] 這次修改會影響哪些模組？有沒有連帶破壞？ +- [ ] 驗收標準是什麼？有客觀證據嗎？ + +--- + +## 誤解記錄 + +（初始化時為空，隨專案進行 append） + +格式： +⚠️ MISTAKE: [錯誤描述，一句話] + 症狀: [CC 通常怎麼表現這個錯] + 正確做法: [應該怎麼做] + 原因: [為什麼會錯] + 日期: [YYYY-MM-DD] diff --git a/template/.claude/wiki/status.md b/template/.claude/wiki/status.md new file mode 100644 index 0000000..d0a4e8a --- /dev/null +++ b/template/.claude/wiki/status.md @@ -0,0 +1,22 @@ +# 當前狀態 + +> 更新時間：[初始化時填入] +> 每次 session 結束必須更新此檔。 + +--- + +## 正在做 + +（初始化後填入） + +## 下次 session 第一件事 + +（初始化後填入） + +## 待負責人確認 + +（無） + +## 已知問題 + +（無） diff --git a/template/CLAUDE.md b/template/CLAUDE.md new file mode 100644 index 0000000..395c6d8 --- /dev/null +++ b/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/` | diff --git a/template/docs/2-architecture/decisions/TEMPLATE-adr.md b/template/docs/2-architecture/decisions/TEMPLATE-adr.md new file mode 100644 index 0000000..2212924 --- /dev/null +++ b/template/docs/2-architecture/decisions/TEMPLATE-adr.md @@ -0,0 +1,30 @@ +# [主題] — Architecture Decision Record + +> 日期：[YYYY-MM-DD] +> 狀態：[提議中 / 已採納 / 已廢棄] +> 影響範圍：[哪些子系統 / 模組] + +--- + +## 背景 + +[遇到了什麼問題，需要做這個決定？] + +## 決定 + +**[結論，一句話。]** + +## 原因 + +[詳細說明為什麼這樣決定。] + +## 放棄的選項 + +| 選項 | 放棄原因 | +|------|---------| +| [選項 A] | [原因] | +| [選項 B] | [原因] | + +## 影響與後續 + +[這個決定影響哪些地方？有什麼技術債或需要注意的事？] diff --git a/template/docs/3-specs/TEMPLATE-sdd/design.md b/template/docs/3-specs/TEMPLATE-sdd/design.md new file mode 100644 index 0000000..44bbc65 --- /dev/null +++ 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] diff --git a/template/docs/3-specs/TEMPLATE-sdd/tasks.md b/template/docs/3-specs/TEMPLATE-sdd/tasks.md new file mode 100644 index 0000000..96df8c9 --- /dev/null +++ b/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]` | 完成（有驗收證據）| +| `[~]` | 暫緩（說明原因）| +| `[!]` | 阻擋中（說明阻擋原因）| diff --git a/template/docs/README.md b/template/docs/README.md new file mode 100644 index 0000000..6a37c58 --- /dev/null +++ b/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` | 架構決策摘要 | 重大決策後 |