ISEP #3:裝一套自己的 wiki,接手 session 不必回頭翻 InkStoneCo

骨架照 inkstone/system-dev-template 的 wiki template 裝(三層+標籤橫切:
INDEX/TAXONOMY/status/mistakes/principles + cards/<bucket>/),不自創格式。

內容只記 ISEP 自己的事:
- 真身薄殼合一(為什麼環境設定收斂成一個 plugin)
- hook 路徑規約(${CLAUDE_PLUGIN_ROOT} vs $CLAUDE_PROJECT_DIR)
- repo 邊界與紅線(wiki 是這條紅線目前唯一開的例外,且例外本身也劃了邊界)

不複製 InkStoneCo 頂層 wiki 的任何內容——複製即 fork,fork 即漂移。

實測:hooks/session-start-recall.sh 以 ISEP 為 cwd 執行,exit 0,principles/mistakes
兩段真的印出剛寫的內容;wiki-secret-scan.sh 對全部新檔案掃過,exit 0;
wiki-recall/update/capture 三支 command 描述的路徑全部存在。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-20 13:00:36 +08:00
parent c2638668e3
commit 45bf7b4a52
12 changed files with 308 additions and 0 deletions
+27
View File
@@ -0,0 +1,27 @@
# 已知誤解 / 踩過的坑
> 這是 ISEP 自己的坑,不是 InkStoneCo 的(不轉抄,複製即 fork,fork 即漂移)。
> 撞到新坑就 append 一條;session 開場只推最近幾條標題(見 `hooks/session-start-recall.sh` push 5/5),全文在這裡。
⚠️ MISTAKE: 「環境設定」曾經拆成兩份,各自會漂
症狀: 本機在跑 `InkStoneCo/.claude/`(真身),雲端跑的是 `generate-shell-payload.py`
另外產生塞進 GitHub 私 repo 的一份(薄殼)。`inkstone/InkStoneCo#57` 實測:薄殼比真身
少 7 支閘,其中兩支是前一天才立的;`#14` 更早查到雲端 33 支 guard 一支都沒生效。
正確做法: 只留一份——ISEP 這個 repo 本身就是唯一真相源,本機與雲端裝同一個 plugin。
改動一律只改這裡,然後兩邊各自 `/plugin update`。不要再改
`InkStoneCo/.claude/hooks/`(退場中,早晚會刪)。
原因: 「一份東西兩個副本」在沒有機制強制同步的情況下必然漂移——差異不是誰疏忽,
是結構本身允許漂移發生。
日期: 2026-08-20ISEP `c263866` 建立時就是為了解這個病)
⚠️ MISTAKE: hook 路徑寫死會在雲端斷
症狀: 舊版 hook 若用 `$CLAUDE_PROJECT_DIR/.claude/hooks/...` 或寫死的絕對路徑指向 hook
腳本自己,雲端執行時的 cwd 不是本機那個真身目錄,路徑就對不到、hook 直接失效
(正是上一條「雲端 33 支 guard 一支都沒生效」的根因)。
正確做法: hook 指自己(找到自己在哪、要 source 的其他 hook 檔)一律用官方
`${CLAUDE_PLUGIN_ROOT}`。腳本內部要指**專案裡的檔案**(如 `system-dev/wiki/`
`system-dev/docs/`)才用 `$CLAUDE_PROJECT_DIR`——那些檔案本來就该住在被操作的
那個 repo 裡,跟 hook 自己的路徑是两回事,别混。
原因: 兩種路徑指的是完全不同的東西(「plugin 安裝到哪」vs「正在操作哪個專案」),
混用就是這條坑的直接原因。
日期: 2026-08-20README「路徑規約」段記錄,ISEP 0.1.0 把 51 條 hook 路徑全部改過一輪)