# CC 已知誤解 + 避坑方法

> 做新功能前讀一遍。
> 格式：每條必須有症狀 + 正確做法 + 原因。

---

## 快速檢查清單（做任何事前）

- [ ] 有對應 SDD 嗎？沒有 → 停手
- [ ] 這次修改會影響哪些模組？有沒有連帶破壞？
- [ ] 驗收標準是什麼？有客觀證據嗎？

---

## 誤解記錄

⚠️ MISTAKE: 把基本盤 block CRUD 當成本目錄的職責
   症狀: 在本目錄改/實作 block CRUD、migration 0001/0002、整套 v3 規範。
   正確做法: 本目錄只做 graph 插件（triplet/graph/entity）。基本盤歸 arcrun/kbdb。動手前先讀 docs/HANDOFF-kbdb-plugin.md 確認邊界。
   原因: 2026-06-13 定調 KBDB-graph = 插件（AGE-on-Postgres 模式），但舊 CLAUDE.md 下半仍是整套 v3 規範，易誤導。
   日期: 2026-06-13

⚠️ MISTAKE: 以為本目錄在 git 版控內、用 git mv 搬檔
   症狀: git mv 報 "not under version control" / "source directory is empty"。
   正確做法: 本目錄無獨立 git（matrix 降級後脫離，且被頂層 gitignore）→ 用普通 mv。改名 KBDB-graph 後才 git init。
   原因: git repo 是 InkStoneCo 頂層，本目錄被 gitignore。
   日期: 2026-06-14

⚠️ MISTAKE: 部署或同步走 GitHub Actions
   症狀: 設計依賴 GitHub API 列檔、push 觸發跨 repo 自動同步。
   正確做法: 部署繞開 GitHub（wrangler 直推 / scp）；讀檔走本地 fs；新 repo 不開 Actions。
   原因: 上游鐵律——當初正是這模式害帳號被 flag。
   日期: 2026-06-14

⚠️ MISTAKE: 假設「核心已在 arcrun」是既成事實
   症狀: 照 HANDOFF 字面以為 arcrun/kbdb 已是 v3 基本盤、插件直接掛上去、共用同一 D1。
   正確做法: 讀真身——arcrun/kbdb 其實還是 v2（entries，無 blocks/0005/0007/block-crud），與本插件是不同 D1 庫（arcrun-kbdb vs inkstone-kbdb）。v3 基本盤真身其實在本目錄。動工前用 ls/grep 對真身，不信 HANDOFF 字面。
   原因: HANDOFF 寫的是「意圖/計劃」，未必已落地；跨 repo 重整時尤其要核對現況。
   日期: 2026-06-14

---

格式：
⚠️ MISTAKE: [錯誤描述，一句話]
   症狀: [CC 通常怎麼表現這個錯]
   正確做法: [應該怎麼做]
   原因: [為什麼會錯]
   日期: [YYYY-MM-DD]