claude-code
4.2 KiB
已知誤解 / 踩過的坑
這是 ISEP 自己的坑，不是 InkStoneCo 的（不轉抄，複製即 fork，fork 即漂移）。 撞到新坑就 append 一條；session 開場只推最近幾條標題（見
hooks/session-start-recall.shpush 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-20（ISEP 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-20（README「路徑規約」段記錄，ISEP 0.1.0 把 51 條 hook 路徑全部改過一輪）
⚠️ MISTAKE: 「裝好了」不等於「它在跑」
2026-08-20 實查：ISEP repo 建好、README 寫著 0.1.0、41 支閘都在裡面——
但 claude plugin list 裡根本沒有 ISEP。本機仍然在跑 InkStoneCo/.claude/，
Gitea 上一個 release tag 都沒有。
⇒ 「東西做出來了」與「有人在用它」是兩件事，而只有後者算交付。
⇒ 判準：去執行環境查它有沒有被載入（claude plugin list / claude plugin details），
不要從 repo 裡有什麼檔案去推論。
⚠️ MISTAKE: 閘的「釋放章」用 stat -f %m 先，雲端 Linux 永遠放行不了
2026-08-23 雲端 cloud-worker 實撞：三支閘（prod-write-guard／main-and-prod-push-guard／
stage-before-prod-guard）取戳記 mtime 都寫成 stat -f %m … || stat -c %Y …。
GNU（Linux）的 stat -f 是 --file-system，%m 被當成檔名 ⇒ 把整張檔案系統表印到
stdout（被 $() 收進去）且 exit 1 ⇒ 時間變數變非數字 ⇒ case *[!0-9]* 命中 ⇒ 釋放章判無效。
後果：總管 touch /tmp/.prod-write-ok 在雲端從沒生效過，連 routine 要求的心跳都打不出去。
⇒ 正確做法：GNU 先、BSD 後 → stat -c %Y … || stat -f %m …（Linux 走前者、macOS 走後者）。
⇒ 為什麼本機測不出來：dev 在 macOS，BSD stat -f %m 本來就正常 ⇒ 這種「只咬某一個 OS」的坑，
驗證要在真正會跑的環境（雲端 Linux）跑，不能只在 dev 機跑。
⇒ 同款第二例（同日抓到，未修）：history-first-guard 的逃生口說明寫 touch /tmp/.kbdb-down，
但它讀該檔是 cat 出來當時間戳算術——空 touch 會炸，正解是 date +%s > /tmp/.kbdb-down。
教訓：逃生口本身也要被測，不然閘壞了連逃生口都用不了。
（修復：分支 fix/stamp-release-stat-ordering-linux；回報 ISEP#30 / InkStoneCo#14）
日期: 2026-08-23