# 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 用 entry_type='block' 表達 block（不需獨立 blocks 表），是刻意設計的基本盤。動工前用 ls/grep 對真身，但**對到的是「現狀」不等於「設計依據」**（見下條）。
   原因: HANDOFF 寫的是「意圖/計劃」，未必已落地；跨 repo 重整時尤其要核對現況。
   日期: 2026-06-14（註：本條原結論「v3 真身在本目錄」被 leo 推翻——本目錄那套帶 blocks 表/CREATE TABLE 的「v3」是長歪的違規殘留，已刪）

⚠️ MISTAKE: 讀違規現狀去推翻鐵律（本 session 最大的錯）
   症狀: 看到插件現狀「直接 SQL 讀 blocks/entry_values（28×/31×）」，把它當「AGE-on-Postgres 訊號」當設計依據，跑去問「要不要共用 D1、直接 SQL」。
   正確做法: 現狀的直接 SQL 是【違規的歷史產物】（違反自己 CLAUDE.md「API-as-Wall」），不是設計依據。鐵律 > 現狀。插件絕不碰表、零 SQL、零 migration，全走基本盤 API；新類型只能建 template+slot，不建表（連「插件自建獨立 D1」都不行）。
   原因: 把「程式碼現在這樣寫」誤當成「所以該這樣設計」。違規代碼會自我合理化。遇到現狀與鐵律衝突 → 改現狀，不是改鐵律。
   日期: 2026-06-14

⚠️ MISTAKE: 把 embedding/語意搜尋當插件職責
   症狀: 插件綁 Vectorize/AI 做 entity 相似度合併、語意 search。
   正確做法: embedding/語意搜尋是基本盤的 optional embed 模組，不在插件。插件不綁 AI/Vectorize；entity 正規化降級 exact match、search 降級 keyword（GET /entries/search），語意部分標 [→arcrun embed]。
   原因: 基本盤 = D1 only（免費、無信用卡）；embed 是可選加購層。插件混進來會破壞分層。
   日期: 2026-06-14

⚠️ MISTAKE: 補對齊/功能 PR 混進 template 基建遷移 → 撞已 merge 的遷移、害衝突
   症狀: PR#3（receiver Zod 補對齊）從 PR#2 merge【前】的分支切 → 帶了一整批 template 1.9.x 遷移檔（.claude/→system-dev/，40 個）。PR#2 已把那批搬進 main → PR#3 重複撞 = CONFLICTING/DIRTY，且真正的補對齊改動被淹沒。
   正確做法: 功能/補對齊 PR 只放該功能的改動；template/基建遷移單獨一筆 PR。撞衝突時別在舊分支硬解一堆遷移衝突 → 從最新 origin/main 重切乾淨分支、只 cherry-pick 該功能的 code commit、force-with-lease 覆蓋 PR 分支（PR 自動更新、不用關掉重開）。切分支前先確認 base 是不是落後於已 merge 的東西。
   原因: 分支從「即將被 merge 的另一支」之前切，會把對方的改動也一起帶上；對方 merge 後兩份就撞。核心改動本身不衝突，衝突全來自混進來的重複遷移。
   日期: 2026-06-26

---

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