system-dev-template/docs/3-specs/install-layout/design.md

install-layout — Design

狀態：已採納 建立：2026-06-26 | 最後更新：2026-06-26 負責人：leo（uncle6me-web）

---

一句話說明

把工具安裝產物從「散落在用戶根目錄（docs/、scripts/、.claude/wiki、.claude/VERSION）」收斂成「只留 CC 死綁的 .claude/ + CLAUDE.md，其餘全進 system-dev/」，並為 wiki 改寫產物正式準備落點。

---

背景與問題

目標用戶是 low-code、只會叫 CC 做事的無技術用戶（見 memory user-profile-lowcode）。現行安裝有三個結構問題：

1. 污染用戶根目錄：install 在根目錄鋪 docs/（七層子目錄）、update 時又生 scripts/，跟用戶自己的檔案混在一起，用戶分不清「哪個 docs 是工具的、哪個是我的」。
2. 工具資料寄生在 CC 原生資料夾：wiki/ 和 VERSION 放在 .claude/ 裡。.claude/ 是 CC 原生機制目錄，不該塞工具自己的資料與版號。
3. wiki 改寫產物沒有正式落點：cards/（改寫成 AI 自讀定稿 wiki 的落地處）install 從沒建立，導致實機（KB）自己長出 .claude/wiki/cards/ 還自行 git init。位置該由工具準備，不靠用戶自救。

關鍵語義陷阱：現行 docs/ 同時是「工具文件結構」與「用戶 raw source（原始文件來源）」。重構必須把這兩義拆開。

---

範圍

包含（In Scope）

• 新增 system-dev/ 作為工具所有「資料」的根：system-dev/{VERSION,wiki/,docs/,scripts/}。
• .claude/ 只保留 CC 死綁的三樣：settings.json、commands/、hooks/。
• wiki/（含 cards/）、VERSION、工具的 docs/、scripts/ 全部移到 system-dev/。
• install.sh 正式建立 system-dev/wiki/cards/（放 .gitkeep 空桶佔位）。
• 舊用戶遷移：update.sh 自動遷移 + session-start hook 自我防呆（雙保險）。
• 同步更新所有路徑引用（CLAUDE.md、SKILL.md、wiki-init、sdd-check、wiki-capture、sdd-guard、session-start-recall、INDEX、decisions-summary、README）。

不包含（Out of Scope）

• 不動用戶 raw source：用戶自己的 docs/、Logseq pages/+journals/、Obsidian vault 根——工具只讀、不搬、不改名。
• 不搬 commands/ 與 hooks/ 出 .claude/：CC slash command 與 hook 註冊路徑死綁 .claude/（hooks 經討論決定務實留 .claude/）。
• 不改 CLAUDE.md 位置：CC 開 session 只讀根目錄/.claude 的 CLAUDE.md，留根。
• 不重寫 wiki 內容本身（只準備落點與路徑；既有卡片內容遷移不改寫）。

---

設計

架構概覽

