Files

T

Leo 9dcbe38021 feat: install.sh 模組化安裝（--wiki / --sdd / --all）

有時只需要 wiki 不需要 SDD。不 fork，改用同一入口模組選單：
- --wiki / --sdd / --all（預設），無參數 + 有 tty 則互動詢問
- curl|bash 無 tty 安全預設 --all
- settings.json 的 hooks 依選的模組自動組裝（不再下載單一靜態檔）

不 fork 的理由：使用者多半非工程背景，一個入口最友善；維護成本不翻倍。
模組邊界先劃好，未來功能達 3+ 個再演進成「模板組合器」。

同步 wishlist：§1 接關 / §2 hook 標記已完成（commit 39783cc），
新增 §3 機敏防護 / §4 模組化安裝並標完成。README 補三層防護與模組安裝說明。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-20 12:45:53 +08:00

6.1 KiB

Raw Permalink Blame History

Wishlist

system-dev-template 自身要補的功能。

1. 接關機制（開新對話自動恢復進度） ✅ 已完成（commit 39783cc）

問題：template 現在「接關」只靠 CLAUDE.md 的軟提醒「Wiki 讀取順序：status.md = session 開始第一件事」，期待 CC 開新對話自己去讀。但軟提醒擋不住「CC 讀了 CLAUDE.md 卻沒真讀 status」，使用者也無法確定它讀了沒。

設計：雙保險（hook 自動 + 命令兜底）

機制	角色	何時
SessionStart hook	主路徑：開 session 自動注入 status 重點，不靠 CC 自覺、不用人說	每次 startup/resume/clear 自動
`/wiki-recall` 命令	Fallback：hook 沒啟動時手動接關；要完整脈絡時也用	使用者見沒自動接關 → 打一句

主路徑不靠人；命令應對 hook 失效。沒有 fallback，hook 一失效就靜默回到「全靠 CC 自覺」（正是要解決的問題）。

要做：

template/.claude/hooks/session-start-recall.sh：注入 status.md 的「正在做 / 下次第一件事」。
template/.claude/settings.json：掛 SessionStart（matcher startup|resume|clear）。
template/.claude/commands/wiki-recall.md：手動接關命令（讀 status → decisions → wishlist → HANDOFF）。
install.sh：偵測已有 settings.json 則不覆蓋，提示手動加 SessionStart（比照 CLAUDE.md 處理）。

命名閉環：init(建) → update(存,session 末) ↔ recall(接,session 初) → capture(隨時存結論)。

配套鐵律（寫進 wiki-recall + 文件）：status/wiki 是 point-in-time 快照非即時狀態。接關＝讀快照 + 核實快照，不盲信。實例：某專案 status 曾寫「待 A 收尾 X」，實際 X 早完成，照舊資訊會催已完成的事。

2. Hook 強制機制（軟規範 → 硬攔截） ✅ 已完成（commit 39783cc）

問題：template 現在完全沒有 hook，所有規範（SDD 協議、wiki 維護）都是 CLAUDE.md 的軟提醒。CC 想跳過就跳過，沒有東西抓得到。

對照 arcrun（值得 template 借鑑）：arcrun 有一套 hook 把鐵律變強制——

pre-write-guard.sh / pre-bash-guard.sh：違反禁令（沒讀 SDD 就動 code、寫違規檔）→ exit 2 直接 block，CC 跳不過。
session-start-load-sdd.sh：開 session 強制注入進度 + 禁令。
效果：「想跳過 SDD 協議就會被抓到」，不靠自覺。

要做（template 標配一個最小 hook 集）：

SDD 協議 hook：動 code（.ts/.go/...）前若沒對應 SDD / 沒在回覆宣告已讀 → 擋或警告。對應 template 既有的 /sdd-check，但從「命令要人打」升級成「hook 自動攔」。
SessionStart hook：見上 §1（接關 + 注入規範）。
可選 pre-write guard：讓使用者自訂專案禁令（如本 InkStoneCo 的「KBDB 禁動表」hook），template 給範本骨架。

設計原則（抄 arcrun 的誠實限制）：hook 擋語法層明顯違規，擋不了藏在 helper 裡的繞道 → 文檔（mindset）+ hook（底線）都不可省，絕不在文件聲稱「不可能繞過」。hook 的價值是「想跳過會被抓到」+ 留痕可審，不是技術防偽。

為何重要：template 的兩大賣點（SDD 強制先設計 + wiki 持久記憶）現在都只是「請你照做」。加 hook 才從「建議」變「機制」——這正是 template 區別於「就是寫幾個 markdown」的關鍵。

3. Wiki 機敏內容防護（不想被編入的內容） ✅ 已完成

問題：wiki 是會被 CC 反覆讀取、可能進版控的記憶空間。有些內容不該被編入——密碼、API 金鑰、私鑰、個資。只靠口頭約束太危險：密碼/個資外洩是不可逆後果，光提醒 CC「別記機敏資訊」擋不住意外。

設計：三層防護（協議 + 機械底線）

層	機制	擋什麼	性質
L1	`.claude/wiki/.wikiignore`（glob，像 .gitignore）	整個機敏檔不編入	協議（CC 遵守）
L2	行內標記 `<!-- wiki:ignore -->`…`<!-- wiki:end -->`	檔案內某段不編入	協議（CC 遵守）
L3	`wiki-secret-scan.sh` hook（PreToolUse）	機敏值真寫進 `.claude/wiki/` → exit 2 擋	硬攔截（機械偵測）

L1/L2 是使用者主動標記，L3 是自動兜底——前兩層漏掉時，寫進 wiki 那一刻 regex 攔下（密碼賦值、PEM 私鑰、AWS/GitHub/Slack/Google/Stripe 金鑰、JWT、連線字串帳密、台灣身分證、信用卡號）。

已做：

template/.claude/wiki/.wikiignore：L1 範本（預設排除 .env/*.pem/*secret* 等）。
template/.claude/hooks/wiki-secret-scan.sh：L3 hook，只掃 .claude/wiki/** 寫入，wiki-secret-ok 行尾標記可豁免誤判。
settings.json：PreToolUse(Write|Edit) 加掛。
wiki-init.md / wiki-capture.md / SKILL.md：寫入 L1+L2 協議。

設計原則（抄 §2 的誠實限制）：L1/L2 靠 CC 自律、L3 靠 regex 特徵（有偽陽/偽陰）。這是「減少意外外洩」的機制，不是保險箱——真正的密鑰本就不該進版控。絕不聲稱「不可能繞過」。

4. 模組化安裝（Wiki / SDD 可分開裝） ✅ 已完成

問題：有時只需要 wiki，不需要 SDD（反之亦然）。原 install.sh 一律全裝。

決策（為何不 fork）：使用者多半非工程背景，最怕「我要去哪個 repo」。一個入口 + 模組選單最友善。fork 成獨立 repo 維護成本翻倍、現在只有 2 個功能略嫌早。等未來功能多到 3+ 個再演進成「模板組合器」（meta-template 把子模板拉進來）——模組邊界先在 install.sh 劃好，當作拆分前置。

已做：

install.sh 支援 --wiki / --sdd / --all（預設），無參數 + 有 tty 則互動詢問 1/2/3；curl|bash 無 tty 安全預設 --all。
settings.json 的 hooks 依選的模組自動組裝（不再下載單一靜態檔）。
README 補上模組安裝與 .wikiignore 三層防護說明。

未來演進：功能達 3+ 個 → 拆成獨立模板 repo，本 repo 轉「組合器」把它們拉進來。

6.1 KiB Raw Permalink Blame History Unescape Escape