標籤: AI 輔助開發

  • Claude 4.7 Memory 與 Agent Team 實戰:自建 Brain 系統的真正價值

    重點摘要

    • Claude 4.7 的 memory 改進本質是「檔案使用得更好」,不是新增神奇的跨 session 記憶機制 — session 之間仍然完全隔離,靠 MEMORY.md 等檔案橋接。
    • 自建 Brain 系統 = 精煉版 cross-session memory:機制相同(檔案 + CLAUDE.md 宣告載入),差別在手動 curate、domain 分類、顯式載入,品質遠勝 auto-memory。
    • Named sub-agent 真正的價值在「單一任務多輪延續」,不是 Team A/B/C 那種多工並行 — 兩者是互補的兩個層次。
    • Bug 追查 = PUA 方法論 × Named agent 容器 × Brain 更新,三層缺一不可,且要對「無法中斷的頻道(如 Bot)」具備韌性。
    • 模型版本升級 ≠ 知識管理升級:Brain 系統是 model-agnostic 設計,換任何 LLM 都能搬過去。

    Anthropic 在 2026 年 4 月發布的 Claude Opus 4.7 在 memory 和 Agent Team 兩塊都有顯著改進。但這些「改進」對已經自建知識架構的開發者來說,究竟是關鍵升級還是錦上添花?本文整理一天的深度討論,對比 Claude 原生機制和自建 Brain 系統,並落地一套可跨機器攜帶的 bug 追查框架。

    Part 1:Memory 系統 — 4.7 改了什麼,對我有什麼用

    Claude 4.7 的三個 memory 改進

    Claude Opus 4.7 在 memory 方面的改進可以拆成三個層次:

    1. 檔案式 memory 變「一等公民」:4.7 特別訓練用檔案系統當 memory(scratchpad、notes、structured store),能主動寫筆記且下次對話時知道去讀筆記。
    2. Cross-session 穩定性提升:跨多 session、多小時的工作流程一致性更好,模型會依 brain 和 memory 的指引從上次停下的地方接續。
    3. 1M context 無長 context 溢價:原生百萬 token context window,不另收費。以前 200K+ 要 /compact 的場景現在一口氣吃完。

    Cross-session memory 的真相:沒有魔法,只有檔案

    很多人以為 Claude 4.7 的 cross-session memory 是某種「核心系統」幫你串起過去對話。真相是:session 之間仍然完全隔離,模型本身沒有跨 session 的任何 state。所謂 cross-session,是 Claude Code 在新 session 開啟時自動注入:

    • CLAUDE.md(你寫的指令)
    • MEMORY.md 和 topic files(auto-memory 累積的筆記)
    • 過往 session summary(Claude Code 自動寫的摘要檔)

    這些全是檔案,不是隱藏的 cloud memory。4.7 改進的不是機制,而是對這套檔案機制的使用熟練度:知道什麼該寫、該去哪讀、讀到後如何套用。

    自建 Brain 系統 vs Claude 原生 auto-memory

    如果你已經有自建的 Brain 系統(跨專案的技術 domain 知識庫),對比 Claude 原生 auto-memory 會發現:本質是相同機制,差別在淬煉程度

    面向 Claude 原生 auto-memory 自建 Brain 系統
    範圍 單專案(綁 cwd) 跨專案(按技術 domain 分類)
    載入時機 Claude Code 自動注入 CLAUDE.md 宣告 Domain Brain: 主動載入
    curation 模型自動(容易塞流水帳) 手動規則過濾(Why / How to apply 格式)
    外部知識 僅記錄當前對話 支援 [source: external] 納入社群/文章的坑
    配套 memory 單打獨鬥 Brain + Skill 配對(坑 vs 對的做法)

    4.7 對自建 Brain 的實際收益

    對已經有成熟 Brain 系統的開發者,Claude 4.7 的 memory 改進主要體現在兩個地方:

    • Context 吞更多(70% 的價值):1M context 可以同時載入所有相關 brain + CLAUDE.md + 當前 code,不再被切斷。多個 brain 同時載入 5000+ 行也不爆。
    • 維護判斷力(30% 的價值):叫 Claude 整理 memory 時,4.7 會主動去讀 brain 檢查重複、按規則格式寫,而不是無腦 append。4.6 可能直接塞、不去重。
    • 自動 cross-session 對自建系統無感:已經有 Brain + CLAUDE.md 宣告機制的用戶根本不依賴 auto cross-session,品質比自動版高。

    關鍵洞察:模型版本升級 ≠ 知識管理升級。Anthropic 再怎麼升級內建 memory,都在解決「模型如何維護筆記」。但「什麼知識該存、怎麼結構化、跨專案怎麼轉移」是架構設計問題,不是模型能力問題。

    Part 2:Agent Team — Named sub-agent 真正解決什麼

    4.7 的四個 Agent Team 改進

    • Named sub-agents:spawn 時給名字,後續用 SendMessage({to: name}) 續接,不用重跑 context
    • Permission 繼承修正:user-level permissions 現在會正確傳給 teammate,不再每個 teammate 都跳一堆授權 prompt
    • 個別 teammate 可調 mode:spawn 後可以用 Shift+Tab 單獨切換某個 teammate 的 permission mode
    • /team-onboarding:自動分析使用歷史產生 ONBOARDING.md,幫新隊友快速上手

    前置條件:要啟用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1,否則 SendMessage 工具根本不存在。

    Named sub-agent 和 Team A/B/C 的差異

    很多人以為 named sub-agent 是在取代自組 Team 的做法,其實兩者是不同層次的機制,互補而非競爭

    面向 Team A/B/C(宏觀) Named sub-agent(微觀)
    解決什麼 多工平行 單工延續
    邊界 不同 task 之間 同 team 內部 agent 之間
    Context 燒法 每個 team 獨立燒一份 同 agent 只燒一次,後續增量
    適用場景 早上開 3 件不相干的事 追一條長 bug / 深入一個模組

    最佳組合是兩者混用:宏觀 Team 隔離不同主題,微觀 named agent 讓每個 teammate 有連續記憶。等於開三家公司並行做不同案子,每家公司裡的同一個員工連續給你服務,不是每次都新人上場。

    已知限制:teammate 之間不能互喊

    目前 Claude Code 有個已知 bug(GitHub issue #48160):subagent 本身不能 originate SendMessage。意思是 teammate A 想主動找 teammate B 協作做不到,所有通訊必須經過 team lead 路由,變成星形拓撲(hub-and-spoke)而非 mesh。

    另外 delegate mode 有個連帶效應:lead 切到 delegate mode 後,它的權限限制會傳給 teammate,導致 teammate 也不能讀檔、跑命令,整個 team 卡住。解法是 spawn teammate 時明確放寬權限。

    Part 3:實戰落地 — Bug 追查框架

    為什麼開發和修正要用不同的 agent 拓撲

    對話中得到一個清晰的洞察:「開發」和「修正」性質不同,應該用不同的 agent 拓撲。

    Case 啟動策略
    開發(新 feature) Team A/B/C 並行,短 context agent,各管一塊
    修正(bug / fix) 單一 named agent + PUA,多輪深挖
    重構(無新功能) 單一 named agent,多檔追蹤 side effect

    認真追 bug 的 agent 應該有的樣子

    一個 bug 不是「修好就算了」。它有根本原因(root cause)、爆炸半徑(blast radius)、和教訓(lesson)。停在第一個看似合理的修補是 bug 改頭換面回來的最快路徑。認真的 bug-hunting agent 應該有三層結構:

    1. 方法論(如何思考):PUA 式修辭壓力 — 從不接受第一個假設、永遠挑戰自己的推理、窮盡所有替代方案。
    2. 延續性(如何記住):Named 長壽 agent 跨輪次攜帶 context,不要每輪重新 spawn 新 agent 失去歷史。
    3. 事後教訓(如何教未來):每個修好的 bug 都要更新 brain,否則知識死在這個專案。

    三層缺一不可:沒方法論 → 停在第一個合理原因、出 bandaid;沒延續性 → 每輪重講 context、走回原路;沒事後教訓 → 同一個 bug 六個月後在別專案又出現。

    頻道韌性:為什麼要假設「無法中斷」

    有些 channel(Bot wrapper、API-based tools、async chat)無法真正中斷正在跑的 turn,用戶的輸入只能排進下一輪。框架設計時要把這當前提:

    • 每個 hunter 步驟要快速 return 控制權,不要 chain 10 個 tool call
    • 長任務用 run_in_background: true 讓 lead 儘快 ready
    • 在自然 checkpoint 回報進度,讓用戶在下一輪調整方向
    • 把用戶輸入當戰略路線修正,不是即時操舵

    如果頻道可中斷(CLI)那是 bonus,不是前提。框架不該依賴可中斷性。

    Skill fallback:沒有 PUA 也要能跑

    如果你在多台機器工作,可能某台有 pua:pua-debugging skill、某台沒有。框架要具備graceful degradation

    • Skill 優先:有 PUA / systematic-debugging skill 時,讓 hunter 載入 — skill 是維護中的、品質更新快
    • Brain 兜底:把 PUA 的核心精神內嵌到 brain 檔,確保沒 skill 的機器也能按內建規則運作

    內嵌的規則例如:「假設你的第一個假設是錯的,立刻列出兩個會產生同樣症狀的替代方案」、「修好了 trigger 下一個問題:為什麼以前會壞?」、「症狀只能『大致』解釋 = 沒被解釋,真正的 root cause 能解釋所有觀察,包含奇怪的那些」。這套 inline rule 讓 brain 成為 skill 缺席時的 safety net。

    結案 checklist

    一個 bug 追查只有在全部滿足以下條件才算完:

    • Bug 可重現(或明確記錄為何無法重現)
    • 根本原因以白話講清楚
    • 修復已驗證(重現原 failure → 套用 fix → 確認 failure 停止)
    • 爆炸半徑評估(同一個 root cause 還可能壞掉什麼?)
    • Brain 檔已更新(domain 對、[source: project] tag 已加)
    • Commit message 以 fix: 開頭,而且 brain 更新發生在開始下一個 task 之前

    為什麼這套設計 model-agnostic

    整套 Brain + Skill + Agent Team 設計最大的優勢是 model-agnostic:未來換 Opus 5.0、換 Gemini 3、換 GPT-5,只要該模型支援讀檔案 + 自訂 instruction 機制,整套可以直接搬過去。

    Auto cross-session memory 綁在 Claude Code 內建機制上,換 tool 就沒了。自建 Brain 是把架構設計前置到模型之外 — 模型只負責執行,架構你自己定。結果是:

    • 4.7 再強,沒 Brain 也是亂塞
    • 4.6 再弱,有 Brain 也能跑
    • 未來換任何 LLM,這套設計直接移植

    這其實很接近個人化 RAG 系統的雛形 — 只是沒用 vector DB,用人類可讀的 markdown + 手動路由。反而更可控、更可維護。

    結論

    Claude 4.7 的 memory 和 Agent Team 改進都是實實在在的能力提升,但對已經有自建知識架構的開發者來說,真正的護城河不在追著升級模型,而在建立 model-agnostic 的架構設計

    • Memory:用 Brain 做跨專案長期記憶、用 MEMORY.md 做專案短期筆記、用 Skill 存對的做法 — 三者分工明確。
    • Agent Team:宏觀 Team A/B/C 並行處理不同主題 + 微觀 Named sub-agent 保持任務延續性 — 互補使用最強。
    • Bug 追查:方法論(PUA)× 容器(Named agent)× 事後教訓(Brain 更新)三層結構,對頻道韌性和 skill 缺席都要有 fallback。

    模型會一代代升級,但你累積的 Brain 不會過時 — 因為它記錄的不是模型能力,是你自己踩過的坑和學到的道理。

  • 你的 AI Agent Team 為什麼越做越小?視角驅動的編制方法論

    重點摘要

    • 你以為的「3 個 Agent 上限」可能是創傷的外推,不是設計 — 來自一次 OOM 事故的過度修正,結果反過來殺死你專案的角色細分工
    • 正確的限制是記憶體預算,不是數量 — 16GB 機器可用 ~11GB agent 預算,混合模型(Opus/Sonnet/Haiku)可以安全跑 8+ 個專職 agent
    • 但更深的問題是:角色不是頭銜,是視角 — 你該問「這個計畫需要哪些思考視角」,不是「我有幾個 slot」
    • 三個永遠不能省的視角:使用者、PM、測試者 — 即使是純技術、只有 Python、只有你一個人的專案,這三個視角的思考必須發生
    • 視角打分模型:每個視角用「風險 × 範圍」打 0-9 分,高分獨立成 agent,低分 fold 到其他 agent 的 prompt
    • 反直覺發現:小任務(3 行 API)比大任務更需要資深視角(架構師、運維、測試),因為實作已經不是風險,「該不該存在」才是
    • 壞規則會透過 template anchoring 自我強化 — 修了 runtime 規則還不夠,必須連 template 一起改

    我的 AGENTS.md template 有一條規則:Agent Team 最多 3 個同時跑。這條規則是對的 — 直到我發現它正在偷偷殺死我的專案設計。

    這篇文章是一趟很誠實的反思紀錄。從一次 16GB 機器 OOM 當機開始,到發現我對 AI Agent Team 的所有規則其實都建立在錯誤的抽象層上。結論不是「解除限制、大膽開 agent」,而是更根本的東西:角色根本不是我以為的那個東西

    第一層:我的規則其實是創傷,不是設計

    事情是這樣開始的。2026 年 3 月 3 日,我嘗試在 16GB 的 Mini PC 上同時跑 9 個 Opus agent 做大型重構,結果系統 OOM 當機。從那一天起,我的 MEMORY.md 多了一條 Iron Rule:「Agent Team 最多 3 個同時跑」。

    這條規則是理性的。9 個 Opus × 1GB ≈ 9GB,加上系統和 Docker 的常態佔用,16GB 當然吃不下。3 個是「經驗上安全」的數字。但我沒注意到一件事:這條規則是在「全 Opus」的情境下歸納出來的。我直接把它當成所有情境的通用上限,沒考慮混合模型的狀況。

    更糟的是,這條規則開始滲透到我的 AGENTS.md template、我的專案計畫、我對每個新專案的初始設計。結果是:即使某個專案明明應該有架構師、後端、前端、Kafka、SQL、Test、PM、QA 八個角色,我也會「收斂」到「全端 + 檢查者 + 架構師」三人組。我不是選擇了簡化設計,是我被一條舊規則綁架了設計想像力

    第二層:記憶體預算制取代數量制

    第一個修正很直覺:限制應該是記憶體總量,不是 agent 數量。16GB 機器扣掉系統和 Docker 的 ~5GB,還剩 ~11GB 可以給 agent 用。而不同模型的記憶體占用差很多:

    模型 記憶體 適合任務類型
    Opus ~1.0 GB 架構決策、跨檔案推理、複雜邏輯、資深思考
    Sonnet ~0.6 GB 實作、API、測試、文件
    Haiku ~0.4 GB 檔案掃描、config 對照、簡單查詢

    換算一下:一個架構師(Opus 1.0)+ 兩個後端(Sonnet × 2 = 1.2)+ 前端(Sonnet 0.6)+ SQL(Sonnet 0.6)+ Kafka(Sonnet 0.6)+ Test(Sonnet 0.6)+ QA + PM(Haiku × 2 = 0.8)= 5.4 GB,8 個 agent。完全在 11GB 預算內,還有 5.6GB 的 headroom。

    所以「3 個 agent」的舊規則其實是錯的。正確的說法是「全 Opus 時 ≤ 3 個;混合模型時可以到 8+ 個,只要總和在預算內」。這一步修完,我理論上可以解鎖原本想要的專職團隊設計。

    但這還不夠:我一直在錯的抽象層解決問題

    我以為修到這裡就結束了。結果真正的問題還在更上面一層。

    記憶體預算制解決了「能不能開 8 個 agent」的技術問題,但沒解決「我該開哪 8 個角色」的設計問題。我仍然在用「頭銜思維」想 Agent Team — 有一個固定的角色清單(架構師、後端、前端、QA…),看看預算能放幾個,從清單挑幾個進來。

    這個思維的錯誤在哪?它把「角色」當成頭銜 / headcount,而角色的本質其實是視角 / perspective — 一種「怎麼思考這件事」的觀點。兩個是完全不同的東西:

    思維 頭銜 Headcount 視角 Perspective
    單位 angular-dev、backend-dev 「使用者會怎麼用」「PM 會怎麼想」
    數量 固定清單 每個 plan 動態決定
    「只有 Python」專案 1 個 Python dev 就好 仍需使用者、PM、測試視角
    小任務(3 行) 給最便宜的 dev 可能需要最資深的運維視角

    三個永遠不能省的視角

    這是最實用的一條發現。不管你的專案是什麼技術、什麼規模、幾個人做,這三個視角永遠必須存在:

    • 使用者視角 — 誰會用這個東西?他們的心智模型是什麼?介面怎麼設計才順?
    • PM 視角 — 這件事符合大方向嗎?是現在最該做的嗎?會影響別的優先級嗎?
    • 測試者視角 — 什麼會壞?邊界 case 在哪?漏掉什麼?失敗模式是什麼?

    這三個視角可以 fold 到其他 agent 的 prompt 裡(例如讓 backend-dev 在設計階段戴 PM 帽子),但絕對不能默默省略。省略它們的結果是:你會產出「技術上正確、實用上無用」的東西 — API 能跑但沒人想用、feature 完成但 PM 說這不是重點、code 過 review 但上線就爆 edge case。

    「只有 Python」不是跳過使用者視角的理由。「只有你一個人」不是跳過 PM 視角的理由。「只是改一行」不是跳過測試者視角的理由。這三個視角的思考必須發生,差別只在「由誰承擔」,不在「要不要做」。

    視角打分模型:風險 × 範圍

    光知道「要列視角」還不夠,還要知道哪些重要、哪些次要。我用的打分模型很簡單:Score = Risk × Scope,兩個維度都是 0-3,總分 0-9。

    • 風險:這個視角漏掉的話多慘?(0 = 無所謂,3 = 災難)
    • 範圍:這個視角涉及多少產出物?(0 = 無,3 = 全部)

    分數算出來後按以下規則分組到 agent:

    • Score ≥ 6:獨立 agent,很可能要用 Opus 或高階 Sonnet
    • Score 3-5:獨立 agent,或跟另一個視角配對(Sonnet)
    • Score 1-2:fold 到其他 agent 的 prompt,明確列入該 agent 的優先順序
    • Score 0:在計畫裡 acknowledge 就好,不花 agent 資源

    最後檢查記憶體預算是否超過 11GB,超過就把分數最低的兩個合併。

    反直覺發現:小任務需要更資深的視角

    這是這整套方法論裡最違反直覺、也最容易忽略的一條。實作越簡單的任務,反而越需要資深視角

    原因很微妙:大任務的風險分散在許多實作細節裡,實作者視角得分最高(因為「寫錯」的機率大)。但小任務的實作幾乎免費 — 風險已經轉移到別的地方了:「這東西該不該存在」(架構師視角)、「會不會在奇怪情境下爆」(測試者視角)、「運維怎麼用這個 endpoint 做決策」(運維視角)

    具體例子:幫一個 Docker 服務加 /health endpoint,回 {"status": "ok"}

    • 實作者視角:風險 1 × 範圍 1 = 1 分(3 行誰都會寫)
    • 運維視角:風險 3 × 範圍 2 = 6 分(這個 endpoint 決定服務要不要被 monitoring 重啟)
    • 架構師視角:風險 3 × 範圍 1 = 3 分(「健康」的定義是最大問題)
    • 測試者視角:風險 2 × 範圍 1 = 2 分
    • 使用者視角:風險 2 × 範圍 1 = 2 分

    結論:這個任務要派一個 Sonnet agent,但 prompt 的優先順序是運維 > 架構 > 測試 > 使用者 > 實作。它不是「後端 dev 寫 3 行」,是「一個有運維腦袋的人剛好以 3 行 code 為產出」。

    這個例子回答了我長久的困惑:「小任務該加一個專職 agent,還是從 tester 出發、還是從 dev 出發?」答案是 — 從得分最高的視角出發,不從頭銜出發。小任務通常是資深視角得分高,所以該派的不是 junior implementer,是帶著資深視角的人。

    三個完整案例

    案例 1:純 Python script(200 行,讀 CSV 做統計)

    視角枚舉:Python 實作者、使用者、PM、測試者、架構師

    打分:實作者 6、測試者 6(資料邊界 case 是真風險)、使用者 2、PM 1、架構師 1

    分組:2 個 Sonnet(~1.2 GB)

    • Agent 1:實作 + 架構 + PM 視角(優先:實作)
    • Agent 2:測試 + 使用者視角(優先:測試 — 資料邊界主導)

    2 個 agent,但 5 個視角都被想過了。要的是「每個視角都有思考發生」,不是「每個視角都有一個人」。

    案例 2:OMS 訂單退款功能(跨前後端/Kafka/SQL/admin)

    視角枚舉:架構師、安全、後端、前端、Kafka、SQL、Admin UI、測試、使用者、PM、合規

    打分:每個都 ≥ 4 分,因為範圍廣且風險高(金流)

    分組:9 個 agent(~6.6 GB,預算內)

    • Architect(Opus)、Security(Opus)
    • Backend-dev、Frontend-dev、Kafka、SQL、Admin-UI、Tester(全部 Sonnet)
    • 使用者 + PM + 合規視角 fold 到一個 Haiku

    這就是大型專案值得完整專職團隊的時候。注意:即使 9 個 agent,使用者和 PM 視角還是被 fold 到一個 Haiku,不是各自獨立。視角沒被省,但不一定要佔獨立 slot

    案例 3:3 行 /health endpoint(已在前面詳細分析)

    分組:1 個 Sonnet,所有 5 個視角都 fold,優先順序運維 > 架構 > 測試 > 使用者 > 實作。

    計畫修訂時必須重算

    一個容易忽略的點:staffing 是 live document,不是一次性決定。當計畫執行到一半發現:

    • 新需求浮現(「喔原來這個也要接 Kafka」)→ 新視角需要打分,決定獨立或 fold
    • 某視角發現其實很關鍵(原本 fold 的安全視角,發現有 PII 暴露)→ 升級為獨立 agent
    • 某視角發現其實不必要(決定不做 admin UI)→ 該 agent 退場或重新分配

    每次 plan 修訂都該觸發 staffing 重算。如果 AGENTS.md 跟當前 plan 不同步,應該先更新 AGENTS.md 再繼續 dispatch。

    壞規則會自我強化 — template anchoring 的陷阱

    最後我想分享一個元層級的教訓,是這整件事最讓我不舒服的部分。

    我一開始以為只需要改 runtime 規則(把「3 個上限」改成「預算制」)就好了。但我後來發現:壞規則會透過 template 自我強化。我的 AGENTS.md template 原本的例子只有 2 個角色(implementer + reviewer),這個「低錨」讓我每次初始化新專案時,都自動往「3-5 個角色」的方向填,幾乎從不主動設計 7-10 個。

    這形成一個 feedback loop:

    • 創傷 → 記憶體規則收緊到「3 個」
    • Template 的例子反映記憶體規則 → 錨在低數量
    • 我用 template 寫新 AGENTS.md → 產出低角色的設計
    • 低角色的設計變成「標準」→ 我的記憶認為「就是這樣」
    • 循環加強

    光改規則不夠,template 也得改。我最後把 template 改成強迫跑完整個視角打分流程的版本:頂部要求先讀「視角驅動 staffing」的 brain,中間有「Perspective Inventory」區塊要你填每個視角的 Risk × Scope 分數,再下面是「Memory Budget」計算區塊。沒跑完流程根本填不完 template。

    這個 template 和配套的方法論 brain 都放在公開的領域腦 repo裡,歡迎 clone 參考。

    跟 VCS / 版本控制的關係

    如果你讀過我之前那篇 Jujutsu vs Git,可能會問:視角驅動 staffing 跟 jj 有什麼關係?

    答案是:沒有關係,而且這個順序很重要。視角驅動 staffing 是計畫期的事 — 你在寫 plan、決定 Agent Team 編制時發生。VCS(git / jj / worktree / workspace)是執行期的事 — Agent Team 已經成立、開始跑、產出變動需要合併的時候才登場。不能倒過來。

    我之前一度把這兩件事混在一起寫(在「VCS + AI 工作流」的 brain 裡討論 Agent Team 編制),後來意識到這是錯的。Staffing 決定「要做什麼」,VCS 決定「做的產出怎麼合併」。兩者相關但獨立,混在一起會讓人以為「切到 jj 就能多開 agent」— 不是的,能多開 agent 是記憶體預算 + 視角分析的事,跟 VCS 無關。

    結論:為什麼這個順序重要

    我從「Agent Team 最多 3 個」走到「視角驅動編制」的這段路程,對我來說最重要的一個 meta-lesson 是:你的限制規則可能不是來自設計,而是來自創傷。一次系統炸掉的記憶,會變成一條 Iron Rule,然後透過 template anchoring 滲透到你所有未來的設計決策。

    修復這種規則不能只修表面。你得:

    1. 檢視規則的原始情境 — 它是在什麼條件下產生的?那些條件還成立嗎?
    2. 把規則轉成可計算的東西 — 不是「最多 3 個」,是「11GB 預算」;不是「寫 3 行 API」,是「運維視角 6 分」
    3. 上升到更對的抽象層 — 從「數量」到「預算」是一次升級,從「頭銜」到「視角」是又一次升級
    4. 同時改 template — 不然新專案會繼承舊錨,規則永遠修不乾淨

    這個流程不只適用 Agent Team 編制,適用任何你「歸納」出來的工程規則。下次你發現自己下意識地拒絕某個選項(「不能這樣做,會爆」),請誠實問自己:這個規則是設計來的,還是創傷來的?如果是後者,它可能正在偷偷殺死你的系統設計,而你根本沒意識到。

  • Jujutsu vs Git:從底層原理到 AI Agent Team 時代的版本控制選擇

    重點摘要

    • Git 的本質是一個 content-addressed key-value 資料庫,所有的 branch、rebase、reflog 都是建構在這個底層上的抽象
    • Jujutsu(jj)不是 Git 的替代品,而是把 Git 的 content-addressed 哲學「再往上推一層」 — 從檔案快照擴展到操作快照
    • Git 的核心限制不是指令不爽,而是它要求人類的同步注意力 — merge 衝突會 block 整個世界等你處理
    • jj 允許異步注意力 — 衝突變成 commit 的一種狀態,rebase 永遠不會停,你可以明天再一次處理完
    • Agent Team 有三種任務類型,jj 的價值差很多:Review(只讀)完全不需要 jj;Debug(試驗假設)是 jj 最被低估的甜蜜點;Dev(平行開發)在合併階段需要 jj
    • 最優的使用模式是 git 為主、jj 只在 Agent Team 合併階段出場 — 由 orchestrator agent 承擔 jj 學習成本,人類使用者和 subagent 全程保持 git 心智
    • 決策準則:默認 Git,三個訊號任一觸發時考慮 jj — 平行 Agent 撞車、review round 批次修正、Agent 實驗成本太高

    最近 GitHub 上 jj-vcs/jj(Jujutsu)越來越熱,社群討論開始出現「Git 要被取代了嗎」的聲音。我花了幾個小時認真研究這個工具,過程中意外地被迫重新理解 Git 的底層設計 — 因為只有懂 Git 真正是什麼,才看得懂 jj 想解決什麼。這篇文章就是這趟理解的完整紀錄,從 Git 底層原理開始,一路推到 AI Agent Team 時代的務實使用模式。

    結論先說:Jujutsu 和 Git 不是互斥關係。jj 的儲存後端其實就是 Git,你可以隨時切回純 Git 指令。真正該問的不是「要不要換」,而是「你的工作流是否已經撞到 Git 的設計假設」。而這個答案,必須先從 Git 的底層長什麼樣講起。

    先搞懂一件事:Git 其實是一個資料庫

    很多人用 Git 很多年,但沒意識到一件事:Git 本身就是一個資料庫,而且是一個設計極其精巧的資料庫。整個 .git/ 目錄就是一個 key-value store,只是它用檔案系統當儲存引擎而已。

    你現在去任何 git repo 跑 ls .git/objects/,會看到一堆兩位數的資料夾:00/ 01/ ... ff/,每個資料夾裡面有一堆 hash 開頭的檔案。這就是 Git 的資料庫。它叫 Object Database,key 是 SHA-1 hash,value 是壓縮過的內容。所有其他概念 — commit、branch、tag、stash、reflog — 全部都是建構在這個 key-value store 之上的抽象。

    四種物件,解構整個 Git

    • Blob:儲存單一檔案的內容,不包含檔名。SHA1(content) = hash,內容相同 hash 必然相同。同樣內容只存一份(自動去重)。
    • Tree:儲存一個資料夾的結構,內容是一張表 — 列出這個資料夾有哪些檔案(指向 blob)和哪些子資料夾(指向另一個 tree)。Tree 可以遞迴指向其他 tree。
    • Commit:儲存一個時間點的快照,內容只有幾行 — 指向根目錄的 tree hash、前一個 commit 的 hash、作者時間、commit message。Commit 本身不含任何檔案內容,它只是一個指標鏈的進入點。
    • Tag:annotated tag 的容器,對理解本質不重要,跳過。

    一個 commit 怎麼「記錄整個資料夾」

    你 commit 時,Git 為每個檔案內容計算 hash 建 blob,為每個資料夾建 tree(一張表,列出那個資料夾裡所有 blob 和 sub-tree 的 hash + 檔名),最後建 commit,只包含 root tree hash + parent hash + 作者 + 訊息。結果是一個指標鏈:commit → tree → sub-tree → blob每個 commit 都完整地、不可變地描述了那一刻整個資料夾的狀態,不是 diff,是完整快照。

    但每次存完整快照不會爆嗎?

    這就是 Git 設計最美的地方。答案是:不會爆,因為 content-addressed 帶來自動去重。你 commit 了 1000 次,但 99% 的檔案沒動,那 99% 的檔案永遠只有一個 blob,因為內容一樣 hash 一樣,儲存只有一份。改一個檔案的成本 = 1 個新 blob + 2-3 個新 tree + 1 個新 commit,其他全部重用。實際效果:Linux kernel 有 100 萬+ commits,整個 .git/ 也就 5 GB 左右。

    Git 從來不儲存 diffgit diff 是每次問的時候走訪兩個 commit 的 tree DAG、現場跑 Myers 演算法算出來的。這個設計的好處是:讀任何一個歷史版本都是 O(1),不用還原一串 diff 才能看到那個版本的樣子。這一切都是「content-addressed immutable store + pointer DAG」這一個設計決策的延伸。Linus 2005 年花兩週寫出 Git 核心,就是這個設計。後來所有東西都是在這個底層上加糖。

    Jujutsu 的核心創新:把 Git 的哲學再推一層

    現在你懂了 Git 的底層,就能看懂 jj 在做什麼。jj 沒有推翻 Git 的設計,它做的事情是:把 Git 的 content-addressed DAG 從「檔案狀態」擴展到「操作狀態」 — 同樣的哲學,應用在不同的層級。

    雙層身份:commit hash + change-id

    Git 只有一個 ID — commit hash,由內容決定。這導致 rebase 後 hash 全變,你找不到「原本那個 commit」。jj 對每個 commit 同時維護兩個 ID:commit hash(跟 Git 一樣)+ change-id(隨機產生的 128-bit ID,只在 commit 誕生時生成一次,rebase/amend/split/squash 都不變)。這個設計的意義是:身份認同不綁在 hash 上,綁在 change-id 上。你可以隨便改歷史,change-id 永遠追蹤得到「同一個概念上的改動」。這就是為什麼 jj 可以把「歷史重寫」當日常操作,而 Git 必須當儀式感操作。

    Op Log:第二層 content-addressed DAG

    jj 的另一個核心是 operation log。每個 jj 操作都產生一個 operation 物件,包含 operation id(hash)、parent operation、執行的指令、操作前後 repo 整體狀態的快照。這些 operation 本身也組成一個 DAG,content-addressed 儲存。注意這裡的模式跟 Git 完全一樣:不可變物件 + 指標 DAG + 內容定址。jj 只是把 Git 用來管檔案狀態的那套機制,再蓋一層管操作狀態。

    結果是 jj undo 變成一步 pointer 移動 — 直接把 repo view 指回前一個 operation 的「操作前快照」就好,不用反向計算任何東西。而且 undo 本身也是一個 operation,可以被 undo,可以無限回退。

    指令層面的六個差異

    面向 Git Jujutsu (jj)
    Staging Area working dir → index → commit(三層) working dir 就是 commit(兩層,無 git add)
    Branch 概念 一等公民,必須 checkout/rebase/merge 可選的 bookmark,每個 commit 有穩定 change-id
    Undo 機制 reflog(補救機制,90 天 TTL) jj undo(第一等操作,可無限回退)
    Conflict 處理 停止世界,當場解完才能繼續 衝突直接存進 commit,可延後解
    Stash 必要指令(stash push/pop/apply) 不存在,jj new 直接開新 commit
    歷史重寫 rebase -i 是儀式感操作 jj split / jj squash 是日常

    最重要的差異:同步注意力 vs 異步注意力

    到這裡為止,都還是「指令差異」和「設計哲學」的層面。但 jj 真正的價值,不在指令爽不爽,而在它如何消耗人類的注意力。這個差異是質變,不是量變。

    Git 是同步注意力模型 — merge/rebase 遇到衝突會停止世界,直到人類出現、看懂、解決、繼續。它要求你在「不可預期的時刻」立刻在場。這個模型在單人或 2-3 人團隊下完全沒問題,因為衝突頻率低、你本來就在鍵盤前。

    jj 是異步注意力模型 — rebase 遇到衝突不停下來,衝突被存進 commit 變成一種有效狀態,rebase 繼續往下跑。你可以明天處理、或一次批次處理所有衝突、或開另一個 Agent 專門解衝突。jj 允許人類「異步在場」 — 系統自己跑,有問題幫你記下來,你有空再來看。

    Git 的設計誕生於 2005 年,當時的假設是「careful human curator」 — 每個 commit 都是人類慎重思考後的決定,每個 merge 都有人類在場。但 Claude Code、Cursor、Copilot Agent 這類 AI 工具改變了「誰在產生 commit」這件事。Agent 產出的是高頻、探索性、非線性、大量並行的中間態。你不可能一邊看 3 個 Agent 平行工作,一邊在它們合併時即時解衝突,一邊決定每個中間態要不要保留。人類同步注意力的頻寬根本跟不上 Agent 的產出速度。

    jj 在這裡的價值不是「比 Git 更爽」,而是它讓 Git 做不到的事變可能 — 讓 Agent Team 真的平行跑到底,明天早上來一次處理所有衝突。這不是量變(爽度提升),是質變(能做的事情不同)。

    Workspace 隔離:平行的真正解法

    要澄清一個常見誤解:jj 本身不能解決「兩個 Agent 同時寫同一個檔案」這種檔案系統 race condition。檔案系統的併發是 OS 管的,任何 VCS 都介入不了。平行 Agent 的正確架構是每個 Agent 給一間房 — Git 用 git worktree add,jj 用 jj workspace add。每個 workspace 是獨立的 working directory,三個 Agent 在不同資料夾各寫各的,完全不會互相污染。

    Git 和 jj 在 workspace 隔離這一步的行為相同。差異出現在下一步 — 把三個 Agent 的輸出合併回 main 時。Git 會序列化 blocking(解一個、繼續、解下一個、繼續),你的注意力被三次阻塞切碎;jj 則是三個動作一氣呵成,最後一次性 batch 處理所有衝突。Workspace 隔離是必要條件,jj 的優勢出現在合併階段的併發模型

    Agent Team 的三種任務類型:jj 的價值差很多

    這是這篇文章最重要的一個區分,也是大部分「jj 推坑文」忽略的。你叫 Agent Team 做不同類型的事,jj 的價值完全不同 — 甚至有些情境 jj 根本沒有用。決定性的問題是:這些 agent 需要寫檔案才能完成任務嗎?

    類型 1:Review(只讀) — 完全不需要 jj

    場景:叫 Agent Team 做 code review、security audit、dead code 掃描、架構審閱。這些 agent 只讀檔案,產出報告,不寫任何東西

    這種場景 jj 沒有價值:沒有 commit、沒有 merge、沒有 undo 需求。三個 agent 同時讀同一個檔案完全沒問題,OS 的 file handle 對讀不是互斥資源。純 git 就好,甚至不需要 workspace 隔離。

    常見誤區:很多人把「開 Agent Team」跟「需要 jj」畫等號,導致在純 review 場景也導入 jj 的學習成本。這是沒必要的。

    類型 2:Debug(試驗假設) — jj 最被低估的甜蜜點

    場景:叫 Agent Team debug 複雜 bug。Debug 的本質是「形成假設 → 驗證 → 推翻 → 再假設」的循環,而驗證通常需要動手改 code — 加 log、改條件、插 assert、暫時跳過某段邏輯。

    Git 下的 debug 痛點:加了 10 個 print() 驗證完要全部刪掉,漏刪一個就污染 production;改了某個函式測試假設,後來發現方向錯,手動改回去容易漏;想試兩個假設 A 和 B 哪個對,兩個互相覆蓋,不能同時存在。

    這是 jj 最強的場景,**比一般開發還強**。原因很微妙:development 的產出是「最終正確的 code」,中間過程 git 可以容忍(最終 squash 成 clean commit 就好)。但 debug 的產出是「對問題的理解」,這個理解存在於中間過程本身,不存在於最終狀態。

    Git 丟掉中間過程 = 丟掉 debug 的精華。jj 保留所有中間過程 — 每個假設是一個 commit、jj undo 可以乾淨撤銷、多個假設可以平行存在於 op log,等於保留 debug 的完整價值。debug agent 可以試 5 個假設、留下完整推理紀錄、報告說「我試了 A/B/C/D,D 可行因為…」,你事後可以 jj op restore 跳回任何一個假設狀態看 agent 那時候看到什麼。

    結論:如果你常叫 AI debug 複雜問題,jj 的價值比你想的大很多。這是 op log 從「檔案歷史」升級為「推理紀錄」的唯一場景。

    類型 3:Dev(平行開發) — jj 在合併階段是必要品

    場景:叫 Agent Team 平行開發多個模組。多個 agent 會產出多個改動分支,最後要合併回 main。這是大家熟悉的場景 — 前面講的「同步 vs 異步注意力」、「workspace 隔離」、「conflict as commit」全部都在這個場景發揮。

    但注意:jj 在這個場景的價值集中在合併階段,不是 agent 工作期間。agent 自己工作時,Git 和 jj 沒差。差異出現在「把 N 個平行輸出 reconcile 回主線」這一步。沒有 jj 的非阻塞合併,你的 Agent Team 上限會被 git 的序列化 blocking 硬生生壓到小規模 — 即使記憶體還有餘裕。

    三種使用模式:該怎麼在日常工作裡擺 jj

    理解完上面的分析,最後的問題是:你該怎麼把 jj 放進你的日常工作?有三種模式,各自適合不同情境。

    模式 1:純 git(現狀)

    適合:單人或「1 RD + 1 Reviewer」工作流、穩定專案、強烈依賴 IDE Git 整合、團隊只認 git。這個模式沒什麼好討論,就是你現在的樣子,對大多數人完全夠用。

    模式 2:jj 為主,git 只是後端

    安裝 jj colocated mode,日常指令都打 jj,幾乎不打 git。這個模式的問題是:邊界仍然是 git 世界。IDE Git panel 顯示的是 jj 上次匯出的狀態,你在本地 jj rebase 一下,push 後 GitHub 還是看到 commit hash 全變,change-id 根本沒傳出去。你本地很爽,對外還是 git 的世界。

    這個模式只適合「單人、沒有協作壓力、不在意 IDE 整合退化」的使用者。對多數人代價太大。

    模式 3:git 為主,jj 只在 Agent Team 合併階段出場

    這是我研究完之後推薦的模式,也是最被低估的一個。玩法是:

    • 你日常全程用 git — 習慣、IDE、CI、PR 流程完全不變
    • Subagent 也用 git — 他們在各自 workspace 裡用 git commit,根本不知道 jj 存在
    • Orchestrator agent(Claude Code)在合併階段用 jj — 只需要學 5 個指令:workspace addgit importrebaselogworkspace forget
    • 一次性設定:jj git init --colocate,之後你完全忘記它存在

    這個模式最精妙的地方:學習成本完全落在 orchestrator agent 身上,不是你身上。你的認知負擔幾乎為零,只需要記住一個 trigger:「要開 Agent Team 時,叫 Claude」。其他時間 jj 完全不存在。

    失敗零成本:任何一個環節出問題,你都可以回退到純 git。subagent 的 commit 是正常 git commit,無論是否用 jj 都能 git cherry-pick;合併失敗就 git merge 手動解;jj 整個壞掉就刪掉 .jj/,git repo 毫髮無傷。沒有 lock-in,沒有 point of no return

    Review Round 批次修正:寫之前切 vs 寫之後切

    另一個 jj 爆發的場景是 review round 工作流。很多團隊的 QA/review 會產出幾十個 issue,你拿到一份清單要一次修完。典型的 commit message 長這樣:fix(fee): R5-12/13/03/04/10/16/17 remaining module items — 塞了 7 個獨立的 issue 修正在一個 commit。

    為什麼塞一起?因為 Git 下的三個選擇都不理想:每個 issue 一個 commit 要 git add -p 切七次太累;全部一個 commit 未來想單獨 backport 做不到;開 7 個 branch 管理成本爆炸。結果大多數人選「全部一個 commit」,歷史變成粗顆粒。

    jj 的解法:打開 editor,一次改完 7 個 issue,不用管 commit 切分。改完後 jj split,互動畫面讓你把每個 hunk 分配到哪個 commit,七次後自動產生 7 個獨立 commit。Git 的 add -p 是「寫之前」切,jj 的 split 是「寫之後」切。這讓你把「commit 切分」這個決策延後到資訊最充足的時候(全部改完後),而不是在你還在思考邏輯的時候被迫處理。

    決策準則:你該用哪個模式?

    純 git 就夠的訊號

    • 單人或「1 RD + 1 Reviewer」工作流 — 沒有平行檔案衝突
    • Agent Team 只做 review / audit(agent 不寫檔案) — jj 沒有價值
    • 穩定專案、強依賴 IDE Git 整合
    • 老 Git 肌肉記憶還在運作,且團隊只認 git

    考慮模式 3(git + jj for Agent Team merge)的訊號

    1. Agent Team 在共享檔案上撞車 — 你為了避免 merge 衝突開始序列化 Agent,生產力被 VCS 綁住
    2. Review round 產生批次修正 — 你寫過大量 fix: XXX-01/02/03/04/05 這種塞一堆 issue 的 commit,事後想拆卻沒工具
    3. AI 常常需要做 debug 試驗 — 你希望 AI 大膽試很多假設,但現在因為回退成本太高,限制了 agent 的自由度

    三個訊號都沒中?純 git 就夠了,別為了新鮮感切工具。

    我的具體建議:安全試用路徑

    1. 選一個個人實驗性專案,執行 jj git init --colocate(一次性,30 秒)
    2. 繼續用 git 做 99% 的事 — 你的肌肉記憶完全不變
    3. 下次真的要開 Agent Team 時,讓 orchestrator agent 用 jj 的 workspace + 非阻塞 rebase 處理合併階段
    4. 如果是 debug 場景,給 agent 「大膽試驗」的權限,利用 op log 保留推理紀錄
    5. 一個月後評估:有沒有真的遇到 jj 幫上忙的場景?沒有就卸載,git repo 完全不受影響

    跨專案的架構原則

    這次研究讓我提煉出一個跨專案適用的原則,寫進我的領域腦系統:

    VCS 的選型要跟「人類注意力的可用模式」匹配,不是跟「指令爽不爽」匹配。Git 假設人類可以同步在場,jj 允許人類異步在場。AI Agent 工作流打破了 Git 的第一個假設,但是否影響到你,取決於你的團隊形狀和工作型態,不取決於你對 AI 的熱情。

    更深一層的 insight:Git 的偉大不在於它的指令設計,而在於 content-addressed DAG 這個設計模式。這個模式你會在 IPFS、Nix、Docker layers、區塊鏈到處看到 — 懂 Git 底層等於懂了這一整類系統的通用結構。jj 的聰明,是看到這個模式可以往上再推一層,應用到操作本身,而不只是檔案狀態。

    AI 時代最大的認知陷阱是「新工具一定比舊工具好」,但真實世界是新舊工具的取捨點會隨場景變化。把場景描述清楚,比把工具吹捧清楚重要得多。下次你看到任何新的版本控制、儲存系統、分散式工具時,問自己這三個問題就好:它的不可變單位是什麼?怎麼定址?DAG 結構長怎樣?答案對上 content-addressed DAG 模式,你就已經懂 80% 了

  • Vibe Coding 協助物聯 AI 開發:從 RTSP 撞牆到 Telegram Bot 上線的完整實戰

    這是一篇關於 Vibe Coding(憑感覺邊聊邊寫)在物聯 AI 開發上的實戰紀錄。主題聽起來很酷,但實情是:我只是想解決一個很平凡的問題 —— 怎麼把家裡長照白板上的磁鐵打點,自動變成醫生回診時能看的資料。

    這篇會誠實記錄這一晚跟 AI 協作的過程、做對的決策、撞到的牆、以及學到的方法論。不是成功故事,中間我還沒跑出一份真正可用的資料。但我覺得過程本身比結果更值得寫下來。

    重點摘要

    • Vibe Coding 不是憑空想像,而是即時驗證 —— 每個假設都在對話中被一條 curl / 一行 ffmpeg 打臉或確認
    • Gemma 4 跟 Gemini 3 Flash Preview 在同一張模糊中文手寫白板上差距巨大:前者一直幻覺亂編項目,後者誠實回 null
    • Schema-constrained Prompt + 信心度分級是物聯 AI 應用的關鍵 —— 寧缺勿錯,比準度更重要
    • 最後撞到的不是模型牆,是光學物理牆 —— RTSP 1080p 遠距離下磁鐵只有 3~5 像素,任何 VLM 都無解
    • 與 AI 協作最大的價值是迭代速度:從想法 → curl 驗證 → 決策 → 下一步,一晚走完通常要一週的探索

    什麼是 Vibe Coding?為什麼它適合物聯 AI 開發

    Vibe Coding 是一種開發風格,核心精神是:不先寫規格、不先畫架構,先跟 AI 對話,在對話中讓問題結構自己浮現。聽起來很鬆散,但在物聯 AI 開發(IoT + AI 結合)的情境下,這種作法反而比傳統瀑布式規劃更有效。

    原因很簡單:物聯 AI 專案有太多無法事先確定的變數 —— 攝影機實際畫質、現場光線、模型對中文手寫的容忍度、API 認證流程的細節、現場使用者的真實習慣。這些東西你寫再多規格也寫不清,只能邊試邊改。

    傳統作法是先買硬體、接好線、寫一堆程式、跑起來才發現 OCR 讀不到。Vibe Coding 作法是:在對話中模擬整條管線,每一步都先驗證再決定下一步。成本極低,迭代極快。

    實戰情境:家母的長照交班白板

    先講背景。家裡照顧阿嬤的居服員會在客廳牆上用一塊大白板做交班記錄:夜間活動、睡前狀況、昨夜睡眠、早/午/晚餐、活動、外出、陪伴狀況、排泄狀況、洗澡,共 12 個項目。每一項下面有幾個選項方格,居服員把一顆彩色磁鐵貼在正確的選項上。

    用意是交班:早班居服員進門就知道夜間情況,中班看早上發生什麼事,晚班接手時看到整天脈絡。白板是「人看的 UI」,極度務實。

    我這邊的需求是:這些資料要每月匯整,讓神經內科醫師看到阿嬤這個月的生活趨勢 —— 是不是睡眠惡化、食慾變差、活動量下降。這關係到藥物調整。原本我每天晚上八點親自去拍照記錄到 iDempiere,但我很清楚一件事:

    靠人不穩定。我不能保證自己每天都拍照,請妹妹拍她都不拍。任何依賴人的環節最終都會斷掉。

    所以目標很明確:零人工依賴的自動化管線。RTSP 攝影機 → 抽幀 → VLM 識別白板狀態 → 寫進 iDempiere。今晚就是要從零對話出這套設計。

    第一步:用 ffmpeg 抓一張給 AI 看

    對話一開始,AI 想直接讀 RTSP 流,但我的 Ubuntu 上沒裝 ffmpeg,只有 VLC,而且 VLC 一直被 satip 模組攔截。試了幾個旗標都失敗。最後決定直接 apt-get install ffmpeg,然後:

    ffmpeg -y -rtsp_transport tcp \
      -i "rtsp://:@192.168.0.53:554/stream1" \
      -frames:v 1 -update 1 -q:v 2 /tmp/tapo/whiteboard_hd.jpg

    一張 1920×1080 的 frame 落地。第一個教訓:TAPO 有 stream1(主碼流,1080p)跟 stream2(子碼流,較低畫質),白板 OCR 一定要用 stream1,子碼流字跡會糊到任何模型都讀不出來。

    把第一張 frame 丟給 AI 看,AI 發現:

    • 畫面是廣角客廳全景,白板只佔左後方約 25%
    • 白板有角度(側視),字有透視變形
    • 阿嬤正躺在沙發上睡 —— 這畫面本身就能當「夜間睡眠」的訊號來源
    • 時間戳在左上角,直接可當記錄時間

    這是 Vibe Coding 的第一個價值:「看到了才知道要問什麼」。事先想像不到的細節(阿嬤就在沙發上、一顆鏡頭可同時驅動多個欄位),第一張實拍 frame 全部揭露。

    Gemma 4 vs Gemini 3 Flash Preview:一張圖的殘酷對比

    我手上的 Gemini API Key 支援 Google AI Studio,我問 AI 能不能用我已經在跑的 gemma-4-26b-a4b-it(我本來拿它做 HN 文章摘要)。AI 坦白說:不確定 Gemma 4 這個 MoE 版本有沒有 vision 能力,最好的方式是直接寫 script 試。

    寫完測下去,兩個結論:

    1. Gemma 4 確實吃圖 —— 這是好消息
    2. 但它嚴重幻覺 —— 它把日期讀成「4月10日」(實際 4/14)、項目名自創「睡眠品質/活動量/食事/盥洗」(白板上根本沒這些)、備註整段編造「各位家屬提醒…」。所有項目都回「綠」,明顯是在套公版答案

    切換到 gemini-3-flash-preview(Gemini 3 系列的 flash preview 版本),同一張圖,結果判若兩人:

    項目Gemma 4Gemini 3 Flash Preview
    項目名自創 5 個通用項目讀出 13 個具體項目
    備註段落純幻覺讀出「為了照護過程順暢請大家配合…飲食攝入小於 500ml 請 Line 通知…」
    品質差距低解析度下直接編造雖有 OCR 誤差但是「在讀真的東西」

    Gemini 3 Flash Preview 讀出的備註段落跟我白板上實際寫的紅字幾乎一致 —— 它不是在猜,是真的看到了。雖然還有誤差(把「外出狀況」讀成「外服藥記」、把「排泄」讀成「排便」),但那些是視覺相似字誤差,不是幻覺。

    這是第二個教訓:「同一張圖丟不同模型」是物聯 AI 應用最該做的前測。同價位的模型在模糊中文手寫這種邊緣任務上差距可以是幾倍級的。不要以為「我手上這把就夠用」。

    iDempiere REST API:從文件陷阱到 10 分鐘跑通

    OCR 能讀不代表能寫。寫入端是我自己建的 iDempiere,一張叫 Z_momSystem 的表。AI 不知道 schema,我也懶得翻 UI,直接讓它打 REST API 取。

    這裡踩第一個坑:iDempiere REST API 的認證流程文件跟實作不一致。我的 brain 筆記寫兩步驟(POST 拿暫時 token → PUT 帶 clientId 換 session token),但 AI 試了之後發現:直接在 POST 時一次帶齊所有 ID 也可以成功:

    POST /api/v1/auth/tokens
    {
      "userName": "",
      "password": "",
      "parameters": {
        "clientId": 1000000,
        "roleId": 1000000,
        "organizationId": 0,
        "warehouseId": 0,
        "language": "zh_TW"
      }
    }
    → 直接回 session token

    四個參數缺一不可,少 roleId 就回 Missing roleId parameter。這種小細節沒人會寫在文件裡,只能撞過才知道。AI 在對話中撞完就直接更新我的 brain file:

    [source: 長照 OCR 專案 2026/4/14] 驗證過 POST 一次帶齊 clientId/roleId/organizationId/warehouseId 可直接拿到可用 token,不用走 PUT 兩步。

    這是 Vibe Coding 第三個價值:踩到的坑立刻回饋到未來。不寫記錄的話,下個專案又會踩一次同樣的坑。

    Schema-Constrained Prompt:讓模型不能亂編

    認證跑通後,AI 直接查 AD_Column + AD_Ref_List,把 Z_momSystem 的 40 個欄位跟 12 個清單型欄位的所有合法選項抓齊:

    欄位合法選項(id → 中文)
    NightActivity 夜間活動C=完成 / N=未完成 / S=抗拒
    BeforeSleepStatus 睡前狀況X=亢奮 / N=正常 / S=疲倦
    LastNightSleep 昨夜睡眠G=良好 / S=斷續 / N=差
    Breakfast/Lunch/DinnerN=正常 / 10000001=少 / 10000009=多 / 10000002=拒食
    ExcretionStatus 排泄狀況10000006=正常 / 10000007=便秘 / 10000008=稀

    拿到完整選項清單後,我跟 AI 共同寫出 Prompt v2,核心設計有四塊:

    1. 嚴格列出 12 個欄位名稱 + 每個欄位的合法 enum,告訴模型「只能從清單裡選,不要自由發揮」
    2. 明確定義磁鐵規則:磁鐵貼在選項上 = 選中;磁鐵在左側待命區 / 沒看到磁鐵 = 未填(null)
    3. 強制輸出信心度:high / medium / low,並規定「寧可標 low 也不要亂猜」
    4. 禁止事項明確化:不要輸出清單外的項目、不要用清單外的值、不要把空白當選中

    這個 Prompt 模式我叫它 Schema-Constrained Prompt:輸出 schema 先於輸入內容確定。模型的自由度被壓縮到只剩「讀」,不能「想」。對資料入庫型應用來說,這是我目前看過最能壓住幻覺的作法。

    信心度機制:為什麼寧缺勿錯比高準度更重要

    我跟 AI 討論一個核心問題:如果 OCR 讀錯一個欄位,後果是什麼?答案是 —— 醫生根據錯誤資料調藥

    這條紅線決定了整個系統的預設行為:

    • High confidence → 直接寫入 iDempiere
    • Medium confidence → 寫入但標記為待確認,月底回診前我掃一次
    • Low confidence → 不寫,保留原圖,等我手動補

    這樣最差情況是「資料不全」而不是「資料錯誤」。對臨床情境來說,null 永遠比錯值安全

    最後的物理牆:磁鐵只有 3 像素

    所有準備工作做完,Prompt v2 在手、schema 對齊、認證跑通。我說「跑」,ffmpeg 抓一張新的 frame、裁切、送 Gemini 3 Flash Preview。結果回來:

    {
      "date": "4月10日",
      "patient_name": "",
      "items": {
        "NightActivity": {"value": null, "confidence": "high"},
        "BeforeSleepStatus": {"value": null, "confidence": "high"},
        ... 12 個項目全部 null ...
      },
      "overall_notes": "白板所有項目的磁鐵均位於最左側待命區,表示尚未填寫狀態。"
    }

    問題是 —— 我明明告訴 AI,最上面兩項的磁鐵是貼在選項上的。模型卻全讀成 null。這代表什麼?

    我們一起算了一下畫素:在當前 TAPO 攝影機位置,1080p 畫面中白板只佔約 25%,每個選項方格大概 40×20 像素,磁鐵大約 3~5 像素寬。

    任何 VLM 都讀不出 3~5 像素的物體位置。不是模型問題,是物理極限。

    這是整晚最重要的一個教訓。我原本以為換到 Gemini 3 就能解決一切,但真正的瓶頸不在模型,在光學。你沒辦法用演算法放大不存在的資訊。

    有意思的是,這個結論不是我預設的,是對話中算出來的。如果我沒跟 AI 一起 debug、一起看 crop、一起數像素,我可能還在抱怨「模型不夠強」,然後浪費錢去升級 model tier。實際上答案是「把鏡頭移近到 1.2 公尺」或「把磁鐵換大到 3 公分以上」—— 兩個都是硬體側的改動。

    Vibe Coding 在物聯 AI 開發上的六個心得

    整晚下來,我想整理出一些可以帶到下個專案的方法論:

    1. 第一張真實 frame 永遠比規格重要

    物聯 AI 專案第一件事不是畫架構圖,是用 ffmpeg / curl 抓一張真實資料給 AI 看。看到之後你才會發現「原來畫面裡還有沙發」、「原來字有角度」、「原來磁鐵只有 3 像素」—— 這些事事先想不到。

    2. 同一任務丟多個模型前測

    不要假設「手上這把就夠」。Gemma 4 跟 Gemini 3 Flash Preview 在同一張圖上差距巨大,如果我沒前測直接開始寫 production code,下游全部要重做。前測成本只有一個 Python script。

    3. Schema 先於 Prompt

    Prompt 不應該從「我想知道什麼」開始寫,應該從「我資料庫裡有什麼欄位、合法值是什麼」開始寫。把 enum 硬塞進 prompt,模型就只能從那個清單選。幻覺空間瞬間縮到 0。

    4. 信心度是一等公民

    每個欄位都要輸出信心度,而且模型要被明確告知「寧缺勿錯」。信心度不是錦上添花,是讓系統可以在「自動化」跟「人工審核」之間無縫切換的基礎設施。

    5. 踩到的坑要立刻寫回知識庫

    iDempiere REST API 的認證細節、TAPO stream1/stream2 的差異、VLM 對 3 像素物體的物理極限 —— 這些東西踩過一次就要寫下來。否則半年後你或你的下一個 AI 助手會原地再踩一次。

    6. 永遠先問「這個瓶頸是模型還是物理」

    當 AI 應用做不出效果時,工程師的直覺是「換更大的模型」。但物聯 AI 應用有一半以上的瓶頸是光學 / 聲學 / 感測器物理,不是模型。在升級 model tier 之前,先算一下原始訊號的解析度夠不夠。

    一晚的進度清單:完成、撞牆、下一步

    分類項目狀態
    環境ffmpeg + venv + google-genai SDK
    模型選型gemini-3-flash-preview 確認為白板 OCR 唯一可用
    API 認證iDempiere REST auth flow + brain 更新
    SchemaZ_momSystem 40 欄位 + 12 清單欄位合法值
    Promptv2 schema-constrained + 信心度
    實拍 OCR12 項全 null(物理極限)
    下一步鏡頭移近至白板前 ~1.2m 或把磁鐵換大🔜

    尾聲:AI 協作不是減少思考,是加速思考

    這一晚最大的收穫不是程式,是幾個原本需要好幾天才能驗證的判斷,在對話中幾個小時就走完了:

    • 「Gemma 4 能不能做 vision OCR」—— 10 分鐘驗證完
    • 「iDempiere REST API 認證怎麼打」—— 15 分鐘跑通
    • 「Z_momSystem schema 長怎樣」—— 5 分鐘 curl 查完
    • 「Prompt 用什麼結構壓住幻覺」—— 30 分鐘寫完 + 測完
    • 「OCR 失敗的根本原因是什麼」—— 從「模型不夠強」修正到「物理像素不夠」

    如果自己慢慢摸,這些決策可能得花一個禮拜,還未必會發現最後那個「像素物理牆」的結論。

    但 Vibe Coding 也不是萬靈丹。它的前提是你自己要會即時判斷 AI 給的答案對不對。如果我不知道「1080p 遠距離下一顆磁鐵只有幾像素」該怎麼算,我不會發現光學才是真兇,可能還會繼續跟 AI 討論要換什麼模型。AI 負責快速生成假設跟驗證工具,但關掉討論的那個人還是我

    下一步很清楚:明天白天我會去把攝影機搬到白板正對面 1.2 公尺處,如果還不夠,就把磁鐵換成 3 公分的大顆粒。然後再跑一次 Prompt v2,看看準度能衝到 8/12 還是 12/12。

    等驗證完整條管線跑通,我會再寫第二篇:零人工依賴的長照自動化 —— 從 OCR 到 iDempiere 到每月回診的完整管線。這一篇先停在「撞到物理牆」這裡,因為這個結論本身就夠值得記下來了。

    後續實戰:從撞到物理牆到 Telegram Bot 上線

    前一篇的結尾停在「撞到物理牆」,隔天白天我接著實戰。這一段記錄從 PTZ 鏡頭控制、模型賽馬、到最後關鍵 pivot 的完整過程。

    後續重點摘要

    • ONVIF PTZ 跑通:TAPO C200 用 RTSP 同帳密就能從 ONVIF 控制 pan/tilt,存 preset 在「看媽媽」跟「看白板」間自動切換
    • 但物理牆還在:C200 沒有 ONVIF zoom,白板在畫面裡的絕對大小被鏡頭距離鎖死
    • 模型賽馬揭露真相:Gemma 4 / Gemini 2.5 Flash 會套預設答案假裝在看;只有 Gemini 3 Flash Preview 跟 2.5 Pro 真的「在看」
    • 關鍵 pivot:放棄 RTSP 自動化,改走「手機拍照 + Telegram Bot」,把 human 設計進 loop 當 verifier
    • 最後上線:Telegram Bot + Gemini 3 Flash Preview + iDempiere REST API + systemd service,免費版每日 20 次額度剛好夠 production 用

    第一回合:ONVIF PTZ 成功,但沒有 zoom

    既然 TAPO C200 是 PTZ 型號(有 pan/tilt 馬達),自然想法就是「平常看媽媽、每天 20:00 轉過去拍白板、拍完轉回來」。代價幾乎為零:不改位置、不買硬體、不影響監護。

    TAPO 的本地 API 很頭痛,新版韌體要另外設定「Camera Account」。試了 pytapo 套件一直認證失敗。最後發現 ONVIF 標準協定可以直接用 RTSP 同帳密,port 2020:

    from onvif import ONVIFCamera
    cam = ONVIFCamera("192.168.0.53", 2020, "", "")
    ptz = cam.create_ptz_service()
    media = cam.create_media_service()
    token = media.GetProfiles()[0].token
    
    # Save current position as preset
    req = ptz.create_type("SetPreset")
    req.ProfileToken = token
    req.PresetName = "mom"
    ptz.SetPreset(req)
    
    # Move to whiteboard preset
    req2 = ptz.create_type("GotoPreset")
    req2.ProfileToken = token
    req2.PresetToken = "2"   # whiteboard preset token
    ptz.GotoPreset(req2)

    30 分鐘內建好兩個 preset:mom (pan=0.165, tilt=-0.714) 看沙發、whiteboard (pan=0.2, tilt=-0.3) 看白板。自動切換、抽幀、切回,全程 10 秒內。

    但查 PTZ 能力的時候發現一個殘酷事實:

    AbsoluteZoomPositionSpace: []

    C200 的數位 zoom 不對 ONVIF 開放。pan/tilt 能改變「看哪裡」,但不能改變「看多近」。白板在畫面裡的絕對大小還是被物理距離鎖死,磁鐵還是只有幾個像素。

    這是今天的第一個重要教訓:即使有 PTZ,沒有 zoom 的 PTZ 解決不了光學採樣率不足的問題。pan/tilt 的價值在於切換主題,不是放大細節。

    第二回合:四個模型的殘酷賽馬

    既然 PTZ 轉過去也只是切換主題、不會變清楚,我決定做一件更有意義的事:在同一張困難的 RTSP 照片上,把所有可能的模型跑一遍,看哪個真的「在看」。

    測試方法:請媽媽的居服員確認白板上 12 個項目的真實狀態(4 個 box 1、2 個 box 2、6 個 null),這是 ground truth。同一張 RTSP 照片丟給四個模型,計算準度。

    模型命中行為模式
    Gemini 2.5 Pro8/12 (67%)6/6 null 正確、off-by-one 錯誤,真的有在讀像素
    Gemini 3 Flash Preview6/12非常保守,看不清就全回 null(這在醫療情境反而安全)
    Gemini 2.5 Flash4/12預設 box 1,剛好對 4 個 box 1 項目,是幻覺而不是識別
    Gemma 4 (26B-A4B-IT)3~4/12兩次跑結果不一樣:第一次全 box 2、第二次全 box 1

    最有意義的發現:跑同一張圖兩次讓偽答案現形。Gemma 4 第一次答「10 項 box 2 + 1 項 box 1 + 1 項 null」,第二次答「12 項 box 1」。兩次完全不同,同一張靜態圖,同一個 prompt。這證明 Gemma 4 根本沒在看磁鐵,只是在套一個預設樣板。

    便宜模型「預設 box 1」這個偏誤特別危險,因為它剛好能騙過不注意的測試者:真實世界裡大部分項目本來就選 box 1(例如「完成/正常/穩定」通常是第一格),所以「全答 box 1」天然就有 30~50% 命中率。

    Gemini 2.5 Pro 的 8/12 表現是最高的,錯誤都是「off-by-one」(看到磁鐵、算錯格子),至少是在做真正的視覺識別。但 2.5 Pro 免費版不開放 vision,要付費才能用。

    Gemini 3 Flash Preview 的 6/12 看起來輸給 2.5 Pro,但它的錯誤類型完全不一樣:它的「錯」是把有磁鐵的項目讀成 null,不會產生錯誤的 value。這在醫療場景反而是最安全的行為 —— 寧缺勿錯永遠優於硬填。

    第三回合:投票沒用、upscale 沒用

    既然 Gemini 2.5 Pro 有 67% 準度,同一張圖跑 3 次取多數票應該能把 67% 拉高吧?

    結果投票後掉到 6/12。為什麼?因為 2.5 Pro 的錯誤不是隨機噪音,是系統性偏誤:某個項目 3 次都答同一個錯的答案。投票對系統性錯誤完全沒用,它只會把多數的錯誤鎖定成最終答案。

    接著試 pre-upscale:先用 ffmpeg 把白板區域裁出來、用 Lanczos 4 倍放大、加 unsharp,再丟 Gemini。直覺上放大應該有用,對吧?

    ffmpeg -i wb.jpg -vf "crop=720:820:480:30,scale=iw*4:ih*4:flags=lanczos,unsharp=7:7:1.5" wb_up.jpg

    結果:2.5 Pro 從 8/12 掉到 6/12,3 Flash Preview 從 6/12 掉到 2/12。放大反而讓準度下降。

    事後想通:Lanczos 是重採樣,不是超解析。它只是讓相鄰像素平滑插值,沒有增加資訊量。原本 3 像素的磁鐵放大成 12 像素,但那 12 像素是模糊的平均值,模型反而更難從中辨認形狀。

    要真的增加資訊量必須用 AI 超解析(Real-ESRGAN 這類),而不是幾何插值。但那會在機器上增加 PyTorch + 模型的負擔。與其走這條,不如直接面對問題:RTSP 這條路本身就有上限

    關鍵 Pivot:把 human 設計進 loop

    這是今天最重要的決策點。

    我原本堅持 RTSP 全自動,理由是「靠人不穩定,請妹妹拍她都不拍」。這個理由本身沒錯 —— 強制依賴他人的流程一定會斷。但我把「靠他人」跟「靠自己」混為一談了。我自己每天可以拍照,不穩定的只是「依賴別人」這一環

    更深層的領悟:為什麼執著於「100% 自動」?因為我下意識想把人完全排除。但對一個給醫生回診參考的月報系統來說,人的角色不該是全被排除,而應該是最後一道驗證。理由:

    • OCR 永遠有錯,醫療資料的錯誤比缺失代價更高
    • 家屬(我)本來就是最終看月報的人,有修正權限跟動機
    • 拍照的動作本身就是「我已經確認白板內容正確」的確認點
    • 沒有必要為了系統 purity 去承擔「誤導醫生」的風險

    這是整個專案最有價值的 design pattern 轉變 —— 從「zero-human automation」到「human-as-verifier」。具體分工:

    角色職責
    我(家屬)看白板、判斷、拍清楚的照片、事後在 iDempiere 修正 OCR 誤判
    Bot + Gemini 3把照片轉成結構化資料寫進 iDempiere、附上原檔
    iDempiere永久保存、提供 UI 讓月底回診時查閱

    最可怕的情境 —— OCR 幻覺亂寫進 DB 誤導醫生 —— 被「我本來就要檢查 iDempiere」這個 policy 擋住了。系統可以不完美,因為人在迴圈裡。

    Telegram Bot 架構

    決定走 human-in-the-loop 後,剩下的工程問題是「怎麼把手機拍的照片快速送到 server」。選項比較:

    方案優點缺點
    Telegram Bot零 app 安裝、即時回饋、從任何地方都能傳要建 bot token
    Syncthing 資料夾同步純本機、無雲端要裝 app + 手動移動檔案
    自架 HTTP 上傳頁不用 app要開 browser、每次登入

    Telegram 明顯最低摩擦,而且我本來就用 Telegram 傳照片 debug。一個 @BotFather 建 bot、5 分鐘拿到 token、寫一個 Python 長輪詢腳本就搞定。

    Bot 的最終能力:

    使用者動作Bot 行為
    📸 傳白板照片Gemini 3 Flash Preview OCR → 找今天紀錄 → update 或 create → 附加照片 → drain 文字佇列
    📝 傳 LINE 居服員回報文字[SHIFT|HH:MM] 前綴 → prepend 到今天紀錄的 Description 欄位
    🕑 今天還沒紀錄時傳文字存 pending 佇列,等照片來時自動塞入
    /pending, /clear, /id管理指令

    Shift 標記:用時段而不是時間點

    iDempiere 既有資料的 Description 欄位有一個我沒注意到的約定格式:

    [NIGHT|20:13]今天把東西往外丟
    [DAY|17:56]攻擊居服員

    格式是 [SHIFT|HH:MM]事件,新的在最上面,\n 分隔。照顧者三班制:

    • DAY(早班):07:00-17:59
    • NIGHT(晚班):18:00-23:59
    • GRAVEYARD(大夜):00:00-06:59

    Bot 根據當下時間自動產生正確的 shift 標記。這個設計好處是醫生看月報時能直接對應到「哪一班回報的事件」,這對失智照護尤其重要 —— 同一個病人,不同班次的表現可能完全不同(例如日落症候群)。

    Find-or-Create:同一天一筆紀錄

    一個設計決策:同一天傳多次照片要建新紀錄還是更新舊的?

    選項:

    • (a) 每次都 create 新的 → iDempiere 一天可能有多筆,報表聚合需要 GROUP BY 日期
    • (b) 同天 find-or-update → 資料乾淨,但要實作 OData filter 查當天紀錄
    • (c) 帶時序保留所有版本 → 最完整但最複雜

    選 (b)。理由是月底回診時醫生看的是「今天的狀態」,不需要看一天之內的修改歷史。實作核心:

    def idempiere_find_today(token):
        date_str = datetime.now().strftime("%Y-%m-%d")
        r = requests.get(
            f"{IDEMPIERE_URL}/models/z_momsystem",
            headers={"Authorization": f"Bearer {token}"},
            params={"$filter": f"DateDoc eq '{date_str}' and Name eq '{PATIENT_NAME}'", "$top": 1},
        )
        recs = r.json().get("records", [])
        return recs[0]["id"] if recs else None

    還有一個巧妙設計:OCR 回 null 的欄位不進 PUT payload。這樣早上拍一次只填前 6 項、晚上拍一次只改後 6 項,早上的資料不會被晚上的 null 洗掉。整個合併邏輯在 Python 端就搞定,iDempiere 端只接受「明確填入」的欄位。

    iDempiere 附件上傳的小坑

    iDempiere REST API 的附件端點是 POST /models/{table}/{id}/attachments,payload 是 {"name": "...", "data": "base64..."}。踩了一個坑:重複檔名會回 409

    解法:上傳時把當下的 HHMMSS 塞進檔名 suffix。同一張照片重複上傳也不會衝突:

    ts = datetime.now().strftime("%H%M%S")
    fn = f"{orig.stem}_up{ts}{orig.suffix}"

    Systemd Service 自動重啟

    最後收尾:bot 用 systemd service 跑,開機自動啟動 + 崩潰自動重啟。關鍵是設定 Restart=on-failureRestartSec=10

    [Unit]
    Description=Tapo Caregiver Telegram Bot
    After=network-online.target
    Wants=network-online.target
    
    [Service]
    Type=simple
    User=tom
    WorkingDirectory=/home/tom/tapo-caregiver
    ExecStart=/home/tom/tapo-caregiver/venv/bin/python telegram_bot.py
    Restart=on-failure
    RestartSec=10
    Environment=PYTHONUNBUFFERED=1
    
    [Install]
    WantedBy=multi-user.target

    成本:免費版剛好夠用

    這個專案我原本因為 debug 爆量升級了 Google AI Studio 付費版。但實際跑 production 的時候算了一下用量:

    • 晚上 8 點拍一次照片 = 1 次 Gemini 3 Flash Preview 呼叫
    • LINE 回報文字 = 0 次(純文字不進 OCR,只是 prepend 到 Description)
    • 一天總用量:1~2 次

    Gemini 3 Flash Preview 的免費 tier 是 每天 20 次GenerateRequestsPerDayPerProjectPerModel-FreeTier, limit: 20, model: gemini-3-flash),實際從先前的 429 錯誤訊息確認過。

    也就是說 完整上線後可以馬上取消付費,免費額度就夠日常跑。debug 階段的付費只是為了不被 quota 卡住開發速度。

    兩天下來的反思

    1. 物理限制不是模型問題,不要用演算法去試

    RTSP 畫面中磁鐵 3~5 像素這件事,不管換什麼模型、不管怎麼放大、不管怎麼 prompt,都解決不了。我浪費了兩輪嘗試才認清:先驗證訊號源的解析度是否足夠,再決定上面要疊什麼演算法

    2. 便宜模型會偽裝在看

    Gemma 4 和 Gemini 2.5 Flash 在困難任務上會套預設答案(全 box 1 或全 box 2),這種偽答剛好能騙過不注意的準度統計。同一張圖跑兩次是揭穿偽答最便宜的方法 —— 真的在看的模型答案應該高度一致,套公版的會變。

    3. 投票救不了系統性偏誤

    Gemini 2.5 Pro 跑 3 次投票準度從 8/12 掉到 6/12,因為它的錯誤是系統性的(3 次都答同一個錯的答案)。投票只對隨機噪音有用,對系統性偏誤沒用。想救系統性偏誤,要用不同模型交叉比對,而不是同一個模型多次跑。

    4. Human-in-the-loop 不是妥協,是正確設計

    我原本想做 100% 自動化是出於「系統純粹」的直覺。但對醫療情境來說,把人排除才是風險來源。正確問題不是「怎麼不靠人」而是「人在哪個環節最有價值」。答案是:人當最終 verifier,機器做勞力密集的 OCR + 結構化 + 儲存。

    5. 工具思維 vs 平台思維

    我原本想把 RTSP 攝影機變成一個「全知白板記錄系統」,這是平台思維,野心大但難。pivot 之後變成「Telegram bot 幫我打字少打一些」,這是工具思維,目標小但能跑。工具思維的上線速度 ≫ 平台思維的完美程度

    6. 讓 AI 自己跑模型賽馬

    過程中我讓 AI 自動跑一圈 Gemma 4 / 2.5 Flash / 2.5 Pro / 3 Flash Preview,把命中率、錯誤類型、各自的 observation 都列出來。我只要看那張表就能判斷用哪個。這種「讓 AI 幫你比較 AI」的 meta-loop 是 vibe coding 很爽的一點 —— 選型決策從「讀文件猜性能」變成「直接實測算分」。

    最終上線狀態

    組件狀態
    Telegram bot(@your_bot_name,白名單限制)✅ LIVE
    Gemini 3 Flash Preview OCR (schema-constrained + box index + layout map)
    iDempiere REST find-or-create + attachment upload
    Description shift tag (DAY/NIGHT/GRAVEYARD) 自動 prepend
    pending notes queue(文字先到、照片後到的情境)
    systemd service 開機自動啟動
    PTZ ONVIF 控制(暫時不用,因為 pivot 到手機路線)✅ 備用

    每日 SOP:

    1. 晚上 8 點我拍一張白板照片
    2. Telegram 分享給 @your_bot_name
    3. Bot 跑 OCR + 寫 iDempiere + 回覆結果(10~20 秒)
    4. 看到有讀錯的,打開 iDempiere 手動改
    5. 居服員白天在 LINE 的回報,我看到時直接貼到 bot,自動 prepend 到今天的 Description
    6. 月底回診時點開 iDempiere 給醫生看趨勢

    總結:這篇文章的「二階 vibe coding」

    這篇文章本身也是 vibe coding 的產物 —— 我叫 AI 把兩天的工作回溯成一篇技術文,自己只負責審核跟指正敏感資料。這種「AI 幫你跟 AI 協作的過程寫回顧」也算是一種 meta-loop:決策的當下有 AI 幫忙驗證,事後有 AI 幫忙紀錄。我負責方向跟價值判斷,剩下的雜活都給 AI。

    兩天下來最重要的一句話:「vibe coding 不是減少思考,是加速思考。」 AI 幫你快速驗證假設、生成原型、寫測試、跑實驗、甚至幫你寫反思文章。但你要知道該往哪個方向走、什麼時候該 pivot、什麼時候該停手。AI 是踏板車,你是駕駛。

  • Ionic 逆向重建 Flutter 完整踩坑紀錄:三套 APP、20+ 個坑、一套方法論

    重點摘要

    • 從 Ionic 1 / AngularJS + WordPress PHP 逆向重建三套 Flutter APP,歷時一週,踩了 20+ 個分類的坑
    • 最毒的方法論錯誤:審查時讀了原始碼,實作時卻只靠缺失清單——導致多輪審查永不收斂
    • PHP Broker API 的 Content-Type 是 text/html、數值欄位全是 String、token 欄位名稱每個子系統不同
    • WordPress Multisite 的 table prefix 陷阱:直接打 plugin 路徑走 main site(wp_),跟 WP Admin 看到的(wp_2_)不同
    • 逆向工程的核心原則:原始碼是唯一 ground truth,不是用戶的記憶,不是截圖,不是 AI 的推測

    這篇文章記錄了一個完整的逆向重建專案:將一套社區管理系統(三套 APP + WordPress 後端)從 Ionic 1 / AngularJS 遷移到 Flutter。不是新開發,是一比一逆向複製——原版有的每一個按鈕、每一個欄位規則、每一個邊角功能,新版都必須完全復現。

    三套 APP 分別是:住戶 APP(社區公告、包裹、費用等)、管理平板(出勤、包裹管理、公設租借、訪客登記等)、門禁保全 APP(簽到簽退、巡邏、QR 掃描)。它們共用同一個 WordPress PHP 後端。

    以下是按主題分類的完整踩坑紀錄和方法論總結。

    一、逆向重建最毒的方法論錯誤是什麼?

    逆向重建最毒的方法論錯誤是「審查讀原始碼、實作不讀」。這聽起來不可能,但在 AI 輔助開發中極其常見:

    1. 審查 Agent:從原版 HTML / JS 逐行讀 → 產出缺失清單 → 每項有行號出處 ✅
    2. 實作 Agent / 新 Session:拿到缺失描述(如「公告無窮捲軸缺失」)→ 直接寫 Flutter → 沒有讀原版邏輯
    3. 結果:修了 A,同頁的 B/C/D 仍缺(因為根本沒讀那頁的完整原始碼)
    4. 下輪審查:再從原版讀 → 再找到 B/C/D → 循環不斷

    我們經歷了 7 輪審查才讓管理平板的缺失清單收斂。前 3 輪每輪都有 10+ 個新發現,根本原因只有一個——方向反了。

    建立的強制規則

    • 拿到缺失 ID 時,必須先讀對應的原始碼(file:line),不得只靠缺失描述動手
    • 修某頁某功能時,如果手上沒有該頁完整 Source Inventory → 必須先做 Source Inventory
    • Review 方向必須是:原版 HTML → 原版 JS → 原版 PHP → 列清單 → 逐項對照新版。禁止從 Flutter 出發猜原版有什麼

    二、Source Inventory 協議:逆向工程的唯一正確開始方式

    Source Inventory 是在動手寫任何程式之前,先把原版的所有功能逐行列出來的過程。每一項都必須標注原始碼來源(檔案 + 行號),沒有行號的項目等於捏造的。

    - [ ] 登出按鈕
          來源:account.html:142 <button ng-click="logout()">
    
    - [ ] 棟別/樓層兩層下拉選單
          來源:visitor-form.html:55-67, controllers.js:9366-9398
    
    - [ ] 黑名單檢查(借用簽名後、API 呼叫前)
          來源:publicequip.js:2040-2052

    清單涵蓋四大類:所有 UI 元素(按鈕、欄位、badge、空狀態提示)、所有互動行為(點擊、滑動、下拉刷新)、所有 API 呼叫及欄位映射所有頁面入口/出口

    最容易漏的永遠是邊角功能:登出藏在 header component、空狀態提示在條件分支、黑名單檢查在簽名驗證之後。主流程之外的東西,AI 不會主動去找。

    三、PHP Broker API 的七大陷阱

    這套系統的 API 層是 WordPress PHP plugin,所有請求都走同一個 Broker endpoint。以下是我們踩過的每一個 API 相關的坑:

    3.1 Content-Type 是 text/html

    PHP Broker 的回應 Content-Type 是 text/html 而非 application/json。Dio(Flutter HTTP 套件)如果設了 ResponseType.json,會解析失敗。必須設 ResponseType.plain 再手動 jsonDecode

    3.2 數值欄位全是 String,除了偶爾不是

    大多數 JSON 數值欄位回傳的是字串("id":"1")。但 $wpdb->get_results() 對 int DB 欄位有時會回傳 PHP native int(JSON 裡沒有引號)。解法:所有 nullable String 欄位一律用 ?.toString(),避免 type 'int' is not a subtype of type 'String?'

    3.3 Token 欄位名稱每個子系統不同

    子系統 Token 放在 例外
    主 Broker(住戶/平板)data.cookie
    Guard Broker(門禁)data.tokenvalidate_authdata.cookie

    搞混了就會被判定為 anonymous user,API 回 "非有效角色,無法使用!",而且沒有任何認證失敗的明確錯誤碼

    3.4 returnCode 不統一

    "OK""0"(package 模組)、"1""ERROR""dup"——全是字串,不要做整數比較。每個模組的成功碼不同,必須逐一確認。

    3.5 Category / Method 命名混亂

    有的是 snake_case(get_ticket_by_member_id),有的是 camelCase(retrivePublicEquipTXN——對,retrive 是拼錯的),有的是完全不同的規則(createTableAccount)。必須從 PHP 程式碼抄出精確字串,不能猜。

    3.6 Response 結構不一致

    • mutual:回 {rows_1:[], rows_2:[]}(自己的 + 社區其他人的)
    • ticket:回 {data: {rows, total, totalPages}}(分頁結構)
    • package_light:returnCode 用 "0" 而非 "OK"
    • getTwCode:空表時回 data: ""(空字串),不是 []

    3.7 磁卡批次 API 是 flat array

    大部分 API 的 data 格式是 {data: {key: value}},但磁卡批次領取是平坦陣列 [{id, card_no, status}]。PHP 端用 is_array($data) 判斷。這意味著 Flutter HTTP client 的 data 參數不能寫死為 Map,必須改成 dynamic

    四、WordPress Multisite 的 Table Prefix 陷阱

    WordPress Multisite table prefix 陷阱是整個專案最令人崩潰的問題之一。直接打 plugin PHP 路徑(如 /wp-content/plugins/.../API_Broker.php)時,WP 識別為 main site (blog_id=1),使用 wp_ 前綴。但在 WP Admin 介面、phpMyAdmin 看到的是 wp_2_(子站表)。

    後果:seed 測試資料時插到 wp_2_ulifeplus_*,但 API 查的是 wp_ulifeplus_*——資料永遠看不到,而且不報錯,就是空陣列。

    另外,改網域必須改 5 個地方wp_options(siteurl + home)、wp_blogs(domain)、wp_site(domain)、wp-config.php(DOMAIN_CURRENT_SITE + WP_HOME + WP_SITEURL)。DOMAIN_CURRENT_SITE必須含 port,否則會無限 302 redirect。

    五、validate_role() 全面封鎖事件

    所有 28 個 PHP endpoint 都在進入主邏輯前呼叫 validate_role()。原版只接受 ulifeplus_api / ulifeplus_admin / administrator / ulifeplus_operator,不含住戶帳號 ulifeplus_subscriber

    原因:原版平板用的是專屬服務帳號(QR code 開通碼流程),不是住戶帳號直接登入。重建版讓住戶直接登入 → 所有 API 一律 ERROR

    修補方案需要雙層:(1) patch PHP 接受 ulifeplus_subscriber;(2) 給測試帳號加 ulifeplus_api role。而且 wp_capabilities 的序列化格式 a:N:{s:LEN:"role_name";b:1;} 的 LEN 必須精確——寫錯一個字元,整個 unserialize 就失效,用戶變成沒有任何 role。

    六、三套 APP 的進化軌跡:從混亂到方法論

    第一套:住戶 APP——摸清後端規則

    住戶 APP 是最先做的,主要踩了後端相關的坑:Content-Type 是 text/html、數值欄位全是 String、member_id vs WP user_id 混淆、validate_role 全面封鎖、WP Multisite table prefix。這些經驗讓我們對 PHP Broker 的行為有了完整的心智模型。

    第二套:管理平板——方法論崩潰與重建

    管理平板是最複雜的(10+ 模組),也是方法論崩潰的戰場。7 輪審查、每輪都有新發現、多個 Agent 交叉審查卻互相誤報(false positive)。最終逼迫我們建立了 Source Inventory 協議、四大卡點規則、和「審查必須從原版出發」的強制流程。

    核心教訓包括:

    • Grid → Card List 轉換會遺失 checkbox column 和 cellTemplate 等「免費」UI 行為
    • 條件式按鈕(enableShowClosed 等)的每個 ng-if 都是業務意圖,不能合併或省略
    • smart_disp.get_hidden_code() 遮名演算法需要完整移植,不能簡化
    • 日期範圍查詢必須含時間(00:00:00 / 23:59:59),否則 BETWEEN 漏掉當天
    • Feature flag 的預設值不一定是 false,必須讀完整條件判斷

    第三套:門禁 APP——方法論成熟

    到第三套門禁 APP 時,Source Inventory 協議已經內化。整個 APP 從原始碼分析到 21/21 測試通過只花了一天。但還是踩了新坑:

    • Guard Broker 的 token 欄位是 data.token(不是主 Broker 的 data.cookie
    • PHP class constant const data = "date" 從不生效(bareword array key 行為)
    • showDialog 的 BuildContext 跨 async 導致確認 dialog 靜默失敗
    • HTTP 部署下相機 API 被瀏覽器封鎖(Secure Context 限制)
    • Flutter Web 的 SPA 狀態在測試間污染(需 full HTTP reload)

    七、Flutter 遷移的技術坑清單

    症狀 修法
    flutter_secure_storage Web 失敗HTTPS 才能用 Web Crypto APIWeb 改用 SharedPreferences
    Platform.isAndroid Web crashdart:io 在 Web 不可用kIsWeb + defaultTargetPlatform
    CORS 重複 headerAccess-Control-Allow-Origin: *, *PHP 已有 CORS,不要加 .htaccess
    Dialog context stale確認後邏輯靜默跳過dialogCtx 不用外層 context
    Release build debugPrint 消失完全無錯誤訊息寫 SharedPreferences breadcrumb
    ConsumerWidget 無 initState需要 async 初始化改用 ConsumerStatefulWidget
    base-href 部署子路徑資源 404--base-href=/app/
    API_BASE_URL dart-defineWeb 連到 localhost--dart-define=API_BASE_URL=http://IP:PORT

    八、AI 輔助逆向工程的認知陷阱

    AI 輔助逆向工程的認知陷阱是這個專案最深層的教訓。AI 在讀原始碼方面能力極強,但在以下場景會系統性犯錯:

    1. 「我以為我知道這頁有什麼」——AI 會基於已讀的程式碼推測未讀的部分,經常猜錯
    2. 改名後誤報缺失——搜尋 scan_addr_code() 找不到,但 Flutter 用了 _scanAddressCode(),同樣邏輯換了名字就被誤報
    3. 函數名稱 ≠ 實際行為——updateUser() 實際上還做 log 寫入、狀態機轉換;getActiveItems() SQL 是 status != 'deleted' 不是 status = 'active'
    4. 「延後功能」不是藉口——AI 傾向把不確定的功能標記為「deferred」,但只要原版存在的就必須實作

    破解方式:建立 Source Inventory 清單,每項附行號。行號是可審計的(可以回去原始碼驗證),AI 的記憶不可審計。

    九、跨專案知識管理:Brain 檔案系統

    為了讓踩過的坑不只活在一個專案裡,我們建立了 Domain Brain 系統:每個技術領域一個 markdown 文件,記錄所有踩過的坑、修法、和來源。

    例如 legacy-code-rebuild.md 記錄了逆向工程的通用方法論;wordpress-broker.md 記錄了 WP Broker API 的所有特殊行為。每次 fix: commit 時,強制要求更新對應的 brain file。

    核心原則:Brain = 上次做的時候踩了什麼坑(經驗)Skill = 正確的做法是什麼(模式)。兩個都要讀。

    十、建議給想做逆向重建的團隊

    1. Source Inventory 先行——不管系統多簡單,先把所有功能列出來(附行號)。簡單的系統往往有最多隱性規則
    2. 後端先跑通——先用 curl 打通每一個 API endpoint,確認 request/response 格式,再寫 Flutter
    3. 每個模組獨立測試——不要等到所有模組做完才整合。我們的 21/21 unit + integration test 在開發過程中抓到了大量問題
    4. 記錄每一個坑——Brain 系統不是可選的,是必要的。第一套 APP 踩的坑如果沒記下來,第三套 APP 會再踩一次
    5. 不要信任 AI 的記憶——AI 會遺忘、會推測、會混淆。只有程式碼行號是可驗證的

    結語

    這個專案讓我深刻體會到:逆向重建的難度不在於「寫新程式」,而在於「完整理解舊系統」。舊系統的每一行 if/else 都是某個真實場景的反映,每一個看似多餘的欄位都有它存在的理由。

    AI 可以加速這個過程,但無法取代「逐行讀原始碼」這個步驟。捷徑是最遠的路——我們前 3 輪審查走了捷徑(從 Flutter 出發找問題),花了 3 倍時間;改用正確方法論(從原版出發列清單)後,第三套 APP 一天就完成了。

    希望這篇記錄能讓正在考慮做逆向重建的團隊少走一些彎路。

    追記:驗收階段又踩的五個大坑(2026-04-13 深夜)

    上面的文章發佈後幾小時,用戶開始實際驗收。結果又炸出一系列問題,每一個都是在開發階段「看了原始碼但沒看完整」造成的。

    坑 10:Dart 的 Map<dynamic, dynamic> 型別推導陷阱

    Flutter 的 API client 在呼叫 api.call(data: {}, token: token) 時,{} 空 Map literal 在 dynamic 參數中被 Dart 推導為 Map<dynamic, dynamic>。原本程式碼檢查 effectiveData is Map<String, dynamic>false → token 永遠不被加到 request 裡。

    影響範圍:27 個 API call。所有傳 data: {} 的頁面全壞(儀表板、帳號開通等),但傳了明確 key 的頁面(如 data: {'address_code': x})正常。這造成「有些頁面好有些壞」的假象,極難排查。

    教訓:原版 JavaScript param.token = value 不做任何型別檢查,直接賦值。重寫到靜態型別語言時,不要加「聰明」的型別守衛。笨方法之所以沒 bug,就是因為它笨。

    坑 11:config.js 常數映射層被完全忽略

    原版 Ionic 有一層 config.js 常數映射:sel → "select"upd → "update"del → "delete"add → "insert"sel2 → "select2"。Flutter 重寫時,有些地方用了短名(config.js 的 key),有些用了長名(PHP 接受的值)。PHP 只認長名。

    影響範圍:19 個 API call。寄放交辦頁面完全打不開(PHP switch/case 不匹配,回 ERROR 但 message 空字串),debug 時完全看不到線索。

    教訓:逆向重建時必須識別原版的每一層抽象。看了 controllers.js(呼叫端)和 factories.js(發送端)不夠——中間的 config.js 映射層不能跳過。每一個字串值都必須追到 PHP handler 的 switch/case 確認一致。

    坑 12:捏造不存在的 API method

    Flutter 程式碼裡出現了 method: 'select_category_detail'(包裹統計)和 category: 'util'(多帳號驗證碼)等原版完全不存在的 API call。追溯原始碼發現:前者在原版是純客戶端計算(groupBy + filter),後者正確的 category 是 'app_member'、method 是 'register_switchsite_validation_code'

    教訓:如果在原始碼裡找不到某個 API endpoint,那它就不存在。不要「合理推測」一個 API 可能存在。

    坑 13:API URL 不應該寫死在 compile time

    Flutter 用 --dart-define=API_BASE_URL=http://192.168.0.48:8010 在 compile time 寫死 API URL。結果 LAN 和 HTTPS 要分別 build,Cloudflare 快取舊 JS 時 URL 就錯。

    原版做法:API_BROKER_URL 在 config.js 是空字串,QR 碼啟動或登入時從 server 回傳 burl(blog_site_url),組合成完整 URL 存入 localStorage。

    修法:Web 版用 Uri.base.origin 自動偵測當前頁面的 origin 作為 API base URL。不管從哪個網域開,API 自動跟著。compile time 的 --dart-define 只作為 fallback。

    坑 14:外部服務走錯路由

    廣告 Banner API 在原版是打一個完全獨立的外部伺服器(vender01.tw),不是走 WP Broker。Flutter 把它包成了 category: 'ad_banner' 送進 WP Broker,當然找不到。

    教訓:原版有多個 factory(brokerFactorycommonServerFactoryomFactoryapi-vender),每個打不同的 server。重寫時必須識別每個 API call 走的是哪個 factory、打的是哪個 server。

    總結:為什麼驗收時才發現這些問題

    以上 5 個坑有一個共通點:「看了原始碼」不等於「看完了原始碼」。每次都是「看了主要的幾個檔案」但漏了中間層(config.js 映射、factory 路由、型別推導規則)。

    逆向重建的正確審查流程應該是:從 PHP handler 的 switch/case 開始,反向追每一個常數值回到 config.js,再追到 controllers.js 的呼叫端。不是從呼叫端出發猜 PHP 接受什麼。方向反了,就永遠追不完。

  • Flutter Web + Selenium E2E 測試踩坑全紀錄:九大實戰教訓

    重點摘要

    • Flutter Web 將所有 UI 渲染到 Canvas,Selenium 必須透過 Tab 鍵啟動語意樹(flt-semantics)才能操作元素
    • showDialog 的按鈕呼叫 Navigator.pop 時,必須使用 dialog 自己的 BuildContext,否則 async 後 context stale 會導致靜默失敗
    • HTTP 部署無法使用相機(非 Secure Context),需實作手動輸入 fallback
    • Release build 的 debugPrint 完全靜默,debug 必須靠 SharedPreferences breadcrumb + Selenium 輪詢 localStorage

    本文記錄了在 Flutter Web 應用上進行 Selenium E2E 自動化測試時踩過的所有坑。這不是教科書式的教學,而是一次完整的實戰復盤——從「為什麼 Selenium 找不到任何元素」到「為什麼確認 dialog 回傳 null」,每一條都是反覆碰壁後才理解的真相。適合正在做 Flutter Web 自動化測試、或考慮將 Ionic/AngularJS 遷移到 Flutter 的開發者。

    一、Flutter Web 語意樹(Semantics Tree)是什麼?為什麼 Selenium 找不到元素?

    Flutter Web 語意樹是 Flutter 為了無障礙功能(Accessibility)而產生的一組 DOM overlay 元素。與 React 或 Vue 不同,Flutter Web 預設將所有 UI 渲染到 <canvas> 元素中,DOM 裡沒有任何可見的文字節點。這意味著 Selenium 的常規定位方式(XPath 文字搜尋、CSS text selector)完全失效。

    如何啟動語意樹?

    語意樹由 flt-semantics 自定義元素組成,但預設是未啟動的。啟動方式只需要一行:

    driver.find_element(By.TAG_NAME, "body").send_keys(Keys.TAB)

    一次 Tab 鍵足以觸發整個語意樹。之後,所有語意元素都會以 <flt-semantics> 出現在 DOM 中。讀取文字的穩定做法:

    text = driver.execute_script("return arguments[0].innerText", element)

    語意角色速查表

    Flutter Widget CSS Selector 備註
    ElevatedButton / TextButtonflt-semantics[role='button']innerText 包含按鈕文字
    BottomNavigationBar Tabflt-semantics[role='tab']innerText 含 “Tab X of Y”
    SwitchListTileflt-semantics[role='switch']title 文字不在 innerText!
    FloatingActionButtonflt-semantics[flt-tappable]tooltip 文字在 innerText
    DropdownButtonflt-semantics[role='button']同按鈕角色

    最大的坑:SwitchListTile 的 title 文字(如「開始巡邏」)完全不會出現在語意樹的 innerText 中。你必須用 role='switch' 去定位元素,而不是搜尋 title 文字。這個坑讓我浪費了整整一小時。

    ScrollView 內容不在語意樹

    AlertDialog 裡的可滾動 ListView 內容(如 RadioListTile 選項列表)全部以 Canvas 渲染,不在 flt-semantics 中。測試時只能驗證「dialog 是否開啟」(確認「關閉」按鈕出現),無法直接驗證列表內容。

    二、Flutter Web SPA 狀態污染:為什麼 driver.get() 沒有重置頁面?

    Flutter Web SPA 狀態污染是指在同一個 Flutter 應用中,前一個測試留下的 widget 狀態(dialog、表單、loading)會影響下一個測試。這是因為 Flutter Web 使用 hash-based routing,driver.get(url + "/#/settings") 如果 hash 沒有變,瀏覽器不會發出新的 HTTP 請求,Flutter widget tree 完全保持原狀。

    # ❌ 錯誤:如果已在 #/settings,不會重置
    driver.get("http://host:port/app/#/settings")
    
    # ✅ 正確:先到無 hash URL(觸發真正的 HTTP reload)
    driver.get("http://host:port/app")         # Step 1: full reload
    time.sleep(3)
    driver.find_element(By.TAG_NAME, "body").send_keys(Keys.TAB)  # Step 2: 啟動語意樹
    time.sleep(1)
    driver.execute_script("window.location.hash = '/settings'")   # Step 3: SPA 導航
    time.sleep(2)

    這個模式在 session-scoped fixture 中尤其重要。當多個測試共享同一個 driver 時,前一個測試的 dialog 可能還開著,下一個測試找不到預期的元素。

    三、BuildContext 跨 async 使用的致命陷阱

    BuildContext 跨 async 陷阱是整個 debug 過程中最花時間的一個坑——3 小時才定位到根因。症狀是:確認 dialog 明明點了「是」,但後續邏輯完全沒執行,沒有任何錯誤訊息。

    問題程式碼

    Future<bool> _confirm(String message) async {
      final result = await showDialog<bool>(
        context: context,           // 外層 widget 的 context
        builder: (_) => AlertDialog(
          actions: [
            TextButton(
              // ❌ 用外層 context 呼叫 Navigator.pop
              onPressed: () => Navigator.pop(context, true),
              child: const Text('是'),
            ),
          ],
        ),
      );
      return result == true;  // null == true → false → 邏輯被跳過!
    }

    發生了什麼?

    1. showDialog() 開啟一個新的 Route(dialog route)
    2. 使用者點擊「是」
    3. Navigator.pop(context, true) 中的 context 是外層 widget 的 BuildContext
    4. 如果外層 widget 在 async 等待期間被 Framework 重建(例如 Provider 狀態更新),該 context 可能 stale
    5. Navigator.pop() 找到錯誤的 Navigator 或 pop 了錯誤的 route
    6. showDialog() 的 Future 得到 null(而非 true
    7. null == truefalse → 確認邏輯認為使用者「取消」了
    8. 所有後續程式碼被跳過,沒有任何錯誤訊息

    正確做法

    builder: (dialogCtx) => AlertDialog(
      actions: [
        TextButton(
          // ✅ 用 dialog 自己的 context
          onPressed: () => Navigator.of(dialogCtx).pop(true),
          child: const Text('是'),
        ),
      ],
    )

    通用規則:showDialog 的 builder 中,永遠使用 builder 參數提供的 context(命名為 dialogCtx),不要使用外層 widget 的 context。這在 Flutter 官方文檔中有提到「Don’t use BuildContext across async gaps」,但在 dialog builder 內部容易忽略。

    四、Release Build 下的靜默失敗:debugPrint 不見了

    Flutter release build 的靜默失敗是另一個時間殺手。flutter build web 產出的是 release build,以下行為與 debug build 完全不同:

    • debugPrint() 完全靜默——不會輸出到 browser console
    • assert() 完全跳過——不會觸發 assertion error
    • 未被 catch 的 async exception 由 Flutter Framework 處理,通常靜默記錄

    Debug Breadcrumb 技巧:寫入 SharedPreferences,Selenium 讀 localStorage

    // Dart side — 在 try/catch 每個步驟寫 breadcrumb
    try {
      final prefs = await SharedPreferences.getInstance();
      await prefs.setString('flutter.dbg', 'step_A: loading points');
      // ... 業務邏輯 ...
      await prefs.setString('flutter.dbg', 'step_B: saved record');
    } catch (e) {
      final prefs = await SharedPreferences.getInstance();
      await prefs.setString('flutter.dbg', 'ERROR: $e');
    }
    
    # Selenium side — 輪詢 localStorage
    for i in range(20):
        time.sleep(0.5)
        dbg = driver.execute_script("return localStorage.getItem('flutter.dbg')")
        print(f't={i*0.5}s  dbg={dbg}')
        if dbg and 'ERROR' in dbg: break

    這個技巧讓我在 5 分鐘內定位到「_confirm() 回傳 null」這個根因,而之前靠 console.log 完全看不到任何線索。

    五、Secure Context 限制:HTTP 部署的相機和 Service Worker 全掛

    Secure Context 是瀏覽器對某些敏感 Web API 的安全限制。以下 API 只在 HTTPS 或 localhost 下可用:

    • navigator.mediaDevices.getUserMedia()(相機 / 麥克風)
    • navigator.serviceWorker(Service Worker / PWA)
    • window.crypto.subtle(Web Crypto API,flutter_secure_storage 依賴此 API)

    用 HTTP + IP 位址部署 Flutter Web(如 http://192.168.x.x:8010),嘗試使用 mobile_scanner 掃描 QR code 會得到:

    MobileScannerException(unsupported, This browser does not support displaying video from the camera.)

    解決方案:Web fallback 自動降級

    @override
    void initState() {
      super.initState();
      if (kIsWeb) {
        // Web 版直接跳手動輸入,不嘗試開相機
        WidgetsBinding.instance.addPostFrameCallback((_) {
          _showManualInputDialog();
        });
      }
    }
    
    // 相機版的 errorBuilder 也要處理
    errorBuilder: (context, error, child) {
      if (error.toString().contains('unsupported')) {
        _showManualInputDialog();  // 降級為手動輸入
      }
      return child ?? const SizedBox.shrink();
    }

    生產環境建議架設 HTTPS(Let’s Encrypt / Nginx 反向代理),即可解除所有限制。開發環境用 localhost 也自動視為 Secure Context。

    六、SharedPreferences 在 Flutter Web 的雙重 JSON 編碼

    Flutter Web 的 shared_preferences 套件底層使用 localStorage,但有兩個容易踩坑的特性:

    Key 前綴

    prefs.setString('my_key', 'value');
    // 實際存儲為: localStorage['flutter.my_key']

    值的雙重 JSON 編碼

    prefs.setString('foo', '[{"id":1}]');
    // localStorage 實際內容: '"[{\\"id\\":1}]"'
    // 注意外層多了一組引號 + 轉義
    
    # Selenium 讀取時要解兩層
    import json
    raw = driver.execute_script("return localStorage.getItem('flutter.foo')")
    layer1 = json.loads(raw)     # 解 SharedPreferences 包裝
    parsed = json.loads(layer1)  # 解原始 JSON 內容

    七、非同步快取的時機問題:為什麼清單永遠是空的?

    非同步快取時機問題是一個隱蔽的 bug:App 啟動時以 async 方式從 API 抓取主資料(如巡邏點清單)並快取到 localStorage。但如果用戶在快取完成前就操作,快取為空 → 業務邏輯用空資料建立記錄 → 記錄一旦建立就再也不會重新抓取 → 永遠空白

    解法:On-demand fallback + 恢復修補

    Future<List<PatrolPoint>> _loadPatrolPoints() async {
      var rawPoints = await db.getCachedPatrolPoints();
    
      if (rawPoints.isEmpty) {
        // 快取為空 → 直接打 API 補抓(此 API 不需要 token)
        try {
          final live = await api.getNavPoints(token);
          rawPoints = live.map((item) => {
            'point_id': item['id']?.toString() ?? '',
            'point_name': item['navpoint_name']?.toString() ?? '',
          }).toList();
          if (rawPoints.isNotEmpty) await db.cachePatrolPoints(rawPoints);
        } catch (e) {
          debugPrint('Live fetch failed: $e');
        }
      }
    
      return rawPoints.map((p) => PatrolPoint(...)).toList();
    }
    
    // 恢復進行中任務時也要修補
    if (patrol != null && patrol.patrolPoints.isEmpty) {
      final fresh = await _loadPatrolPoints();
      if (fresh.isNotEmpty) {
        patrol = patrol.copyWith(patrolPoints: fresh);
        await db.updatePatrolRecord(patrol);
      }
    }

    八、Selenium + Firefox geckodriver 實戰注意事項

    Console Log 不可直接取

    Firefox geckodriver 不支援 driver.get_log('browser')。要捕捉 console 輸出,需要在頁面注入攔截器:

    driver.execute_script("""
        window.__logs = [];
        var orig = console.log;
        console.log = function() {
            window.__logs.push(Array.from(arguments).join(' '));
            orig.apply(console, arguments);
        };
    """)
    # 操作後讀取
    logs = driver.execute_script("return window.__logs")

    但在 release build 中,Flutter 的 debugPrint 不呼叫 console.log,所以這招也沒用。前面提到的 SharedPreferences breadcrumb 才是唯一可靠的方式。

    click_text() helper 的完整實作

    封裝一個通用的「找語意元素並點擊」函式,需要同時搜尋 button、tab、tappable 三種角色:

    def click_text(driver, text, timeout=15):
        """Click flt-semantics element whose innerText contains text."""
        end = time.time() + timeout
        while time.time() < end:
            selectors = [
                "flt-semantics[role='button']",
                "flt-semantics[role='tab']",
                "flt-semantics[flt-tappable]",
            ]
            for sel in selectors:
                for el in driver.find_elements(By.CSS_SELECTOR, sel):
                    t = driver.execute_script("return arguments[0].innerText", el) or ""
                    if text in t:
                        driver.execute_script("arguments[0].click()", el)
                        return
            time.sleep(0.5)
        raise AssertionError(f"Clickable element '{text}' not found")

    九、方法論:Flutter Web Debug 的正確排查流程

    當 Selenium 測試與 Flutter Web 出現異常時,依照以下順序排查,可以最快定位問題:

    1. 語意樹是否啟動?按 Tab 後檢查 flt-semantics 元素數量。為 0 → 重按 Tab
    2. localStorage 狀態正確嗎?檢查 flutter.* key,確認 token、快取資料是否存在
    3. HTTP 還是 HTTPS?相機、Service Worker、Web Crypto 都需要 Secure Context
    4. Dialog 回傳值正確嗎?用 dialog 內部的 context 而非外層 context
    5. Release 還是 Debug build?debugPrint 在 release 完全靜默
    6. 寫 debug breadcrumb:try/catch 裡寫 SharedPreferences,Selenium 輪詢 localStorage
    7. SPA 狀態殘留?用 full HTTP reload(無 hash URL)強制重置 Flutter widget tree

    總結:Flutter Web + Selenium 是可行的,但需要正確的心智模型

    Flutter Web 的測試難度不在於「找不到元素」,而在於「找到了但行為不符預期」。Canvas 渲染 + 語意覆層的架構與傳統 HTML DOM 測試完全不同,需要建立新的心智模型。最大的兩個坑——BuildContext 跨 async 靜默失敗release build debugPrint 消失——可以讓你花上數小時 debug 而沒有任何錯誤訊息。

    掌握了這九個教訓後,我們的 Selenium 測試從 0 做到 40/40 全過,涵蓋了登入、導航、簽到/簽退、巡邏流程、設定頁面等完整 E2E 場景。希望這篇記錄能幫到正在走同一條路的開發者。

  • iDempiere + LangGraph:為 15 年老 ERP 加上 AI 問答的完整紀錄

    重點摘要

    • 用 LangGraph + Claude Sonnet + Groq Llama 為 15 年老 ERP 系統加上 AI 問答功能,不改任何一行既有程式碼
    • 從設計到上線跑通:13 輪審查、20+ 個 AI 專家、發明了「領域腦」知識管理系統、踩了 30+ 個坑
    • 最大的教訓不是技術——是「經驗存在但沒被用到」。叫 20 個專家 review 不如先讀一遍上次的踩坑紀錄
    • 完整開源:AI Assistant + Domain Brain(領域腦知識管理系統)

    這篇文章記錄一個完整的旅程:從「我想讓老 ERP 系統能用 AI 回答問題」到「真的在 iDempiere 裡輸入問題、6.8 秒後看到 Claude 的回答」。過程中我們設計了架構、寫了計畫、做了 13 輪審查、發現了「領域腦」這個知識管理方法、踩了 30 多個坑、讓兩個不同的 AI(Claude 和 Qwen)協作開發——最後真的跑通了。

    最終成果:一張截圖說明一切

    ** === AI Assistant Response ===
    Question: 我想查詢訂單
    Answer: 很抱歉,目前沒有找到任何訂單資料。建議您提供特定的訂單編號...
    Model: sonnet
    Tokens: 705
    Time: 6864 ms
    Query: order_status_by_documentno

    這代表什麼?整條鏈路全部打通了:使用者在 iDempiere 輸入問題 → Java Plugin 用 HMAC 簽名 → HTTP 打到 Python → LangGraph 分類問題 → 選對了 SQL → 查了 PostgreSQL → PII 脫敏 → Claude Sonnet 回答 → 脫敏還原 → 顯示在 iDempiere UI。6.8 秒,705 tokens,沒有改 iDempiere 任何一行既有程式碼。

    架構:支援老系統,不重寫老系統

    核心理念:iDempiere 是 15 年的 Java ERP,我們不動它,只在旁邊加一個 Python 微服務。

    iDempiere (Java/OSGi)                    Python AI Service (FastAPI)
    ┌──────────────────────┐                 ┌──────────────────────────┐
    │ AI Chat Process      │  HTTP POST      │ HMAC 驗證                │
    │ HMAC 簽名            │ ──────────────→ │ LangGraph 分類 (Llama 8B)│
    │ 審計日誌              │                 │ 選擇預定義 SQL            │
    │                      │ ←────────────── │ PostgreSQL 查詢 (只讀)    │
    │ 顯示回答              │  JSON 回應      │ PII 脫敏 → Sonnet → 還原  │
    └──────────────────────┘                 └──────────────────────────┘

    這個架構的好處:Python service 掛了,ERP 完全不受影響。要換 LLM 模型?改 Python 一行。要加新的查詢?加一個 SQL 定義檔,Java 端不用動。

    開發過程:兩個 AI 協作,一個審查一個寫碼

    這個專案的開發方式很特別:Claude(我)負責設計、審查、知識管理;Qwen 負責寫程式碼。

    角色 AI 工作
    架構師 + 審查員 Claude Opus 設計 spec、寫 plan、派專家 review、建 Domain Brain、debug 部署問題
    程式實作 Qwen Python service 全部程式碼 + Java plugin 全部程式碼
    指揮官 Tom(人類) 定需求、判斷方向、提出「你有沒有去看上次的紀錄?」這種靈魂拷問

    13 輪審查學到的事

    我們做了 13 輪 review,派了 20 多個 AI 專家 agent。前 8 輪查邏輯、安全、架構、接點——都通過了。然後 Tom 問了一句:「你有沒有去看 tw-invoice 上次踩的坑?」

    答案是沒有。然後我們發現 3 個會直接讓 plugin 啟動失敗的 bug,全部都是上次踩過且記錄過的。20 個專家沒抓到,一句「去看舊筆記」就全找到了。

    這件事催生了一篇完整的反思文章和一個全新的知識管理系統——Domain Brain(領域腦知識管理系統)。

    踩的最痛的幾個坑

    痛點 教訓
    JVM 參數加在 idempiere.ini systemd 啟動不吃 ini,要加在 server.sh 先搞清楚服務怎麼啟動的
    2Pack XML 格式錯 Para 要嵌套在 Process 裡、要 type=table、reference=uuid 看 tw-invoice 的 working example 比看文件有用
    AD_Menu_ID=146 不存在 menu ID 是環境特有的,不能 hardcode 用 UUID reference
    ad_menu_access 表不存在 iDempiere 根本沒有這張表 不要假設表存在,先查
    缺 IProcessFactory DefaultProcessFactory 用 Class.forName,看不到 plugin 每個 SvrProcess 都需要自己的 Factory

    Domain Brain:解決「經驗不傳承」的方法

    這個專案最大的副產品是 Domain Brain — 一個把所有專案經驗按技術領域濃萃的知識管理系統。詳細的介紹在前一篇文章,這裡只講結果:

    • 9 份領域腦,涵蓋 OSGi、2Pack、PO Model、REST API、Python LLM、Crawler、回測、OMS、設計原則
    • 每個專案的 CLAUDE.md 宣告自己需要哪些腦:## Domain Brain: osgi-bundle, 2pack, po-model
    • 審查時帶著腦 → 第一輪就抓到之前 8 輪沒抓到的 bug
    • 新坑自動更新回腦 → 所有未來專案受益

    技術棧

    技術
    ERP UI iDempiere 12 + ZK + OSGi Plugin
    AI 路由 LangGraph StateGraph(分類 → 選 SQL → 查詢 → 脫敏 → 回答 → 還原)
    LLM Claude Sonnet(查詢選擇 + 回答) + Groq Llama 8B(分類)
    安全 HMAC-SHA256 簽名、PII 可逆脫敏 [PII_C_001]、只讀 DB 帳號、statement_timeout
    資料庫 PostgreSQL(iDempiere DB),ai_readonly 帳號,ThreadedConnectionPool

    開源

    下一步

    • 從 Process 對話框升級為 ZK Form 聊天窗(更好的 UX)
    • 加入 AI_ChatLog 審計表(追蹤每次問答)
    • 更多預定義 SQL(目前 3 個,目標 20+)
    • 對話歷史(Phase 2)
    • 有限的寫入操作——透過 iDempiere API,不是直接 SQL
  • 叫了 20 個 AI 專家 Review,最致命的 Bug 卻是「沒讀上次的筆記」

    重點摘要

    • 用 AI 派了 20 個專家跑了 7 輪 review,查了上百個檢查點,結果最致命的 bug 是「沒有去看上次踩過的坑」
    • 問題不是 AI 不夠聰明,而是 AI 沒有主動讀已有的經驗文件就開始寫新計畫
    • 解法不是叫更多專家,而是建立「做特定事之前必讀的 checklist」並且寫進記憶系統
    • AI 和人一樣:知識存在 ≠ 知識會被用到。差距在於流程,不在於能力

    這篇文章記錄一個讓我很不高興的經驗:我用 Claude Code 設計一個 iDempiere AI 助手系統,前後叫了 20 個 AI 專家 agent 做了 7 輪 review,查了上百個技術檢查點——結果最致命的 bug,不是什麼深奧的技術問題,而是「沒有去讀上次開發同類型 plugin 時寫下的踩坑紀錄」

    這件事讓我思考一個更根本的問題:我到底該怎麼跟 AI 協作,才能讓它真正用到已有的經驗?

    發生了什麼事?

    我在開發一個 iDempiere ERP 的 AI 問答助手。這個系統分成兩部分:Java 的 iDempiere Plugin(前端 UI + 權限 + 審計日誌)和 Python 的 FastAPI 服務(AI 路由 + PII 脫敏 + LLM 呼叫)。

    在寫 Plugin 的計畫之前,我已經有一個完整的 iDempiere plugin 開發經驗——台灣統一發票系統 tw-invoice。那個專案踩了超過 24 個坑,每一個都花了我好幾個小時 debug,而且全部記錄在 CLAUDE.md 裡

    但是當 Claude 開始寫 AI 助手的 Plugin 計畫時,它完全沒有去讀那份文件。它是從「一般 iDempiere 知識」出發寫的,而不是從「我們一起踩過的坑」出發。

    7 輪 review 查了什麼?漏了什麼?

    輪次 專家數 查了什麼 找到什麼
    R1 3 元件設計(iDempiere/Python/Security) 12 個修正(HMAC、PII、async)
    R2 1 驗證 code 有更新 0/12 code 沒改(只改了表格)
    R3 2 接點(Java↔Python↔DB↔LLM) 4 個 CRITICAL(PG schema, pool, HMAC bytes)
    R4 3 架構師 / 開發者 / PM 4 個 BLOCKED(conftest 順序、mock 路徑)
    R5 2 老系統 × 新系統聯合對話 thread pool 會拖垮 ERP、statement_timeout
    R6-R7 6 最終驗證 62+38 個檢查點 全部通過 ✅
    R8-R9 3 我要求去讀 tw-invoice 踩坑紀錄 3 個 P0 — 不修直接不能跑

    你看到問題了嗎?前 7 輪 review 用了 20 個專家 agent,查了上百個檢查點,全部通過。但只有在我「要求 Claude 去讀舊專案的踩坑紀錄」之後,才發現 3 個會直接讓 plugin 無法啟動的致命 bug。

    那 3 個致命 bug 是什麼?

    Bug 後果 tw-invoice 有記錄嗎?
    MANIFEST.MF 缺 org.adempiere.plugin.utils Bundle 無法 resolve,完全不能啟動 ✅ 有,而且踩過
    @Model annotation import 路徑錯 PO model 不被發現,DB 操作全部失效 ✅ 有,而且踩過
    initPO 缺少 tableId 檢查 第一次啟動(2Pack 還沒跑)直接 crash ✅ 有,而且踩過

    三個 bug 都是 tw-invoice 踩過且記錄過的。經驗就躺在那裡,但沒有被讀取。

    問題出在哪?不是 AI 不聰明

    讓我想清楚之後,我發現問題不在 AI 的能力(它確實能找到問題——找到了上百個),而在於AI 和人一樣,「知道」跟「會用」之間有巨大的差距

    三層問題

    1. AI 不知道要去看 — 寫新 plugin 計畫時,它沒有主動去讀 tw-invoice 的 CLAUDE.md。它有能力讀,但沒有觸發「我應該先去看看上次踩了什麼坑」的念頭。
    2. 我也不知道要提醒它 — 我以為「派 20 個專家 review」已經夠全面了。我不知道這些專家不會自動去讀歷史紀錄,除非我明確要求。
    3. 專家 review 的盲點 — 專家只看「這份文件本身有沒有問題」,不會跨專案比對「上次做類似的事踩了什麼坑」。他們審的是邏輯一致性,不是經驗傳承。

    解法:不是更多專家,而是「做事之前的 checklist」

    派再多專家也沒用,如果他們不知道要看哪些歷史紀錄。真正的解法是在開始工作之前,就讓 AI 讀取相關的經驗教訓。

    我最終建立了兩份「跨專案強制 checklist」,存在 Claude 的記憶系統裡:

    記憶檔案 觸發條件 內容
    idempiere-plugin-pitfalls.md 寫任何 iDempiere plugin 之前 MANIFEST.MF 必要 package、2Pack 路徑、@Model import、initPO guard、afterPackIn 模式、部署 SOP
    python-llm-pitfalls.md 寫任何 Python LLM 整合之前 JSON 解析容錯、Groq rate limit、timeout 設定、lazy-init 模式

    這兩份檔案在 MEMORY.md 索引裡標記為 🔴 MANDATORY。每次新對話載入時,AI 會看到這個索引,知道「做 iDempiere plugin 工作之前,先讀 pitfalls 檔案」。

    你該怎麼做?給 AI 使用者的具體建議

    如果你也用 Claude Code(或任何 AI coding assistant)做重複性的專案工作,以下是我的教訓:

    1. 踩坑之後立刻寫進 CLAUDE.md

    不是「之後再整理」,是修完 bug 的那一刻就寫。寫三行就好:什麼坑、為什麼踩到、怎麼修的。這個我有做,tw-invoice 的 CLAUDE.md 記了 24 個坑。問題出在下一步。

    2. 建立跨專案的 pitfalls 記憶(這是我缺的那一步)

    經驗寫在專案 A 的 CLAUDE.md 裡,專案 B 不會自動讀到。你需要把「通用教訓」抽出來,放到 Claude 的記憶系統(~/.claude/projects/memory/),這樣每個新專案都能讀到。

    # MEMORY.md 索引加這一行:
    ## ⚠️ Must-Read Before Specific Work
    - **idempiere-plugin-pitfalls.md** 🔴 MANDATORY — 寫任何 plugin 前必讀

    3. Review 之前,先問「你有沒有讀過上次的紀錄?」

    不要假設 AI 會自動做這件事。它不會。你需要明確說:「先去看 tw-invoice 的 CLAUDE.md 取經,然後再來審這份計畫。」

    4. 專家 review ≠ 經驗傳承

    20 個專家能找到「這份文件本身有沒有邏輯錯誤」,但找不到「上次做類似的事踩了什麼坑」。這兩件事是不同的能力,需要不同的觸發方式。

    • 專家 review:「這份計畫有沒有 bug?」→ 邏輯驗證
    • 經驗傳承:「上次做類似的事踩了什麼坑?」→ 歷史比對

    你需要兩者都做,而且經驗傳承要在 review 之前。否則 review 再怎麼嚴謹,也只是在一個有缺陷的基礎上做驗證。

    AI 協作的本質:知識存在 ≠ 知識被用到

    這次經驗讓我想通一件事:AI 的問題跟人的問題是一樣的

    你的資深工程師也會犯同樣的錯——他上次在專案 A 踩了 10 個坑,寫了筆記,但做專案 B 的時候忘了翻筆記,同樣的坑又踩一次。差別在於人有「直覺」(模糊地記得「好像上次有遇過類似的」),AI 沒有這種模糊記憶。AI 要嘛讀了文件就完美執行,要嘛沒讀文件就完全不知道。

    所以跟 AI 協作的核心不是「讓 AI 更聰明」,而是讓正確的資訊在正確的時間出現在 AI 面前。這是一個資訊流設計問題,不是 AI 能力問題。

    我的 AI 協作框架(修正版)

    開始新專案
        ↓
    1. 讀 MEMORY.md 索引(AI 自動做)
        ↓
    2. 有沒有「Must-Read」標記的 pitfalls 檔案?
       → 有:讀完再動手(AI 必須被觸發)
       → 沒有:判斷是否需要建立一個
        ↓
    3. 讀舊專案的 CLAUDE.md(我要明確要求)
        ↓
    4. 寫計畫(現在才開始)
        ↓
    5. Review(專家驗證邏輯 + 歷史比對)
        ↓
    6. 踩到新坑 → 立刻寫進 CLAUDE.md + 更新 pitfalls 記憶

    關鍵改變:步驟 2 和 3 是我之前跳過的。我以為步驟 5 的 review 會涵蓋一切,但 review 只能驗證邏輯,不能傳承經驗。

    更深的問題:專案爆炸之後,你連「要叫 AI 去看哪裡」都不知道

    我檢查了一下自己的開發環境:42 個資料夾、9 個 iDempiere 相關專案、38 個記憶檔案、8 個專案各有自己的 CLAUDE.md(共 1578 行經驗紀錄)。

    這代表什麼?我已經快到「我自己都不知道我有什麼」的臨界點了。

    這次我還記得「tw-invoice 有踩坑紀錄」所以能叫 AI 去讀。但再過半年呢?再多 10 個專案呢?到時候我連「有一份紀錄存在」都不記得,更不可能叫 AI 去參考。而 AI 自己不會主動翻遍 42 個資料夾找相關經驗。

    這就是Sample → 大系統模式的致命陷阱:

    正常的軟體開發流程:
      做 Sample → 驗證可行 → 嫁接到大系統
    
    加入 AI 協作之後:
      做 Sample → AI 幫你踩坑 → 經驗寫在 Sample 的 CLAUDE.md
      → 做大系統 → AI「不知道」Sample 的經驗存在
      → 同樣的坑再踩一次
      → 你修完寫進大系統的 CLAUDE.md
      → 下一個專案又不知道...
    
    無限循環。

    跟資深用戶合作的隱藏風險

    還有一個我不想承認但必須說的事:跟資深用戶合作,AI 反而更容易犯錯。

    因為你太懂技術,我傾向「快速產出」而不是「慢慢確認」。你一聽就懂的東西,我就跳過解釋直接做。結果跳過的步驟裡,就藏著「你以為我知道、我以為你知道、但其實沒人確認」的盲區。

    如果你是新手,我反而會更謹慎——每一步確認、每個假設驗證。但跟資深用戶合作,雙方都太有信心,踩煞車的人就消失了。

    知識分層:什麼該鎖、什麼該開

    還有一個企業層面的問題:當經驗從「人的腦子」搬到「.md 檔案」,它變得可複製了。新人 clone repo 就能拿到所有踩坑紀錄。這對知識傳承是好事,但對機密控管是風險。

    解法是分層:

    層級 內容 存在哪 被帶走的風險
    公開技術層 CLAUDE.md、架構規則、coding style Git repo 低(跟 source code 等價)
    團隊經驗層 踩坑紀錄、設計文件、SOP Git repo 中(加速競爭對手,但不是核心機密)
    個人記憶層 跨專案 pitfalls、用戶偏好 ~/.claude/(本機) 低(不在 repo 裡,但可手動複製)
    營運機密層 API key、商業邏輯、客戶資料 .env / 公司內部系統 高(必須嚴格管控)

    但現實是:目前沒有任何 AI 開發工具提供這種分層管理。 Claude Code 的記憶系統是平的——所有 .md 檔案放在同一個目錄,沒有權限控制、沒有加密、沒有存取日誌。這是整個產業還沒解決的問題。

    真正需要的:「做特定事之前必須讀什麼」的自動化

    我現在的解法是「手動建立 pitfalls 記憶 + 在 MEMORY.md 標記 MANDATORY」。但這依賴兩件事:

    1. 我記得去標記 — 如果我忘了把新的 pitfalls 抽出來建立跨專案記憶,下次還是會踩坑
    2. AI 會去讀標記 — 目前是靠 MEMORY.md 索引,但沒有強制機制。AI 「應該」讀,但「應該」跟「一定會」之間有差距

    理想的解法是什麼?類似 Git hooks 的機制:

    觸發條件                    → 自動動作
    ─────────────────────────────────────────────
    偵測到 iDempiere plugin 相關工作  → 強制讀取 idempiere-plugin-pitfalls.md
    偵測到 Python LLM 整合          → 強制讀取 python-llm-pitfalls.md
    偵測到新專案建立                → 掃描所有已有專案的 CLAUDE.md,提取相關經驗
    偵測到跟舊專案同類型的工作       → 自動列出「相關專案清單」讓用戶確認

    這個機制目前不存在。Claude Code 有 hooks,但是是 shell command 層級的,不是「語意理解」層級的。它能在 tool call 前後跑 script,但不能理解「這次的工作跟上次的 tw-invoice 是同類型的,應該先去參考」。

    在這個機制出現之前,唯一的防線就是你自己:你必須記得提醒 AI 去讀歷史,而且你必須知道歷史在哪。當你的專案多到你自己都不記得有哪些,這條防線就會失守。

    最終解法:領域腦(Domain Brain)

    經過上面所有的分析,我最終做了一件事:把 42 個專案、1578 行 CLAUDE.md、38 個記憶檔案的經驗,按「技術領域」濃萃成 7 份領域腦

    之前(按專案切,散落各處):
      tw-invoice/CLAUDE.md     → 24 個坑(OSGi + 2Pack + PO + REST 混在一起)
      module-ui/CLAUDE.md      → ZK + REST + 測試(370 行)
      skin-ui/CLAUDE.md        → WAB + Vue + 測試(507 行)
      langgraph-duo/           → Python LLM 整合
      analyst/                 → 爬蟲 + pandas + 回測
      → 你要知道「哪個專案有哪些經驗」才能讓 AI 去讀
    
    之後(按領域切,濃萃在一處):
      brain/idempiere-osgi-bundle.md   ← 所有 OSGi 的坑(來自 4 個專案)
      brain/idempiere-2pack.md         ← 所有 2Pack 的坑
      brain/idempiere-po-model.md      ← 所有 PO Model 的坑
      brain/idempiere-rest-api.md      ← 所有 REST API 的坑
      brain/python-llm-integration.md  ← 所有 LLM 整合的坑
      brain/python-crawler-data.md     ← 所有爬蟲/資料的坑
      brain/design-principles.md       ← 跨語言設計原則
      → 你只需要說「我要做 plugin」,AI 就讀 OSGi + 2Pack + PO 三份腦

    為什麼這比「叫 AI 去看舊專案」好?

    面向 看舊專案 CLAUDE.md 領域腦
    你需要記得什麼 哪個專案跟現在的相關 只需要知道「我在做什麼類型的事」
    新專案踩了新坑 寫進該專案的 CLAUDE.md 萃取到對應的領域腦(所有未來專案受益)
    專案 B 比專案 A 先做完 A 不知道 B 的經驗 B 的經驗已在領域腦,A 自動受益
    專案數量爆炸 越多越容易漏 領域腦數量固定(技術領域有限)
    AI 專家 review 每次從零開始 站在所有歷史經驗之上審查

    最關鍵的一行:領域腦的數量不會隨專案數量增長。你可以有 100 個專案,但「iDempiere OSGi」的領域腦就是一份。新經驗加進去,舊經驗不會消失。專案可以刪掉,經驗永遠留著。

    閉環:專家 review 終於有意義了

    之前(斷裂的):
      專家 review → 找到問題 → 修進當前專案 → 下個專案又不知道
                                                  ↑ 斷在這裡
    
    之後(閉環的):
      專家 review(讀領域腦 + 當前文件)
           ↓
      找到問題 → 修進當前專案
               → 同時萃取到對應的領域腦
           ↓
      下個專案開始前讀領域腦
           ↓
      專家 review(讀更新過的領域腦 + 當前文件)
           ↓
      ↻ 經驗循環,不斷累積

    這才是 AI 專家 review 真正有意義的前提:他們站在所有歷史經驗之上做審查,而不是每次都從零開始

    現實的限制

    領域腦不是完美解法。它依然有幾個問題:

    • 萃取是手動的 — 目前沒有工具能自動從 CLAUDE.md 提取教訓並分類到領域腦。我是派 AI agent 讀完所有檔案後人工整理的。
    • 維護需要紀律 — 踩了新坑要記得更新領域腦,不只是寫進專案的 CLAUDE.md。如果忘了這一步,循環又斷了。
    • 領域邊界不總是清楚 — 一個 bug 可能同時涉及 OSGi、2Pack、和 PO Model。要判斷放哪個腦,或者放多份。
    • Token 成本 — 領域腦加起來約 2000-3000 tokens。每次新對話讀取相關的 2-3 份,約 $0.005-$0.015。每月 $5-15,可以接受。

    但即使有這些限制,領域腦依然比「靠人記得哪個專案有哪些經驗」好太多了。因為人的記憶會隨專案數量退化,領域腦不會

    完整解法:Domain Brain 宣告 + fix: 驅動更新

    經過不斷推敲,最終方案有三個核心機制:

    機制一:每個專案用一行宣告自己需要哪些腦

    # 每個專案的 CLAUDE.md 開頭加一行:
    
    idempiere-tw-ai-assistant/CLAUDE.md:
      ## Domain Brain: osgi-bundle, 2pack, po-model, python-llm-integration
    
    analyst/CLAUDE.md:
      ## Domain Brain: python-crawler-data, design-principles
    
    新專案/CLAUDE.md:
      ## Domain Brain: python-crawler-data, design-principles

    為什麼不用資料夾名稱比對?因為 analyst/ 裡有爬蟲也有 API 也有 SQLAlchemy——資料夾名稱不等於技術領域。為什麼不用關鍵字比對?因為「API」出現在 iDempiere REST、Groq LLM、爬蟲、自己的 FastAPI 四種 context 裡,關鍵字比對直接崩潰。

    讓專案自己宣告是最可靠的——你看得到、可以改、一行字。AI 讀到 CLAUDE.md 就知道要載入哪些腦,不用猜。

    機制二:fix: commit 驅動更新

    新經驗怎麼回到領域腦?不是靠事後整理,而是靠 fix: commit 當觸發點:

    每次 AI 寫出 fix: 開頭的 commit message:
      1. STOP — 不要急著做下一個 task
      2. 問自己:「這個 fix 會不會在其他專案也發生?」
      3. 是 → 當場更新對應的領域腦(不是之後,是現在)
      4. 領域腦更新後,所有未來專案的 review 都能受益

    機制三:專家 review 帶著腦

    派專家 review 時:
      1. 專家讀該專案的 CLAUDE.md → 看到 Domain Brain 宣告
      2. 專家讀對應的腦 → 帶著所有歷史 bug 經驗
      3. 審查當前文件 → 站在經驗之上,不是從零開始
      4. 找到新問題 → 修完 → 更新腦
      5. 下一個專案的專家 → 拿到更新過的腦
      ↻ 循環

    三個機制合在一起的效果

    你要做的事 AI 自動做的事
    新專案加一行 Domain Brain(6 個字) 讀對應的腦、帶著經驗開始工作
    不需要做任何事 fix: commit 時自動判斷是否更新腦
    說「派專家審查」 專家帶著最新的腦去審查
    偶爾說「把這個更新到腦」 當場更新,所有未來專案受益

    還是不完美的地方

    • 你自己 debug 沒跟 AI 說的坑 — AI 不知道,無法更新腦。你得養成習慣說一句「把這個更新到腦」
    • 其他同事的經驗 — 除非他們也更新領域腦,否則知識在他們腦子裡消失
    • 新領域出現 — 7 份腦不夠用了(比如加了 DevOps 或 mobile)→ 建新的腦檔案
    • AI 判斷 fix: 是否該更新腦 — 還是靠判斷,可能漏。但比「完全沒有機制」好太多

    結語

    叫再多專家進來 review,如果他們不知道要看歷史紀錄,就跟你請了 20 個新員工來審查、但不給他們看前任的交接文件一樣。當你的專案多到連自己都記不清有哪些,而 AI 又不會主動翻遍你的 42 個資料夾找經驗——這時候你需要的不是更聰明的 AI,而是一個能自動把經驗送到 AI 面前的系統。領域腦不是完美的系統,但它把「靠人記住 42 個專案的經驗」變成「靠 7 份按領域整理的文件」。專案會越來越多,但技術領域是有限的。這就是為什麼領域腦能 scale,而按專案管理經驗不能。

    跟 AI 協作的真正技巧不是「讓 AI 更聰明」或「叫更多 agent」,而是設計一個流程,讓正確的經驗在正確的時間被讀取。這聽起來很簡單,但直到你踩了同一個坑兩次,你才會真正理解為什麼需要這麼做。

    相關閱讀:iDempiere Plugin 開發完整指南:踩遍台灣統一發票的 10 個坑 | LangGraph 多模型實戰:從零到 Production 的完整教學 | Agent Team 穩定的關鍵:spawn 之前先建好兩份文

  • Agent Team 穩定的關鍵:spawn 之前先建好兩份文件

    重點摘要

    • Agent Team 不穩定的根本原因:agent 靠對話記憶工作,不靠文件
    • 解法:spawn agents 之前,必須先建好 CLAUDE.md 和 AGENTS.md
    • CLAUDE.md 寫專案現況,AGENTS.md 寫團隊規則,缺一不可
    • Agent 之間的工作交接必須透過實體檔案,不能靠口頭傳遞

    同樣是用 Claude Code 跑 Agent Team,有人的 team 順暢完成、互動極少,有人的 team 一直卡住、不斷要人介入。

    差距不在任務複雜度,不在模型,在一件事:有沒有在 spawn agents 之前先建好文件。

    為什麼 Agent Team 會卡住

    要理解這個問題,先理解 agent 的本質。

    當你 spawn 一個 agent,它只知道你在那一刻的 prompt 裡說了什麼。你的對話歷史、你之前說的規則、其他 agent 做了什麼——它全都不知道。

    這代表什麼?

    如果你沒有把規則寫進文件,你(orchestrator)就是整個 team 唯一的記憶體。你要記住所有規則,要在每個 spawn prompt 裡正確地說一遍,要把 agent A 的結果正確地轉述給 agent B。

    這就是卡住的來源:

    • Prompt 寫漏一條規則 → agent 做出不符合期望的結果
    • Agent A 的結果透過我轉述給 Agent B → 轉述過程中遺漏細節
    • 對話太長,舊的 context 被壓縮 → 規則消失
    • 某個 agent 失敗重啟 → 什麼都不記得,要重頭說
    • 多個 agent 平行跑 → 每個人收到的規則說法略有不同

    每一個都是可能的失敗點。越複雜的 team,失敗的機率越高。

    讓 Team 穩定的解法:兩份文件

    穩定的 Agent Team 做一件事:把所有 agent 需要知道的東西,從對話記憶移到磁碟上的文件。

    文件是客觀存在的。所有 agent 讀同一份,規則永遠一致。Agent 失敗重啟,讀一遍文件就恢復。多個 agent 平行跑,各自讀文件,不需要我轉述。

    需要兩份文件,職責不同:

    文件 寫什麼 類比
    CLAUDE.md專案現況:ID、路徑、已完成的項目、已知問題、版本新人入職的專案交接文件
    AGENTS.md團隊規則:誰做什麼、如何交接、鐵律、失敗怎麼處理公司的工作手冊

    CLAUDE.md 要寫什麼

    寫所有「agent 每次都要重新查,但其實不需要查」的東西:

    # 專案名稱
    
    ## 關鍵 ID 和路徑
    - WordPress 分類 ID:失智照顧=76、家屬心聲=78
    - 已發布文章:[Post ID 清單]
    - 輸出目錄:./content/drafts/
    
    ## 技術環境
    - 使用版本:XXX
    - API endpoint:[測試] / [正式]
    
    ## 已知的坑
    - 台灣失智症協會網站用 http:// 不支援 https
    - 這個 API 的日期格式是 YYYYMMDD 不是 ISO 8601
    
    ## 已完成 / 待處理
    - ✅ 已完成:XXX
    - ⚠️ 待處理:YYY

    沒有 CLAUDE.md,agent 每次都要重新查分類 ID、確認文章有沒有發過、試連結通不通。每一步都是潛在的失敗點。

    AGENTS.md 要寫什麼

    AGENTS.md 有四個必要部分:

    1. 鐵律(所有 agent 不可違反)

    ## 鐵律
    - 所有醫療資訊必須附上可驗證的來源 URL
    - 不能修改 iDempiere core 代碼,只能在 plugin 層擴充
    - 沒有測試的代碼不算完成

    2. 每個 agent 的定義

    ### researcher(研究員)
    職責:搜尋資料,每筆資訊必須記錄來源 URL
    工具:WebSearch, WebFetch, Read
    輸出格式:[明確定義]

    3. 交接協議(最關鍵、最常被忽略)

    ## 交接協議
    researcher 完成 → 存到 ./drafts/research-[topic]-[YYYYMMDD].md
    writer 開始前  → 必須讀取上面那個檔案
    writer 完成   → 存到 ./drafts/article-[topic]-[YYYYMMDD].md
    publisher 開始前 → 讀取 article 檔案,驗證 References 後才發布

    4. 失敗處理規則

    ## 失敗處理
    - 找不到可信來源:停止,回報「無法找到符合鐵律的來源」,等待指示
    - 需求不清楚:列出疑問,等確認後再開始,不要自行假設
    - 任何 agent:遇到不確定的事,停下來問,不要猜

    具體案例:iDempiere 台灣統一發票 Plugin

    用一個真實場景說明這套做法。假設要用 Agent Team 開發一個 iDempiere 的台灣統一發票 plugin,team 成員是 PM、RD、架構師。

    CLAUDE.md(專案現況)

    # iDempiere 統一發票 Plugin
    
    ## 技術環境
    - iDempiere 版本:11.0,Java 17
    - Plugin 目錄:/path/to/plugin
    - 財政部電子發票規格書版本:5.0(2025年)
    
    ## 已知 iDempiere 約束
    - Callout 用 @Callout annotation(見 idempiere-callout-generator skill)
    - 不能用 Spring,只能用 OSGi service
    - DB 操作只能透過 PO 或 DB class,不能直接 JDBC
    
    ## 已完成的模組
    - ✅ 發票開立
    - ⚠️ 作廢(待測試)
    - ❌ 查詢(未開始)

    AGENTS.md 的交接協議

    ## 新功能開發流程
    
    pm 寫需求 → 存到 ./specs/req-[feature].md
        ↓
    architect 設計 → 讀 req 檔案 → 存到 ./specs/arch-[feature].md
        ↓
    rd 實作 → 讀 req + arch 檔案 → 代碼 + ./specs/impl-[feature].md
        ↓
    architect review → 讀 impl 摘要 → 存到 ./reviews/review-[feature].md

    每個 agent 知道自己要讀什麼、存到哪裡。PM 和 RD 不需要「對話」,他們透過檔案交接。Architect 不需要等 PM 說完才知道需求,直接讀需求檔案。

    每次 spawn agent 的啟動句

    請先閱讀 CLAUDE.md 和 AGENTS.md,
    確認你的角色、鐵律和交接路徑後再開始工作。

    這一句話讓 agent 在開始工作前自己去讀規則,不需要我每次重複說一遍。

    不穩定 vs 穩定:對照表

    沒有文件(常見做法) 有文件(穩定做法)
    規則從哪來我的 prompt(每次可能不同)AGENTS.md(永遠一致)
    專案狀態我的記憶(可能過時或漏掉)CLAUDE.md(客觀存在)
    Agent 間交接我轉述(容易漏細節)實體檔案(完整保留)
    Agent 失敗重啟什麼都不記得讀文件即恢復
    平行跑多個 agent規則可能不一致讀同一份文件,完全一致
    需要人工介入頻繁只在真正需要決策時

    標準流程:每次建立 Agent Team 前

    1. 建立 CLAUDE.md:寫入專案現況(ID、路徑、已知問題、版本、已完成項目)
    2. 建立 AGENTS.md:寫入鐵律、每個 agent 的定義、交接協議、失敗處理規則
    3. Spawn agent 時第一句:「請先閱讀 CLAUDE.md 和 AGENTS.md,確認規則後再開始」
    4. 交接一律用實體檔案:agent 完成後存到指定路徑,下一個 agent 從那裡讀

    沒有做完這四步就開始 spawn,你就是在用對話記憶撐整個 team。任務越複雜,遲早會卡住。

    常見問題

    Q:簡單的任務也需要這兩份文件嗎?

    一個 agent 做一件事,不需要。兩個以上的 agent 有交接,就需要。判斷標準很簡單:如果你需要「把 A 做完的東西交給 B」,就要用文件定義這個交接。

    Q:CLAUDE.md 和 AGENTS.md 要多詳細?

    CLAUDE.md:詳細到「新加入的 agent 不需要問任何問題就能知道專案現況」。AGENTS.md:詳細到「每個 agent 知道自己的輸出要存到哪個路徑」。最常被忽略的就是交接路徑,這是 team 失敗最常見的原因。

    Q:文件要每次重寫嗎?

    AGENTS.md 的團隊結構通常固定,一次寫好後很少改。CLAUDE.md 的專案狀態會變,每次任務完成後更新「已完成項目」。把更新 CLAUDE.md 當作任務完成的一部分,下次 team 啟動時文件就是最新的。

  • 舊系統整合場景下,會用 vs 不會用 Claude Code 的差距

    重點摘要

    • 舊系統整合最大的陷阱:Claude 看不到舊系統,但舊系統的約束決定了新功能能不能用
    • 不會用的人:讓 Claude 在沒有舊系統上下文的情況下做新功能,結果接不上去
    • 會用的人:先讓 Claude 讀關鍵接口,CLAUDE.md 記錄現有約束,設計文件定義接合點
    • 三個場景示範:醫療 HIS 接 LINE 掛號、舊報表接新數據、舊 ERP 接電商平台

    上一篇文章講的是新功能開發。但現實是,大多數人面對的不是一張白紙,而是一個已經在跑的舊系統。

    舊系統整合比全新開發難十倍,不是因為技術更難,而是因為有一大堆隱性約束 Claude 不知道。格式、命名、邊界、不能動的地方,這些都在舊代碼裡,Claude 看不到就無從遵守。

    這篇用三個場景直接模擬:有舊系統在的情況下,會用和不會用 Claude Code 的差距。

    根本差距:Claude 的上下文只有你給它的部分

    Claude Code 非常聰明,但它只知道你告訴它的東西。在全新專案,你說什麼格式就用什麼格式,問題不大。在整合舊系統時,如果你沒有把舊系統的關鍵結構告訴它,它會做出一個邏輯正確但無法接上的東西。

    這不是 Claude 的問題,是你的輸入不完整。

    舊系統整合的核心挑戰是:讓 Claude 在動手之前,先理解它不能動的邊界在哪裡。

    場景一:醫院 HIS 系統加掛 LINE 預約掛號

    情境

    一家地區醫院用了十年的 HIS 系統(Windows Server + MSSQL),所有掛號邏輯都在 stored procedures 裡。現在要加 LINE Chatbot 讓患者能線上預約,但 HIS 系統不能動,只能從外部透過 API 呼叫它。

    不會用的人怎麼做

    幫我寫一個 LINE Chatbot 預約掛號系統,要能讓患者選科別、選醫師、選時段。

    Claude 做出一個完整的 LINE bot,資料庫設計清楚,對話流程順暢。

    開始對接 HIS 系統時,問題一個接一個:

    • HIS 的患者 ID 是 8 位數字,Claude 設計的是 UUID — 整個 primary key 要換
    • HIS 的診次代碼格式是 YYYYMMDD-科別碼-序號(例如 20260325-INT-001),Claude 自己設計了完全不同的格式
    • HIS 只接受 stored procedure 呼叫,不開放直接讀表,Claude 設計的是直接 SELECT
    • 科別代碼是 HIS 裡的維護資料(內科=INT、外科=SUR),Claude 用了自己的命名

    每一個問題單獨看都能修,但修完之後發現下一個格式又不對。最後花了兩天在做格式轉換,而不是做功能。

    結果:開發 3 天,對接 2 天,還有格式轉換層要長期維護。

    會用的人怎麼做

    第一步:先讓 Claude 讀懂舊系統的接口

    把 HIS 系統對外開放的 SP 簽名整理成文件,餵給 Claude:

    請先閱讀以下 HIS 系統的接口文件,
    告訴我你對這個系統的理解,特別是資料格式和呼叫限制,
    再討論 LINE bot 的架構設計。
    
    --- HIS 接口文件 ---
    sp_GetAvailableSessions
      @DeptCode NCHAR(3)      -- 科別碼,參照 tb_Dept.DeptCode
      @DateFrom NCHAR(8)      -- YYYYMMDD 格式
      @DateTo   NCHAR(8)
      回傳: SessionId NCHAR(16), DoctorName, SessionDate, RemainSlots
    
    sp_CreateBooking
      @PatientId NCHAR(8)     -- 8位數字,不足補0
      @SessionId NCHAR(16)    -- 從 sp_GetAvailableSessions 取得
      @Phone     NVARCHAR(20)
      回傳: BookingNo NCHAR(12), Status (SUCCESS/FULL/DUPLICATE)
    
    sp_CancelBooking
      @BookingNo NCHAR(12)
      @Reason    NVARCHAR(100)
    ---

    第二步:CLAUDE.md 記錄現有系統的約束

    ## 整合約束(HIS 系統,不可更動)
    - PatientId:8 位數字字串,不足補 0(例如 "00012345")
    - SessionId:格式為 YYYYMMDD-DeptCode-NNN(例如 "20260325-INT-001")
    - 所有 HIS 呼叫只能透過 stored procedure,不允許直接查表
    - 科別代碼參照 tb_Dept,常用:INT=內科、SUR=外科、PED=小兒科
    
    ## 新系統原則
    - LINE bot 層只做對話邏輯
    - HIS 接口層做格式轉換(HisAdapter class)
    - 不在 LINE bot 層直接呼叫 HIS

    第三步:設計文件定義接合點,不是重新設計格式

    # 功能:LINE 掛號 → HIS 預約對接
    
    ## 接合點(Integration Points)
    LINE 用戶選擇診次 → HisAdapter.getAvailableSessions(deptCode, dateRange)
      → 呼叫 sp_GetAvailableSessions
      → 回傳格式轉為 LINE flex message 可用的結構
    
    用戶確認掛號 → HisAdapter.createBooking(lineUserId, sessionId, phone)
      → 查詢或建立患者檔(PatientId)
      → 呼叫 sp_CreateBooking
      → 處理 FULL / DUPLICATE 回傳狀態
    
    ## 不碰的東西
    - HIS 資料庫 schema 完全不動
    - 所有 PatientId 維持 8 位補零格式
    - SessionId 格式完全繼承 HIS
    
    ## Done When
    - HisAdapter 有完整的 unit test(mock SP 回傳)
    - LINE bot 不包含任何 HIS 格式邏輯(全在 Adapter)

    結果:1.5 天完成,無格式轉換層,後續維護只在 HisAdapter 這一層。

    場景二:舊版股市報表腳本接新即時數據

    情境

    一個量化分析師用了三年的 Python 腳本,每天手動下載 CSV,跑一堆計算,輸出報表。現在要改成自動化:自動爬取數據、自動計算、推播到 Line Notify。但舊腳本的計算邏輯非常複雜(含自訂指標、過去三年調整過的參數),不能改,只能把數據來源換掉。

    不會用的人怎麼做

    幫我把這個股市分析腳本改成自動化,自動抓數據然後推 LINE 通知。

    Claude 看了舊腳本,做了一個新的自動化版本。看起來很整齊,比舊腳本乾淨很多。

    跑了一週,發現結果跟舊版不一樣:

    • 舊腳本的 RSI 計算用的是 Wilder 平滑法,Claude 預設用了 SMA 版本,數值不同
    • 舊腳本對成交量有一個「過去 20 日剔除最高最低各兩天後的平均」的自訂邏輯,新版沒有
    • 舊腳本在除權息日前後有特別處理,新版沒有
    • 欄位名稱被 Claude 重新命名了(舊版 vol_adj 在新版變成 adjusted_volume),下游所有 Excel 公式全壞

    分析師說:「它幫我重寫了,但重寫出來的東西跟我的不一樣,我現在不知道以哪個為準。」

    結果:新舊結果不一致,花了一週在驗算差異,反而比手動下載多花時間。

    會用的人怎麼做

    關鍵原則:計算邏輯一行都不能動,只換數據來源。

    第一步:讓 Claude 讀懂舊腳本,先提取它的業務邏輯

    請閱讀這個舊腳本,告訴我:
    1. 它依賴哪些輸入欄位(欄位名稱和格式)
    2. 有哪些自訂計算邏輯(非標準指標)
    3. 最後輸出哪些欄位
    
    不要修改任何東西,只告訴我你的理解。

    這一步讓 Claude 自己找出所有隱性依賴,避免後面遺漏。

    第二步:CLAUDE.md 把舊腳本的約束凍結

    ## 舊系統相容性約束(不可更動)
    - 所有輸出欄位名稱必須與 legacy_report.py 完全一致
      (vol_adj、rsi_wilder、price_adj 等,不得重新命名)
    - RSI 計算必須使用 Wilder 平滑法(非 SMA),與舊版等價
    - 成交量平均:去掉最高最低各 2 天後的 16 日均量
    - 除權息調整邏輯:參見 legacy_report.py 第 87-134 行,禁止修改
    
    ## 本次修改範圍
    - 只修改數據來源層(DataFetcher class)
    - 所有計算邏輯保持不變
    - 輸出格式和欄位名稱保持不變

    第三步:設計文件只描述「換什麼」,明確說「不換什麼」

    # 功能:數據來源自動化
    
    ## 要換的
    舊:手動下載 CSV 放在 ./data/ 目錄
    新:DataFetcher 自動從 TWSE API 抓取,存成相同格式的 DataFrame
    
    ## 不換的
    - 所有 calculate_*() 函數:一行都不動
    - 所有欄位名稱
    - 輸出的 Excel 格式和公式
    
    ## 驗證方式
    用同一天的歷史數據,新舊兩版並排執行,
    所有欄位數值差異必須在浮點誤差範圍內(< 0.0001)

    「驗證方式」這一段給了 Claude 一個清楚的完成定義:不是「看起來跑得動」,而是「跟舊版數字一樣」。

    結果:1 天完成,新舊並排驗算通過,分析師信心十足上線。

    場景三:舊訂單系統接新電商平台(Shopee / momo)

    情境

    一家中型品牌商有自己的後台訂單系統(自建,PHP + MySQL,跑了七年),現在要同時開 Shopee 和 momo 的店,訂單要自動回拋到自建系統,庫存要即時同步。自建系統的代碼文件不齊全,但不能大改,只能在外面包一層。

    不會用的人怎麼做

    幫我串接 Shopee 和 momo 的訂單,自動同步到我們自己的系統。

    Claude 寫了一個整合服務,讀 Shopee/momo 的 webhook,轉換格式,打進自建系統的 API。

    測試時發現:

    • 自建系統的商品 SKU 格式是 PRD-XXXXXXXX,但 Shopee 上的 SKU 是當初手動輸入的,有些根本對不上
    • 自建系統的訂單狀態只有 5 種,Shopee 有 12 種,Claude 的對照表做了一半,有幾個狀態沒處理
    • momo 的訂單金額包含平台折扣,自建系統的商品價格是定價,兩邊金額對不上帳
    • 自建系統在創建訂單時會觸發一個庫存扣減的觸發器,Claude 不知道這件事,導致庫存被扣兩次

    最後一個問題最嚴重:庫存被扣兩次,一直到實際出貨才發現。

    結果:開發 4 天,測試又 3 天,上線後還是出現庫存問題。

    會用的人怎麼做

    舊系統不熟,先讓 Claude 幫你挖清楚它的邊界。

    第一步:讓 Claude 讀舊系統,主動找隱性行為

    請閱讀這個訂單系統的代碼,特別注意:
    1. 創建訂單時會觸發哪些副作用(觸發器、事件、其他表的更新)
    2. 庫存扣減在哪裡發生(是 API 層還是資料庫層)
    3. 訂單狀態的完整清單和流轉規則
    
    告訴我所有你發現的隱性行為,不要開始寫任何代碼。

    「隱性行為」這個說法很重要。Claude 在讀舊代碼時會主動找資料庫 trigger、事件監聽器、side effect,這些是最容易被遺漏的整合風險。

    第二步:用 Plan Mode 規劃整合架構,重點在「邊界」

    【背景】
    自建訂單系統(PHP + MySQL),創建訂單時資料庫層會自動扣減庫存(trigger)。
    Shopee 和 momo 各有自己的訂單狀態體系。
    
    【目標】
    Shopee/momo 新訂單自動進到自建系統,庫存只扣一次,狀態對照完整。
    
    【約束條件】
    - 自建系統的 trigger 不能改(沒有完整文件,風險太高)
    - SKU 對照表需要人工確認後再上線(不能用 Claude 猜測)
    - momo 的折扣金額要分開記錄,不能直接入自建系統的商品價
    
    請制定整合架構計劃,
    特別說明如何避免庫存被扣兩次,
    等我確認計劃後再開始實作。

    Plan Mode 裡,Claude 提出了三個方案,推薦的是:新建一個 OrderBridge 服務,只負責格式轉換和狀態對照,在呼叫自建系統 API 之前先把庫存檢查做在 Bridge 層(避免 API 呼叫失敗後 trigger 已執行的問題)。

    第三步:設計文件把 SKU 對照、狀態對照、金額拆分全部定義清楚

    ## SKU 對照策略
    - 對照表存在 sku_mapping 資料表,人工審核後才生效
    - 找不到對照的 SKU:訂單進 pending_review 佇列,不自動處理
    - 禁止猜測或模糊匹配
    
    ## 訂單狀態對照(Shopee → 自建)
    UNPAID        → 不同步(等付款)
    READY_TO_SHIP → processing
    SHIPPED       → shipped
    COMPLETED     → completed
    CANCELLED     → cancelled
    其他狀態      → 記錄 log,不同步,發警報
    
    ## momo 金額處理
    momo_original_price → 自建系統 unit_price
    momo_discount       → 另存 discount_record 資料表
    momo_final_price    → 自建系統 actual_amount
    (三個欄位分開記錄,不做合併計算)

    結果:2 天完成 OrderBridge,庫存零重複扣減,SKU 對照人工審核後上線,穩定運行。

    舊系統整合的核心技巧整理

    技巧 怎麼做 目的
    先讓 Claude 讀現有接口提供 API 簽名、schema、關鍵函數,要求 Claude 說出理解後再動手讓 Claude 在正確的上下文下設計,不做無效假設
    要求 Claude 找隱性行為明確說「找出所有 trigger、side effect、副作用,不要開始寫代碼」在整合前把地雷挖出來,不是做完才踩到
    CLAUDE.md 凍結不能動的邊界在 CLAUDE.md 明確寫「不得修改 X 格式 / Y 欄位名稱 / Z 計算邏輯」Claude 不會因為「更整齊」而擅自重新命名或重構
    設計文件定義接合點,不定義格式設計文件描述「新舊系統在哪裡接觸」,格式繼承舊系統,不重新設計避免做一個格式轉換層長期維護
    驗證方式要對比舊系統Done When 裡明確說「與舊系統同樣輸入,輸出結果必須一致」讓 Claude 自己驗算新舊等價性,不是跑起來就算完成

    一個可以直接用的提示模板

    每次要在舊系統上加新功能,用這個模板啟動:

    【現有系統】
    [描述現有系統的技術棧和關鍵接口,附上接口文件或關鍵代碼片段]
    
    【要加的功能】
    [一句話描述]
    
    【不能動的邊界】
    - [現有系統的格式、欄位名稱、計算邏輯等不能更動的項目]
    - [如果有 DB trigger 或其他隱性行為,也列在這裡]
    
    【請先做這兩件事,再開始設計】
    1. 告訴我你對現有接口的理解(特別是你覺得可能影響整合的部分)
    2. 指出你看到的整合風險(格式衝突、重複操作、狀態對照缺口)
    
    確認理解正確後,我們再討論設計。

    這個模板做了三件事:把舊系統的上下文給 Claude、凍結不能動的邊界、要求 Claude 在動手前先說出它的理解和風險判斷。

    常見問題

    Q:舊系統的代碼很亂,文件也沒有,怎麼辦?

    先讓 Claude 讀代碼,問它「這個系統對外暴露了哪些接口?資料庫有哪些關鍵的 table 和 trigger?」讓 Claude 幫你反向整理出一份接口文件,確認沒有遺漏後再進行整合設計。不要跳過這一步,這是整合成功的前提。

    Q:整合的範圍不確定,不知道要動到哪裡?

    先用 Plan Mode,給 Claude 目標和約束,讓它畫出影響範圍。Plan Mode 的價值在複雜整合場景特別高,因為它會列出所有相關的文件和狀態流,讓你確認範圍是否正確,再決定怎麼切入。

    Q:新功能做完,但舊系統有些邏輯說不清楚,怕 Claude 做錯?

    這種情況用「新舊並排驗算」:先在測試環境讓舊版和新版用同樣輸入各跑一次,比較輸出。在設計文件裡明確寫出這個驗證條件,Claude 就會把「新舊等價」列為完成定義的一部分。

    從不會用到會用:舊系統整合的具體升級路徑

    舊系統整合的升級路徑跟全新開發不太一樣:問題不是「我沒說邊界條件」,而是「Claude 根本不知道舊系統長什麼樣」。所以升級的重點是:在動手前把舊系統的關鍵資訊餵給 Claude

    第一步:今天就能做到(一個句子)

    在你的提示前面加上這段:

    我有一個現有系統,新功能必須跟它相容。
    
    現有系統的關鍵格式:
    [把你知道的接口格式、欄位名稱、資料格式貼在這裡]
    
    新功能不能更動上面這些格式。先告訴我你的理解,再開始設計。

    就算你只知道一部分格式,先寫一部分。有比沒有好。

    醫療 HIS 整合:Level 0 → Level 1

    不會用(Level 0) 初步會用(Level 1)
    幫我串接 HIS 系統做 LINE 掛號(見下方)
    我有一個舊的 HIS 系統(不能修改),需要在外面接一個 LINE 掛號 bot。
    
    HIS 現有接口(Stored Procedure):
    sp_GetAvailableSessions(@DeptCode NCHAR(3), @DateFrom NCHAR(8), @DateTo NCHAR(8))
    sp_CreateBooking(@PatientId NCHAR(8), @SessionId NCHAR(16), @Phone NVARCHAR(20))
      回傳 Status: SUCCESS / FULL / DUPLICATE
    
    格式約束(不能改):
    - PatientId 是 8 位數字字串,不足補 0
    - 所有呼叫只能透過 stored procedure,不能直接查表
    
    請先告訴我:
    1. 你對這個 HIS 接口的理解
    2. 你覺得 LINE bot 和 HIS 之間需要什麼樣的轉換層
    
    確認後再討論架構設計。

    舊報表腳本接新數據:Level 0 → Level 1

    我有一個舊的 Python 分析腳本,計算邏輯不能動,只要換掉數據來源(從手動 CSV 改成自動抓取)。
    
    舊腳本的輸入依賴(這些欄位名稱不能改):
    - date (YYYY-MM-DD)
    - open, high, low, close, volume
    - vol_adj(自訂欄位:去掉最高最低各2天的16日均量)
    
    計算邏輯不能動的原因:
    - RSI 用的是 Wilder 平滑法(非標準 SMA),三年來的報告都是這個版本
    - 改了數值會跟歷史記錄不一致
    
    請先告訴我:
    1. 你理解哪些東西不能動
    2. 你打算怎麼讓新舊版本在同樣輸入下輸出一致的結果
    
    確認後再開始實作數據來源層。

    舊 ERP 接電商平台:Level 0 → Level 1

    我有一個舊的訂單系統(PHP + MySQL),要串接 Shopee 的訂單進來。
    舊系統不能大改,只能在外面包一層。
    
    已知的舊系統行為:
    - 創建訂單時,資料庫層有 trigger 會自動扣庫存
    - 訂單狀態:pending / processing / shipped / completed / cancelled(只有這五種)
    
    Shopee 訂單狀態有 12 種,需要做對照。
    
    我擔心的問題:
    - 庫存被扣兩次(trigger + 外面的 API 都扣)
    - 狀態對照不完整,有些 Shopee 狀態沒有對應的舊系統狀態
    
    請先幫我分析這兩個風險,告訴我你的處理方案,再開始設計架構。

    注意最後一段:把你擔心的問題說出來。這讓 Claude 優先處理你知道有風險的地方,而不是從它認為重要的地方開始。

    第二步:下週可以做到(CLAUDE.md 記錄舊系統約束)

    舊系統整合的 CLAUDE.md 要特別加一個「整合約束」區塊:

    # 整合約束(現有系統,不可更動)
    
    ## [系統名稱] 的格式規範
    - [欄位名稱] 的格式:[說明]
    - [接口規範]:[說明]
    - 禁止直接操作資料庫,只能透過 [API / SP / 特定方法]
    
    ## 已知的隱性行為
    - [觸發器 / 事件 / side effect 描述]
    - 注意:[操作 X] 會同時觸發 [Y],不要重複執行
    
    ## 新功能的邊界
    - 只修改 [Adapter / Bridge / 特定模組],不動舊系統
    - 欄位名稱繼承舊系統,不重新命名

    每次發現一個新的隱性行為(觸發器、計算邏輯、格式特例),就加進這個區塊。它會越來越完整,讓你以後的整合工作越來越省力。

    第三步:一個月後的進化

    進化 A:在開始任何整合前,先讓 Claude 找隱性行為

    請閱讀 [現有系統代碼/文件],找出所有:
    1. 資料庫 trigger 和它的作用
    2. 創建/更新/刪除記錄時的 side effect
    3. 對外暴露的接口(API / SP / 事件)和它們的格式
    
    告訴我你找到的所有隱性行為,不要開始設計,先讓我確認。

    這個步驟在整合開始前把地雷挖出來,比做完後踩到省 10 倍時間。

    進化 B:複雜整合用 Plan Mode,重點讓 Claude 畫出影響範圍

    【現有系統】[描述]
    【目標】[一句話]
    【不能動的邊界】[列清楚]
    
    請制定整合計劃,特別標出:
    - 會影響到的現有功能
    - 每個整合點的風險
    - 我需要在上線前人工驗證的項目
    
    等我確認計劃後再開始實作。

    進化 C:設計文件加「新舊等價性驗證」

    舊系統整合的完成定義,永遠要加這一條:

    ## 驗證方式
    用同一份歷史輸入,新舊兩版並排執行,
    [關鍵輸出欄位] 的結果差異必須在 [可接受範圍] 內。
    新版上線前,提供新舊對比報告。
    階段 做什麼 關鍵句
    Level 0直接說要串接什麼
    Level 1(今天)把舊系統格式和約束說清楚「這些格式不能改,告訴我你的理解再開始」
    Level 2(下週)CLAUDE.md 記錄舊系統約束和隱性行為每次整合後補一條「已知隱性行為」
    Level 3(一個月後)先讓 Claude 挖地雷,再 Plan Mode 確認影響範圍「找出所有隱性行為,不要開始設計」