用戶專案/
├── CLAUDE.md                 ← CC 原生，留根
├── .claude/                  ← 只放 CC 機制檔
│   ├── settings.json         ← CC 原生（hook 在此註冊）
│   ├── commands/*.md         ← slash 指令，CC 死綁此路徑
│   └── hooks/*.sh            ← 留 .claude/（務實決定）
└── system-dev/               ← 工具所有資料（新）
    ├── VERSION               ← 工具版號（從 .claude/VERSION 搬出）
    ├── wiki/                 ← 工具 wiki（從 .claude/wiki/ 搬出）
    │   ├── INDEX.md TAXONOMY.md status.md mistakes.md decisions-summary.md .wikiignore
    │   └── cards/            ← 【新】改寫產物落點，install 建好，.gitkeep 佔位
    ├── docs/                 ← 工具文件（從根 docs/ 搬出）
    │   ├── README.md SKILL.md
    │   └── 1-vision/ 2-architecture/ 3-specs/ 4-guides/ 5-records/ 6-user/
    └── scripts/              ← install.sh + update.sh，一開始就裝

關鍵決策

決策	選擇	原因	放棄的選項
工具資料落點	收進 system-dev/	不污染用戶根目錄；用戶一眼分清工具 vs 自己的檔	散在根目錄（現狀，壞習慣）
資料夾命名	system-dev/（明碼）	用戶 ls 看得到、好找	.sdt/、.system-dev/（隱藏，low-code 用戶不易發現）
wiki/VERSION	搬出 .claude/	工具資料不該寄生 CC 原生目錄	留 .claude/（現狀，職責混淆）
commands/hooks	留 .claude/	CC 機制死綁；hooks 搬走只多一層路徑、無實益	全搬 system-dev/（settings.json 走不了，得留跳板）
CLAUDE.md	留根	CC 自動讀，搬走整套導航/鐵律失效	搬 system-dev/（要留極薄跳板，等於沒搬）
docs 雙語義	拆開：工具→system-dev/docs/，raw source 維持用戶處	解決「哪個 docs 是誰的」	全搬（會誤搬用戶內容）/ 全留（污染依舊）
cards/ 落點	install 正式建 + .gitkeep	位置由工具準備，不靠用戶自救	不建（現狀，用戶自己長、自行 git init）
舊用戶遷移	update 自動遷移 + hook 防呆雙保險	low-code 用戶不會手動遷；不遷會默默壞	只靠 update（沒跑的人壞）/ 只靠手動（用戶不會做）
版本語意	1.9.0（中版號 + 自動遷移、向下相容到能升上來）	提供自動遷移即非破壞性手動	2.0.0（若要求用戶手動遷才算）
舊腳本升級撞 404（1.9.1）	① 發佈源保留 template/.claude/VERSION 相容墊片 ② 新腳本驗 REMOTE_VER 須像版號	1.8.x 舊腳本寫死抓舊 VERSION 路徑，搬走後 curl 回「404」字串、被當內容寫進 VERSION；墊片讓舊腳本不 404，格式驗證讓未來任何路徑變動都不污染 VERSION。bump 時兩個 VERSION 檔須同步（system-dev/VERSION 權威 + .claude/VERSION 墊片）	不留墊片（舊用戶撞 404）；只靠 README 改 curl（救不了已跑本機舊腳本的人）
CLAUDE.md 等用戶檔遷移後仍寫舊路徑（1.9.2）	session-start hook 偵測 + 提示 CC 代修	遷移搬檔案位置，但 update.sh 鐵則「絕不碰 CLAUDE.md」（用戶資料）→ CLAUDE.md 內 .claude/wiki 變死引用，CC 照它找錯位置。讓腳本盲 sed 改用戶 CLAUDE.md 風險高（可能誤傷用戶自寫內容、破壞鐵則），改由 CC（懂語義、知道 raw source 的 docs/ 要保留）代改	腳本自動 sed 改（誤傷風險 + 破鐵則）；只寫 README（low-code 用戶不看）
重複 install 製造 wiki 並存（1.10.1）	職責切分：install 只管「全新安裝」，一切已裝過的後續（更新/遷移/補新檔）歸 update。 ① install 偵測「裝過沒」（system-dev/ 或 .claude/wiki/ 或 .claude/VERSION 任一存在，不分新舊版）→ 不動任何東西，導去 update 並 exit ② update 的 migrate_dir：目的地已存在但舊位置仍有真資料 → 記 COEXIST 警告「並存需合併」，不靜默跳過、不自動合併 ③ install↔update 互相導向（update 遇全新專案也導回 install），閉環無死結	根因不是「舊結構」而是「重複 install」：判準該是裝過沒、不是哪個版本。用戶先 install（建空殼）→ 再 update（遷移被冪等擋掉）→ 真資料卡舊位置、空殼佔新位置、並存。切乾淨職責後，install 永不在已裝專案動手，從源頭杜絕並存	只擋舊結構（新版重裝照樣亂）；腳本自動合併（覆蓋風險）；migrate 靜默跳過（並存無聲、用戶不知資料分裂）

介面定義：遷移行為（雙保險）

第 1 層 — update.sh 自動遷移（冪等）

• 偵測舊位置存在 → 搬到 system-dev/：
  • .claude/wiki/ → system-dev/wiki/（含 cards/、含 wiki/.git，用保留 .git 的搬法）
  • .claude/VERSION → system-dev/VERSION
  • 根 docs/ 中工具自己鋪的白名單路徑（README.md、SKILL.md、3-specs/、2-architecture/、1-vision/、4-guides/、5-records/、6-user/）→ system-dev/docs/
  • 用戶自填的 docs 內容不搬（白名單外的一律不動）
• system-dev/ 已存在對應檔 → 略過（可重複跑）
• 印出「已遷移 X → system-dev/」

第 2 層 — session-start-recall.sh 自我防呆

• 開 session 檢查舊路徑 .claude/wiki/ 是否還在：
  • 在 → 印「⚠️ 偵測到舊結構未遷移，跑 update.sh 或叫 CC 幫你遷移」
  • CC 見此訊息即知該遷，可當場用檔案工具搬

資料模型：受影響路徑引用清單

檔案	改動類別
scripts/install.sh	create_dir/download 落點 docs/→system-dev/docs/、wiki→system-dev/wiki/、VERSION、新增 cards/、scripts/ 落點
scripts/update.sh	update_file/keep_file 路徑、自我更新路徑、VERSION 讀點、新增遷移段
template/CLAUDE.md + 根 CLAUDE.md	鐵律/速查表/wiki 讀取表路徑；raw source 宣告維持
template/docs/SKILL.md	cards/ 落點 → system-dev/wiki/cards/；raw source 偵測語義維持
.claude/commands/wiki-init.md（+template）	cards/ 落點、工具 docs 示意、SKILL 引用；raw source 偵測維持
.claude/commands/wiki-capture.md、sdd-check.md（+template）	docs/2-architecture、docs/3-specs → system-dev/docs/
.claude/hooks/sdd-guard.sh（+template）	7 處 docs/3-specs → system-dev/docs/3-specs
.claude/hooks/session-start-recall.sh	STATUS_FILE 路徑 + 新增防呆檢查
.claude/wiki/INDEX.md、decisions-summary.md（+template）	docs/2-architecture 引用
README.md、README.en.md	目錄樹示意、安裝後說明

---

技術限制

• bash 3.2 相容（macOS 內建）：腳本改動後必須 bash -n 過，且多位元組字元旁變數一律 ${VAR} 包好（1.7.0/1.8.2 崩潰教訓）。
• 不可破壞 wiki/.git：實機 KB 的 wiki 自帶獨立 git repo（192 張卡），遷移時用保留 .git 的搬法。
• 必須相容 CC 原生機制：commands/hooks/settings.json/CLAUDE.md 路徑不可違反 CC 載入慣例。
• 遷移必須冪等：update.sh 可被重複跑（含「以為沒更新再跑一次」）而不出錯。
• curl | bash 串流安全：update.sh/install.sh 走遠端串流執行，不可在多位元組邊界出 unbound variable。

---

驗收標準

完成的定義：

• 新裝（install.sh）：根目錄只出現 .claude/ + CLAUDE.md，其餘全在 system-dev/；system-dev/wiki/cards/ 存在且有 .gitkeep。
• system-dev/VERSION 存在且 .claude/ 下無 VERSION。
• 舊用戶跑 update.sh：舊 .claude/wiki/、根工具 docs/、scripts/ 自動遷入 system-dev/，wiki/.git 完好，可重複跑不出錯。
• 未遷移用戶開 session：hook 印出防呆提示，不默默失敗。
• 所有路徑引用無殘留死連結（grep 不到非 raw-source 語義的舊 docs/3-specs、.claude/wiki 寫死路徑）。
• raw source 語義引用維持指向用戶原始文件（未被誤改成 system-dev/）。
• bash -n 通過 install.sh 與 update.sh。
• 實機 KB 套用後：開 session 接關正常、/wiki-init 寫入 system-dev/wiki/cards/、192 張卡與其 .git 完整。

---

相關文件

• memory: user-profile-lowcode（目標用戶輪廓）
• memory: sdd-rule-applies-to-this-repo（本 repo 也守 SDD 鐵律）
• 前置 hotfix：1.8.2（update.sh bash 3.2 崩潰修復，已 push）
• 前置：1.8.1（補裝 Cowork SKILL.md，已 push）