分類: 🛒 電商 OMS 系統

  • 跟 AI 寫程式的 15 條軟工紀律 — 用一條真實對話從頭拆解

    重點摘要

    • 常聽到「跟 AI 寫程式需要軟工基礎」,但具體是哪些?本文用前一篇 Opus 4.8 Workflow 實測那條真實對話從頭拆,對照 15 條經典軟工紀律
    • 盤點結果:做到 9 條 / 部分做到 1 條 / 沒做 5 條。每條都有對話證據引用,沒做的給可執行 action。
    • 15 條按高 leverage 排序前 5 名:驗證紀律、正交分解、真實基準、focused review、文檔作為下個 session 輸入。這 5 條沒守,其他都白搭。
    • 結論:跟 AI 寫程式需要的不是「新的軟工」,而是把舊軟工套到 stateless / non-deterministic / 訓練截止 / 高並發 4 個 AI 特性上的對應方法。

    為什麼問這題

    「跟 AI 寫程式需要軟工基礎」這句話傳得很廣,但講細節的人少。多數人講出來的不是軟工,是 prompt engineering tricks(怎麼下 prompt、怎麼用 chain-of-thought)— 那叫 LLM 使用技巧,不叫軟工。

    真正的軟工基礎是從 1970 年代 SWEBOK 累積到今天的工程紀律:specification、verification、separation of concerns、observability 那些。問題是這些紀律最初是針對「人寫 code、人 review、人交接」設計的,套到「AI 寫 code、人 review」會不會失效?哪些反而更重要?

    本文不假設,用一條真實對話實證:5/29 我跟 Claude Opus 4.8 跑 Home123 backend 的 109 個 GraphQL resolver authz pattern audit 對照實驗,從頭到尾大約 8 輪對話、~50 分鐘。把這條對話拆解,對照 15 條經典軟工紀律,看真實場景下到底用到了哪些、漏了哪些。

    15 條紀律的分類框架

    從經典軟工教材(《Code Complete》、《Pragmatic Programmer》、SWEBOK Guide)抽出 15 條跟 AI 協作最相關的紀律,分 4 群:

    類別 條目 經典 reference
    核心驗證#1 驗證紀律、#13 根因分析、#7 回顧TDD / Postmortem culture / Code Complete §22
    設計分解#2 正交分解、#8 規格先於實作、#9 權衡分析、#14 錯誤處理哲學Dijkstra SoC / Spec-first / Pragmatic Programmer Ch.4
    過程紀律#3 真實基準、#5 focused review、#6 並行執行、#10 預設驗收標準、#12 預算控管Performance Engineering / Code Review SOP / Agile
    知識持久化#4 文檔作為輸入、#11 可重跑、#15 版本控制ADR / Reproducible Research / Git workflow

    下面逐條拆。每條格式統一:定義 → 經典出處 → 你做了沒 → 證據或補救 → 對 AI 協作的特別意義

    #1 驗證紀律 (Verification Discipline)

    定義:任何宣稱(claim)都要靠可重現的證據才能信。
    經典出處:Steve McConnell《Code Complete》§22 The Twelve-Step Programming Process、TDD 的 Red-Green-Refactor 第一步、Cynefin framework 的 probe-sense-respond。

    本次對話做了沒:✅ 做了,多次

    對話證據:

    「幫我讀書 https://www.anthropic.com/news/claude-opus-4-8」
    → 不接受 AI 憑記憶,要 AI 去 web 抓。

    「今天已經是5/29了 你的日期有問題」
    → 即時校正環境假設,不讓我繼續用錯日期。

    「我正在運作 你看一下」
    → 不接受我講的文字總結,要看 ps / pstree / jsonl 真實 OS 訊號。

    對 AI 協作的特別意義:AI 的訓練資料有 cutoff(我的是 2026 年 1 月)。你問跟 cutoff 之後的事(Opus 4.8 是 5/28 發佈),我用「記憶」回答就是瞎掰 — 而且會用流暢的口氣瞎掰,不像人類會猶豫。強制 AI 查資料這個動作,等於把 AI 從「自信的 LLM」拉回「會用工具的執行者」。這條 baseline 沒守,後面 14 條全變空談,因為起手第一個 claim 就錯了。

    #2 正交分解 (Separation of Concerns)

    定義:一個議題只談一個軸線,軸線之間不混。
    經典出處:Dijkstra 1974《On the role of scientific thought》、Parnas 1972 information hiding、UNIX philosophy 的 “do one thing well”。

    本次對話做了沒:✅ 做了,而且是教科書級。

    對話證據:

    「首先 看起來除了MODEL 還有 EFFORT
    同樣是SONNET 還可以有HIGH XHIGH?
    WORKFLOW 我要怎麼去用?」

    三個正交軸線(Model / Effort / Workflow)分開問。對照組是新手會問「給我最好的設定」— 等於要 AI 替你在多維空間做加總決策,你拿到答案也不知道為什麼。

    對 AI 協作的特別意義:AI 處理 bundled question 會發生兩種失敗:(1) 只回最顯眼那條,其他偷偷漏掉;(2) 強行給一個整合答案,但每個軸線都妥協。你下意識把 3 軸拆開,等於逼 AI 逐個 expose,你才能照自己的 context 做選擇。這對應的軟工原則是「不讓抽象漏掉」(don’t leak the abstraction)的反向應用:你拒絕 AI 把抽象漏掉。

    #3 真實基準 (Representative Benchmarks)

    定義:評估新工具用真實場景,不用 toy example。
    經典出處:John Hennessy / David Patterson《Computer Architecture》§1.8 Fallacies and Pitfalls(benchmark 永遠騙人)、SPEC CPU 為什麼要 update、ML 領域 distribution shift 一整條研究線。

    本次對話做了沒:✅ 做了,而且是本次對話最關鍵的一個動作。

    對話證據:

    「好 你現在用HOME123 專案 做一個測試循環 然後用你的WORKFLOW試試看 記錄下來差異」

    不要 toy 不要 hello-world,直接拿 Home123 的 109 個 production resolver。這個動作直接決定了實驗結論的可信度。

    對 AI 協作的特別意義:80% 的「新 AI 工具評測」文章用合成 case(leetcode-style problems),結論毫無遷移性。Anthropic 自家 4.8 release notes 用的也是 SWE-bench、Terminal-Bench 這種「合成的真實」 — 不是任何一家公司的 production codebase。你直接拿 109 個 real resolver 來測,workflow 暴露出來的問題(主 orchestrator 抓到 synthesis agent 算錯 83 vs 109)在合成 case 上看不到,因為合成 case 沒那麼大、catch 不到 emergent behavior。這個動作的工程價值比你的 prompt 內容更高。

    #4 文檔作為下個 Session 輸入 (Documentation as Next-Session Input)

    定義:寫文件不是給未來的人看,是給未來的 stateless agent 看,作為下次 conversation 的可讀輸入。
    經典出處:Architecture Decision Records (ADR, Michael Nygard 2011)、SREbook 的 runbook 文化、Reproducible Research 運動(Donald Knuth literate programming 的延伸)。

    本次對話做了沒:✅ 做了,而且是主動做。

    對話證據:

    「Ab然後我想請你發一篇文章到wordpress上詳細比對這一次的經驗跟數據還有該怎麼啟用的prompt」

    同時要求三份產出:(A) brain/dynamic-workflows.md(下個 conversation 我會自動讀)、(B) 更新 brain/adaptive-agent-team-staffing.md(舊文件補新知識)、(WordPress 文章 —對人類讀者跟搜尋引擎)。

    對 AI 協作的特別意義:你跟人類同事的會議結論寫成 wiki/Notion,下次他翻過。跟 AI 寫 code 的對話結論寫成 brain file,下次 conversation 的 AI 把它當 first-class context 讀 — 等於把這次 conversation 的腦容量無損傳給下次。一般軟工人甚至沒聽過這個用法(「文件是給 AI 讀的?」),但它是 LLM 時代的 ADR + retrospective 文化合體。沒這層,你每次跟新 conversation 都得從零教一遍,等於每次都 onboarding。

    #5 Focused Review (一次只 review 一條軸線)

    定義:給 code review 的 feedback 一次只挑一條軸線改,不混雜其他要求。
    經典出處:Google Engineering Practices《Code Review Developer Guide》、《The Art of Readable Code》Ch.15、Andy Hunt《Pragmatic Thinking and Learning》Ch.9。

    本次對話做了沒:✅ 做了,而且 6 個字精準命中。

    對話證據:

    「注意好讀性跟比較方式」

    6 個字,2 條軸線,沒夾雜其他要求(沒同時挑錯字、補內容、改標題)。我回去重做的時候不需要 disambiguate「我到底該優先處理哪一條」。新手 reviewer 會給 30 條 mixed feedback,作者改完反而亂七八糟。

    對 AI 協作的特別意義:AI 在 mixed feedback 下會做兩件事:(1) 試圖一次解決所有,結果每條都打折;(2) 自選優先序,但你看不到它怎麼選的。你的 focused feedback 等於把「review reviewer」這層 meta-loop 去掉。對 token 成本也直接有差 — AI 不用先花 token 解析「Tom 到底想我先處理哪條」,直接動工。

    #6 並行/異步執行 (Async Parallel Execution)

    定義:能並行的工作不要序列化等待,結果到再收。
    經典出處:Concurrent programming 整個學門、Amdahl’s law、async/await 在現代語言的普及、Toyota production system 的並行工序設計。

    本次對話做了沒:✅ 做了

    對話證據:

    「我正在運作 你看一下」

    你開另一個 terminal 跑 workflow,沒等我講完就行動。我這邊主 session 同時讀你的 process tree + session jsonl 做即時觀察。兩條軌道平行,中間用 jsonl 落地通訊。

    對 AI 協作的特別意義:跟 AI 對話有個隱形成本叫 cache miss penalty。Claude 的 prompt cache 5 分鐘 TTL,超過就要從零重讀整個 conversation。如果你序列化等(我講完→你看→你跑→等結果→回我),很容易 5 分鐘外。並行化 + 中間用 file system / jsonl 落地通訊,等於把 cache 維持在熱狀態。傳統軟工這條對應的是「不要 block 在 IO 等待」,AI 場景下是「不要 block 在對話等待」。

    #7 回顧 (Retrospective)

    定義:任務完成後不直接進下一個,先回看「what went well / what didn’t」。
    經典出處:Agile retrospective(Scrum 每個 sprint 末必做)、Norm Kerth《Project Retrospectives》、Etsy/Google 的 blameless postmortem 文化。

    本次對話做了沒:✅ 做了,而且是 meta 級 — 你問本篇這題就是 retrospective。

    對話證據:

    「還有 很多人說跟ai寫作需要很多的軟工基礎,不像請你評估一下所謂的軟工基礎在我們所有的循環裡面,我無形中有用到哪一些…因為有一些是我打中很關鍵的點,而你不知道那些是不是軟工基礎」

    這句話本身是回顧:你不滿足於「拿到結果就走」,還要拆解過程、識別 pattern、產生可遷移知識。

    對 AI 協作的特別意義:AI 不會主動 retrospect — 我跑完就等下一個 prompt,沒人觸發我不會自己回頭看「剛剛這條對話我做對了什麼」。retrospective 必須由你發起。但 retrospective 的產出對 AI 特別有價值:它是 #4 文檔作為輸入的最佳 raw material — 直接把回顧結論寫成 brain file,下次 conversation 直接用。傳統 retrospective 是「同個團隊下個 sprint 用」,AI 場景是「同個你下個 conversation 用」。

    #8 規格先於實作 (Spec-First / Specification before Implementation)

    定義:動手寫 code 之前先把「要做什麼」「驗收標準」寫死。
    經典出處:Leslie Lamport《Specifying Systems》、TDD「先寫測試」也是這條的變形、Design by Contract (Bertrand Meyer)、SDD(Spec-Driven Development)的學派。

    本次對話做了沒:✅ 做了,而且是顯式的 4 維度規格。

    對話證據:

    「記錄下來差異 怎麼啟動 有優化那些地方 要做什麼東西 必要是什麼」

    4 個維度寫死:(1) 啟動方式、(2) 優化點、(3) 要做的東西、(4) 必要條件。我後續的 brain file 跟 WordPress 文章兩份產出,結構直接照這 4 維度生。

    對 AI 協作的特別意義:沒給 spec 的 AI 會「自由發揮」,結果是形式上看起來有結構,實際結構是 AI 替你做的選擇,你不一定買單。你給 4 維度等於把結構決定權拿回來,AI 只負責填內容。這條對應的傳統軟工是 PRD/RFC,AI 場景是「在 prompt 裡內嵌驗收 schema」。

    #9 權衡分析 (Trade-off Analysis)

    定義:任何方案都有 cost 跟 benefit,要顯式列出再比較。
    經典出處:Software Architecture 教材必有的 ATAM (Architecture Tradeoff Analysis Method)、Jeff Bezos 的「two-way door / one-way door decisions」、《Pragmatic Programmer》Ch.4「Be a Catalyst for Change」的反向。

    本次對話做了沒:✅ 做了,而且是顯式追問。

    對話證據:本系列你連續問了三個 trade-off 問題:

    「差異你可以跑跑看」(empirical 比較 cost)

    「我想知道Workflow那一個,他現在到底對我的意義是什麼?我看不太出來」(質疑單一方向的 benefit)

    「注意好讀性跟比較方式」(cost = 讀者認知負擔 vs benefit = 完整性)

    對 AI 協作的特別意義:AI 對「該不該做某件事」的默認是 yes — 因為訓練資料裡的「Yes, you should」遠多於「No, don’t」。你「我看不太出來意義」這句逼我從 advocacy 模式切到 honest assessment 模式,實際結論變成「不存它,寫 reference 進 brain 就好」。這條對應的傳統軟工是 design review 裡「這個複雜度真的需要嗎?」的提問。

    #10 預設驗收標準 (Acceptance Criteria Upfront)

    定義:任務開始前先寫死「做到什麼程度算 done」。
    經典出處:Agile user story 的 INVEST criteria、Behavior-Driven Development (BDD) 的 Given-When-Then、Definition of Done 是 Scrum 必備產物。

    本次對話做了沒:🟡 部分做到

    分析:你 #8 給了 4 維度規格,算是 partial acceptance criteria。但缺了「品質門檻」:

    • workflow 跑出來的 report 要達到什麼分類正確率才算可信?
    • baseline 跟 workflow 的差異要大到多少才算「值得換 workflow」?
    • 對話拆解後若 15 條都做到,實質工程效率提升多少才算夠?

    結果就是 — workflow 抓到 12 個 hand-roll,我們默認接受這個數字,沒去 sample 5 個函式人工驗證。如果 workflow 系統性把某類 hybrid 全錯標,我們不會發現。

    該怎麼補:任務開始前加一句「驗收標準」段落。例如本次該寫:

    驗收標準:
    1. 兩邊跑完後,我會手動 sample 5 個 USES_PRELUDE 跟 3 個 HAND_ROLLED 對證據
    2. 如果 baseline 跟 workflow 在這 8 個樣本上有 2 個以上分歧,需逐個澄清
    3. 完整 109 函式都要有 row,缺一個視為失敗

    對 AI 協作的特別意義:AI 沒驗收標準會「看起來完成」(plausible-looking output),但內部可能 systematically 錯。傳統軟工裡 acceptance test 是另一個人寫的,AI 場景下你得自己寫,因為 AI 不會主動跟自己對抗。本次沒守這條的代價:我們得花一篇文章解釋「為什麼信任 workflow 的結果」,而本來只需要 sample-test。

    #11 可重跑 / Idempotency (Reproducible Execution)

    定義:任何過程要可從頭重來,輸入相同則輸出相同(在合理隨機範圍內)。
    經典出處:Make / build system 整個學門、Donald Knuth literate programming、Reproducible Research 運動、Docker / IaC 的根本動機。

    本次對話做了沒:❌ 沒做。最具體的證據是你沒按 s 把 workflow script 存下來

    分析:本次跑了 11 個 Haiku 4.5 平行 audit,產生 146 行 JavaScript orchestration script,結果只存在 session 暫存目錄。如果這次的審計結論被人質疑(例如「12 個 hand_roll 是真的還是 AI 瞎標」),你要重跑驗證沒辦法保證跑出同一份結果 — 因為:

    • 下次跑 Claude 會重新生 script,chunk 切法可能不同
    • Haiku 4.5 即使 temperature 0 也有非 deterministic 因素(MoE routing 隨機)
    • Cache hit 率不同 → 提示空間不同 → 細節結論不同

    該怎麼補:三層防護(從便宜到昂貴):

    1. 最低: 把 script 從 session 暫存目錄 cp 出來歸檔到 brain 或 repo
    2. 中等: 把 script 真的存成 ~/.claude/workflows/<name>.js slash command,雖然本案大概不重跑,但其他 audit 可以 fork
    3. 高保證: 把 audit 結論 + 109 函式分類存成 JSON / CSV,用 schema 驗證,以後重跑只需 diff JSON 不需要重看 markdown

    對 AI 協作的特別意義:AI 的輸出有內建非 determinism(temperature、MoE、context order),這跟傳統 reproducibility 假設(同 input → 同 output)直接衝突。AI 場景的可重跑不能依賴「程式邏輯一樣」,要依賴「中間結果落地」 + 「結果用結構化格式儲存」 + 「下游 verifier 用同 schema 驗」。傳統軟工這條是「build 可重現」,AI 場景是「結論可驗證」。

    #12 預算控管 (Cost / Budget Cap)

    定義:任何運算工作開始前先設天花板,超過自動停。
    經典出處:Cloud computing 的 budget alerts、Kubernetes resource limits、Hadoop / Spark 的 timeout、Stripe 的「circuit breaker」pattern、SREbook §12 effective troubleshooting 的 budget 章節。

    本次對話做了沒:❌ 沒做

    分析:我們跑 workflow 的時候沒設 token budget 或 wall-time cap。實際跑了 11 個 agent、~$6.10 estimated cost、132 秒 wall-time。如果 Claude 寫的 script bug 了 — 例如把 chunk 切成 100 個,可能跑出 100 個 agent、$60 cost、20 分鐘 wall-time。沒任何機制自動阻擋。

    該怎麼補:

    • prompt 裡明寫上限 — 例如「最多派 12 個 agent,單一 agent 最多跑 60 秒」
    • --effort medium 而不是 high 開始,確認 quality 夠才升 effort
    • 跑前先讓 Claude 估算 token cost 跟 agent 數,你 approve 才放跑(workflow 內建這層 approval prompt,但你按 [3] View raw script 之前沒人問你 budget)
    • 對自己設「單條對話 spend 上限」(例如 $10),透過 Claude Code admin page 或 API budget API 強制

    對 AI 協作的特別意義:傳統軟工 budget 是「機器跑爛要錢」,AI 場景下 budget 還包含「AI 寫錯 script 跑很久才發現」的 fail-loud delay。Anthropic 自己在他們 multi-agent research system 的 paper 也警告:multi-agent 用 token 是 single-agent 的 3-10×,Research system 是 ~15×。沒 budget cap 等於放任這個倍率,3am 一覺起來收到 $200 帳單是真實風險。

    #13 根因分析 (Root Cause Analysis)

    定義:遇到問題不停在表象,挖到「為什麼會發生」的最底層。
    經典出處:Toyota 的「Five Whys」、Apollo 13 事故報告、Etsy / Google 的 blameless postmortem template、《The Field Guide to Understanding Human Error》。

    本次對話做了沒:🟡 部分做到,但是 AI 替你做的

    分析:本次 audit 最有價值的發現是「guard role 被 AuthzDecision.IsCommunityWide 排除,迫使 5 個 resolver 各自重 probe 一段相同 SQL」。這是根因分析的成果 — 不停在「這幾個 resolver 沒用 prelude」,而是挖到「為什麼它們不能用」。

    但這是 workflow 的 synthesis agent 替你做的,不是你做的。Baseline 模式下 1 個 agent 沒做出這層,你也沒主動追問「為什麼會有 5 個重複」。如果這次跑 baseline 你會 miss 這個 root cause。

    該怎麼補:不能只靠 AI 替你做。可以加紀律 — 拿到分類結果後,主動問:

    看到 12 個 HAND_ROLLED,我們 ladder 5 個 why:
    - 為什麼這 12 個沒用 prelude? → 各自原因
    - 為什麼它們有共同原因? → 找 pattern
    - 為什麼這個 pattern 沒被早發現? → 流程 gap
    - 為什麼流程沒抓到? → tooling gap
    - 為什麼 tooling 沒設計這層? → 設計時的假設

    對 AI 協作的特別意義:AI 默認停在第一層觀察(「這幾個沒用 prelude」)。要挖根因得明確要求(「列出 root cause」)或結構性逼它(workflow 的獨立 synthesis pass 就是設計來做這個)。傳統軟工這條是 debug 工具,AI 場景是「prompt design」工具 — 在 prompt 裡內嵌 root cause analysis instruction,或設計獨立 verification agent。

    #14 錯誤處理哲學 (Error Handling Philosophy)

    定義:對「事情會出錯」這件事有明確設計姿態 — fail-fast vs fail-silently、retry policy、circuit breaker、graceful degradation。
    經典出處:Erlang 的「let it crash」哲學、《Release It!》Michael Nygard 整本書、Google SREbook §22 addressing cascading failures。

    本次對話做了沒:❌ 沒做

    分析:我們沒任何「workflow 跑到一半失敗了怎麼辦」的計畫:

    • 如果某個 chunk 的 Haiku agent 超時了 → 我們沒設 retry 也沒設 fallback
    • 如果 synthesis agent 算術錯了(這次真的發生了:83 vs 109)→ 我們沒設 verification 步驟,純靠主 orchestrator 主動懷疑
    • 如果 JSON schema 驗證 fail → 不知道會發生什麼,沒測過
    • 如果 workflow runtime 自己 crash → 沒 graceful resume 流程

    該怎麼補:在 prompt 裡加 error handling instruction:

    如果跑到一半發現:
    - 某 chunk 的 agent fail → 標記 SKIPPED,繼續其他,最後 report 哪些 skip
    - synthesis 結果跟 row count 對不上 → 不要直接出 report,先 escalate 給主 orchestrator 重算
    - JSON schema 違反 → 該 row 標 INVALID,繼續其他
    - 整體執行超過 5 分鐘 → 自動 abort,出階段性 report
    
    最後 final report 要明確標示哪些 chunk 是「完整跑完」、哪些是「skipped」、哪些是「fail-and-retried」。

    對 AI 協作的特別意義:AI 預設 fail-silently — 它會生「看起來合理」的內容掩蓋失敗。傳統軟工 fail-fast 是「raise exception 停下來」,AI 場景的 fail-fast 是「標註 INVALID / SKIPPED 而不是瞎掰」。沒設計這條,AI 會「完整交付」一份其實內部有 hole 的報告,你看不出來。本次 workflow synthesis 算 83 是僥倖被主 orchestrator 抓到,如果主 orchestrator 也沒抓,我們就拿錯誤數字寫文章了。

    #15 版本控制紀律 (Version Control Discipline)

    定義:任何重要 artifact 進 git,commit message 寫清楚 why,branch 策略對應 workflow。
    經典出處:Git 整個工具、Conventional Commits 規範、Trunk-based / GitFlow / GitHub Flow 各家 branch 策略、Linus 的 git 設計初衷。

    本次對話做了沒:❌ 沒做。本次產出全部沒進 git。

    分析:這次產出了 4 件 artifact:

    • ~/.claude/projects/-home-tom/memory/brain/dynamic-workflows.md(新建)
    • ~/.claude/projects/-home-tom/memory/brain/adaptive-agent-team-staffing.md(編輯)
    • ~/.claude/projects/-home-tom/memory/MEMORY.md(編輯)
    • WordPress 文章兩篇

    前三個位置實際是 ~/.claude/projects/-home-tom/ — 你有可能沒把它放在 git 控管下,意思是:

    • brain 編輯沒 commit history,半年後想知道「dynamic-workflows.md 是什麼時候加的、為什麼加」沒記錄
    • 如果 brain 不小心被改錯了(例如未來某個 conversation AI 寫壞了),無法 rollback
    • 跨機器同步只能靠 rsync / cloud sync,沒 conflict resolution

    該怎麼補:

    1. cd ~/.claude/projects/-home-tom && git init(如果還沒)
    2. 新 brain 或重大編輯後 commit:git add brain/ MEMORY.md && git commit -m "feat(brain): dynamic-workflows from 2026-05-29 Opus 4.8 test"
    3. WordPress 文章 export markdown 進專屬 repo,或用 wp-cli 串自動 backup
    4. workflow script 改 #11 補救時順便 commit 進 dotfiles repo

    對 AI 協作的特別意義:AI 跨 conversation 是 stateless,brain file 是它的「外部記憶」。外部記憶的版本控管比 code 的還重要,因為你不會看到自己過去 conversation 改了哪些 brain,只有 git diff 告訴你。本次對話我改了 3 個 brain 檔,如果你沒 git 控管,3 個月後你不會記得這幾條條目是 5/29 對話加的還是更早。傳統 git 是 code 的時間機,AI 場景是「我跟 AI 集體記憶的時間機」。

    15 條全表:做了沒 × leverage

    # 紀律 類別 本次 Leverage(高→低)
    1驗證紀律核心驗證★★★★★ 沒守等於沒救
    2正交分解設計分解★★★★★ AI 回答品質直接相關
    3真實基準過程紀律★★★★★ 結論可信度核心
    4文檔作為輸入知識持久化★★★★★ AI 時代特有的紀律
    5Focused review過程紀律★★★★ AI 對 mixed feedback 表現差
    6並行執行過程紀律★★★ 規模大才顯效
    7回顧核心驗證★★★★ 跟 #4 配對 leverage 最大
    8規格先於實作設計分解★★★★ 直接決定 AI 輸出結構
    9權衡分析設計分解★★★★ 抗 AI 默認 yes 傾向
    10預設驗收標準過程紀律🟡★★★★ 該補,沒守會默認 plausible-looking
    11可重跑知識持久化★★★ 任務一次性可省,系統性任務必須
    12預算控管過程紀律★★★ 小任務可省,長 background 任務必須
    13根因分析核心驗證🟡★★★★ 主要靠 prompt 設計
    14錯誤處理哲學設計分解★★★★ AI 預設 fail-silently 必補
    15版本控制知識持久化★★★ brain 控管比 code 控管更重要

    結論:跟 AI 寫程式需要哪些軟工?

    不是新的軟工,是舊軟工套到 AI 4 個特性上

    15 條全部都不是「AI 時代發明的」 — 每條都能在 1990 年代的軟工教材找到根。差別在 4 個 AI 特性對這些紀律的需求強度不同:

    AI 特性 被放大需求的紀律
    訓練資料 cutoff#1 驗證紀律(逼 AI 查資料,不要憑記憶)
    Stateless / 無 conversation 記憶#4 文檔作為輸入、#15 版本控制(外部記憶持久化)
    非 deterministic 輸出#11 可重跑、#10 預設驗收標準、#14 錯誤處理(處理隨機性)
    高並發 + 高速#6 並行、#12 預算控管(token 倍率風險)

    個人 leverage 排序(5 強)

    如果你是這條光譜中段的人(寫過 5 年以上 code,剛開始系統性用 AI 寫 code),最該優先吸收這 5 條:

    1. #1 驗證紀律 — 沒守這條,後面 14 條都白學。AI 講什麼都不能信,grep / curl / test 重驗
    2. #2 正交分解 — 拆軸線問,不要 bundled question。直接決定 AI 回答品質
    3. #4 文檔作為輸入 — 把學到的寫成下個 conversation 可讀的格式。沒這條,每次 onboarding
    4. #3 真實基準 — Toy example 騙人。用 production codebase 評估工具
    5. #5 Focused review — 給 AI feedback 一次只挑一條軸線

    沒做的 5 條,該怎麼補

    本次對話沒做的紀律對應 5 條 action(從便宜到貴):

    1. #15 版本控制(5 分鐘):cd ~/.claude/projects/-home-tom && git init && git add . && git commit -m "snapshot" 一次性處理
    2. #11 可重跑(2 分鐘):把 workflow script 從 session 暫存 cp 到 brain 或 dotfiles repo 歸檔
    3. #10 驗收標準(每任務多寫 3 行 prompt):任務 prompt 開頭加「驗收標準:N 個項目,M% 正確率,通不過要告訴我」
    4. #14 錯誤處理(每 workflow 多寫 5 行):script 內加 fail-fast / skip / retry 分支
    5. #12 預算控管(系統性設定):Claude Code admin page 設 hard daily limit 或寫個 hook 跑前先估

    真正的 meta-insight

    本文 15 條展開後最反直覺的觀察:跟 AI 寫程式需要的軟工基礎,大部分不是 code-level 的,是 process-level + protocol-level 的。傳統軟工新人學的順序是「先學語言 → 再學 design pattern → 最後學 process」,跟 AI 寫程式得反過來:先學 process discipline(怎麼下指令、怎麼驗證、怎麼回顧),最後才是 code-level technique

    因為跟 AI 寫程式,code 是 AI 生的,你扮演的是 reviewer + verifier + spec writer 三個角色。這三個角色傳統上叫 PM / QA / Tech Lead — 都是 senior eng 的活。所以「跟 AI 寫程式比較簡單」這句話完全反了 — 它把senior eng 的工作 commoditize 到每個用 AI 的人身上,reviewer 的紀律從「資深工程師的特權」變成「每個 prompt 作者的基本技能」。

    這就是為什麼那麼多人「用 AI 寫了一堆 code 但跑不起來」 — 不是 AI 不行,是沒人替他們做 reviewer / verifier / spec writer 那三層活。本文 15 條的本質就是把這三層活的紀律寫下來。

    跟我之前文章的關聯

  • Claude Code Dynamic Workflows 實測:Opus 4.8 + 11 Haiku 平行 audit 109 個 resolver

    重點摘要

    • Anthropic 在 2026-05-28 釋出 Claude Opus 4.8,帶來 Dynamic Workflows(背景跑 JS script orchestrate 數百 subagent)、Effort Control(low/medium/high/xhigh/max/ultracode)、Messages API system entries 中段插入。
    • 實測:同題雙軌跑 Home123(Go + gqlgen 後端)的 109 個 resolver 函式 authz pattern audit,baseline (Opus 4.7 + 1 個 general-purpose agent) vs workflow (Opus 4.8 + 11 個 Haiku 4.5 worker)。
    • 最大發現:workflow runtime 自動把 worker model 派為 Haiku 4.5,主 orchestrator 維持 Opus 4.8 — 對應「想 → opus / 找 → haiku」分工 doctrine,以前要手寫 AGENTS.md 分配的事 runtime 替你做了。
    • Wall time 沒省(workflow runtime 132 秒比 baseline 236 秒快,但加上主 session synthesis 反而是 392 秒)。本次估算成本 workflow ~$6.1 是 baseline ~$0.72 的 ~8.5× — 主要花在 runtime cache write 固定成本,大規模任務攤平會降下來。
    • 收益不在省錢,在:JSON Schema 強制輸出契約、reproducibility(script 落地,以後 /<name> 一鍵重跑)、主 orchestrator 主動 cross-check 下游(實戰抓到 synthesis subagent 算錯總數 83 vs 真實 109)。

    一眼看完:Baseline vs Workflow

    整篇下面會逐項拆,先給你 5 秒讀完的版本。題目都是同一份 Home123 GraphQL 後端 109 個 resolver 函式的 authz pattern 分類。

    面向 Baseline Workflow
    啟動指令主 session 派一個 Agentclaude --model claude-opus-4-8 --effort high 後 prompt 內塞 workflow
    主模型Opus 4.7Opus 4.8
    Worker 數量1(general-purpose,可寫)11(Explore 型,強制 read-only)
    Worker 模型Opus 4.7(跟主一致)全 11 個 Haiku 4.5(runtime 自選)
    並發加速11 agents 加總 354s 實跑 132s = 2.7×
    主 session tool call24 (14 Bash + 10 Read)8 (5 Bash + 2 Read + 1 Workflow)
    輸出契約自由 markdownJSON Schema + enum 鎖死 4 值
    覆蓋109/109109/109
    總耗時3:56(236s)6:32 turn,workflow runtime 2:12
    抓到的 root cause1 個(CapsAny 提案)6 個(含 guard 5× 重複的真兇)
    結構級洞見沒做出read-side vs write-side 不對稱
    主動 cross-check 下游—(只有 1 agent)✅ 抓到 synthesis agent 算錯 83 vs 真實 109
    估算成本~$0.72~$6.10(約 8.5× baseline)
    可重跑script 落地,以後 /<name> 一鍵

    架構差異:一張流程圖

    讀者最常問的不是「快多少」,是「結構上到底差在哪」。把兩種模式畫成流程:

    Baseline                              Workflow
    ─────────                             ─────────
    User prompt                           User prompt
        │                                     │
        ▼                                     ▼
    ┌─────────────────┐                   ┌─────────────────┐
    │ Main Claude     │                   │ Main Claude     │
    │ (Opus 4.7)      │                   │ (Opus 4.8)      │
    │                 │                   │ 寫 JS script    │
    │ Agent tool      │                   └────────┬────────┘
    │   ↓ 派 1 agent  │                            │ Workflow tool
    └────────┬────────┘                            ▼
             │                              ┌──────────────────┐
             ▼                              │ Runtime          │
       ┌──────────────┐                     │ (背景執行 script) │
       │ 1× Opus 4.7  │                     └────────┬─────────┘
       │ general-     │                              │ fan-out
       │ purpose      │                              ▼
       │              │            ┌──────────────────────────────────┐
       │ ─ 24 tool ─  │            │ Phase 1: Classify (平行)         │
       │   call ─ 自由 │            │ ┌────┐┌────┐┌────┐ ... ┌────┐  │
       │   分類 +    │            │ │H4.5││H4.5││H4.5│      │H4.5│  │
       │   markdown  │            │ └────┘└────┘└────┘      └────┘  │
       └──────┬───────┘            │ 10 agents (schema 切 8 chunks +  │
              │                    │  visitor 1 + announcement 1)     │
              ▼                    └────────────┬─────────────────────┘
       markdown report                          │ JSON schema 驗證
                                                ▼
                                   ┌──────────────────────────┐
                                   │ Phase 2: Synthesize      │
                                   │ ┌────┐                    │
                                   │ │H4.5│ 1 agent           │
                                   │ └────┘                    │
                                   └────────────┬──────────────┘
                                                │
                                                ▼
                                   ┌──────────────────────────┐
                                   │ Main Claude (Opus 4.8)   │
                                   │ cross-check synthesis,   │
                                   │ 抓到 83 vs 109 算術錯誤  │
                                   │ 用 authoritative rows     │
                                   │ 重算 + 寫最終 report     │
                                   └────────────┬──────────────┘
                                                ▼
                                       final markdown report
                                       + JS script 落地

    關鍵差別不是 agent 數,是「主 Claude 不再親手做活,變成 orchestrator + verifier」。中間結果落在 script 變數,不灌進主 session context。

    背景:Opus 4.8 帶來什麼

    Anthropic 在 2026-05-28 同步發佈了 Claude Opus 4.8、Dynamic Workflows research preview、Effort Control、以及 Messages API 的中段 system entries 支援。發佈當天我看了官網內容,隔天 5/29 拿真實專案 Home123 跑了一輪雙軌對照,本文記錄完整數據與啟動 prompt。

    三個直接相關的能力更新:

    能力說明適用 plan
    Dynamic WorkflowsClaude 寫一支 JS script,runtime 背景跑,內含可數百個 read-only Explore subagent 平行作業所有付費(Pro 要先去 /config 開)
    Effort Control5 級:low / medium / high / xhigh / max,另有 ultracode(= xhigh + 自動 workflow orchestration)所有 plan
    Messages API system entries可在 messages array 中段插入 system entry,更新指令但不破 prompt cache、不需要假裝 user turnAPI 直連

    不是所有 model 都吃所有 effort 等級。實測 claude --effort foo 會回:

    error: option '--effort <level>' argument 'foo' is invalid.
    It must be one of: low, medium, high, xhigh, max

    官方支援表(來自 code.claude.com/docs/en/model-config):

    Model支援 effort 等級預設
    Opus 4.8, Opus 4.7low, medium, high, xhigh, max4.8 → high / 4.7 → xhigh
    Opus 4.6, Sonnet 4.6low, medium, high, max(沒 xhigh)high
    其他不支援 effort

    常見誤解:Sonnet 也能 xhigh 嗎?不行。Sonnet 4.6 只到 high,你硬塞 xhigh 會自動降到 high 不報錯但也少一級。ultracode 在 Sonnet 連菜單都不出現。

    對照實驗設計:為什麼挑 Home123 authz audit

    Workflow 適合的題目有 4 個必要條件:

    1. 可平行化 — 任務天然能切成 N 個獨立 chunk
    2. 可被 JSON Schema 約束 — 輸出結構穩定、enum 有限
    3. 有 ground truth — 否則 11 個 agent 跑完你也不知道對不對
    4. Read-only 為佳 — Explore type agent 不會誤改檔

    挑的題目:掃描 Home123 backend GraphQL 的 3 個 resolver 檔,把 109 個 resolver function 分類成 USES_PRELUDE / LEGIT_PUBLIC / HAND_ROLLED / UNKNOWN。

    Home123 是 multi-tenant SaaS,我自己寫了一個 authzPrelude centralised authn+cap+scope+audit 序列,規範每個 protected resolver 進 withTx 後第一段要 call。但程式碼累積過程中,有些 resolver 為了 cap-OR 之類 prelude 還不支援的情境 hand-roll 了授權邏輯。這次審計就是要逐一抓出來。

    符合條件為什麼這題符合
    可平行化109 個 function 各自獨立,每個分類不依賴其他結果
    可被 schema 約束class enum 只有 4 值;每筆 row 必填 file / func / line / class / evidence
    有 ground truthgrep -c authzPrelude backend/graph/*.resolvers.go 給出客觀基準
    Read-only純審計、不改檔

    啟動 prompt:兩邊放在一起看

    兩邊我都跑了。下面先給差異速覽,再給雙邊完整 prompt 對照。

    差異速覽

    面向 Baseline Workflow
    session 啟動任何 session 都可,呼叫 Agent toolclaude --model claude-opus-4-8 --effort high
    觸發機制主動派 1 個 Agentprompt 內含 workflow 關鍵字 → Claude Code 反白 → approval prompt
    Prompt 句子數~20 行(任務說明)~24 行(任務說明 + 第一個字「workflow」)
    關鍵差異字直述命令式 — 「做這個 audit」第一個字加 「跑一個 workflow,」 — 觸發 runtime 寫 script
    事前需要無(general-purpose 預設可用)Claude Code ≥ 2.1.154,Pro 要先 /config
    跑前是否確認不需要,直接跑approval prompt 必須選 [1] Yes;第一次強烈建議按 [3] View raw script

    左:Baseline prompt(逐字)

    你在 /home/tom/Desktop/home123_new 做一次 read-only authz pattern audit。
    禁止修改任何檔案。
    
    審計三個 resolver 檔的每一個 resolver function:
    - backend/graph/schema.resolvers.go (~80 funcs)
    - backend/graph/visitor.resolvers.go (~15 funcs)
    - backend/graph/announcement.resolvers.go (~16 funcs)
    
    分類規則:
    1. USES_PRELUDE — body 第一段 call authzPrelude(...)
    2. LEGIT_PUBLIC — 真正不需要 auth 的 (Login / RefreshAccessToken 等)
    3. HAND_ROLLED — 沒 call authzPrelude 但自己寫 cap/scope/role/audit 檢查
    4. UNKNOWN — 你無法判定
    
    輸出:markdown 表 | file | func | line | class | evidence |,
    所有 function 一行不能少。
    
    最後加 ## Summary:每 class 數量、HAND_ROLLED 跟 UNKNOWN 清單、可疑模式。
    
    用 Bash grep / Read 自己抓,不要憑記憶或猜。

    右:Workflow prompt(逐字)

    新 session 啟動:

    cd /home/tom/Desktop/home123_new
    claude --model claude-opus-4-8 --effort high

    進去後丟這個 prompt(留意第一個字是 「在這個 repo 跑一個 workflow,這個關鍵字就是觸發 runtime 的開關):

    在這個 repo 跑一個 workflow,做 read-only authz pattern audit。不准改任何檔案。
    
    審計三個 resolver 檔的「每一個」resolver function:
    - backend/graph/schema.resolvers.go (約 78 funcs)
    - backend/graph/visitor.resolvers.go (約 15 funcs)
    - backend/graph/announcement.resolvers.go (約 16 funcs)
    
    每個 function 分類成 4 種之一:
    1. USES_PRELUDE — body 第一段 call authzPrelude,或 1-line delegate 到呼叫
       authzPrelude 的 helper
    2. LEGIT_PUBLIC — 真公開查詢 (Login / RefreshAccessToken / Healthcheck /
       ApplicationStatus 等),依據 schema directive / 註解 / 函式意圖判定
    3. HAND_ROLLED — 沒 call authzPrelude 但自己寫 cap/scope/role/audit
       (CheckCap / hasRole / rbac.RequireCapability / 手動讀 ctx 判 user)
    4. UNKNOWN — 邏輯太繞或無法判定
    
    輸出格式:markdown 表 | file | func | line | class | evidence |,
    每個 function 一行不能少。
    
    最後加 ## Summary:每 class 數量、HAND_ROLLED 跟 UNKNOWN 名單、可疑模式
    (eg. asymmetry / 同一 cap 兩種寫法 / 整個檔的傾向)。
    
    建議擴展 prelude 才能解的問題也標出來 (eg. CapsAny 多 cap OR-chain)。

    送出後 Claude Code 會問你

    Workflow plan:
      Phase 1: Classify — one Explore agent per function-range chunk
      Phase 2: Synthesize — cross-file pattern analysis + suspicious findings
    
    [1] Yes, run it
    [2] Yes, and don't ask again for <name> in <path>
    [3] View raw script   ← 第一次強烈建議按
    [4] No

    第一次按 View raw script 看 Claude 寫出什麼 JS,看完按 ESC 回去再按 Yes。這是 workflow 教育核心,跟 subagent 的 black box 是完全不同的體驗 — 你看得到 orchestration 的具體 code。

    Claude 寫的 workflow script 長啥樣

    從 session jsonl 撈出來的真實 script 開頭片段:

    export const meta = {
      name: 'authz-pattern-audit',
      phases: [
        { title: 'Classify',   detail: 'one Explore agent per function-range chunk' },
        { title: 'Synthesize', detail: 'cross-file pattern analysis' },
      ],
    }
    
    // JSON Schema 強制每筆 row 必填 5 欄
    const ROW_SCHEMA = {
      type: 'object',
      required: ['rows'],
      properties: {
        rows: {
          type: 'array',
          items: {
            type: 'object',
            required: ['file', 'func', 'line', 'class', 'evidence'],
            properties: {
              file: { type: 'string' },
              func: { type: 'string' },
              line: { type: 'integer' },
              class: {
                type: 'string',
                enum: ['USES_PRELUDE','LEGIT_PUBLIC','HAND_ROLLED','UNKNOWN']
              },
              evidence: { type: 'string' },
            },
          },
        },
      },
    }
    
    const PRELUDE_REF = `
    REFERENCE — what each class means in THIS codebase (backend/graph/authz.go):
    authzPrelude(ctx, tx, claims, PreludeOptions{Cap:..., Scope:..., ...})
    is the centralised authn+cap+scope+audit sequence...
    CLASSIFICATION RULES (pick exactly one per function):
    ...
    `
    
    // schema.resolvers.go 切 8 chunks,各 1 個 Explore agent;visitor / announcement 各 1
    // fanOut(...) → 10 個 read-only Explore agents 平行
    // 然後 1 個 synthesis Explore agent 做 cross-file 分析
    
    return { rows, summary }

    注意三件事:

    • JSON Schema 鎖死 enum:subagent 不可能跑出 "class": "MAYBE" 這種,runtime 直接退回。Baseline 自由 markdown 沒有這層保護。
    • agentType: 'Explore' 是 script 層硬性:11 個 agent 完全不能 Edit/Write,不是靠 prompt 講「不准改」這種 soft 約束。
    • chunk 切法寫死在 script:每個 agent context 不汙染,不會記錯行號。

    跑起來後的真實 process 狀態

    從本機 process tree + session jsonl 即時觀察到的(workflow 跑到 110 秒時):

    $ ps -o pid,pcpu,pmem,vsz,rss,etime,cmd -p 1676911
        PID %CPU %MEM    VSZ   RSS     ELAPSED CMD
    1676911 26.9  1.0 73786132 337864    01:49 claude --model claude-opus-4-8 --effort high
    
    $ python3 - << 'PY'
    import json
    events = {}; tools = {}
    with open('<session>.jsonl') as f:
        for line in f:
            d = json.loads(line); ...
    print(events, tools)
    PY
    # 結果:
    # {'assistant': 14, 'system': 2, 'user': 6, ...}
    # Tools: {'Bash': 3, 'Read': 1, 'Workflow': 1}

    主 session 只花 5 個 tool call(3 Bash + 1 Read 探勘 + 1 Workflow 派出去)就把工作全部 delegate 出去,自己等 callback。

    Workflow runtime 把 11 個 agent 的執行軌跡寫到磁碟,結構是這樣的:

    ~/.claude/projects/<project>/<session>/
    ├── workflows/
    │   ├── scripts/
    │   │   └── authz-pattern-audit-wf_d545fc61-597.js   ← Claude 寫的 script
    │   └── wf_d545fc61-597.json                         ← run state
    └── subagents/workflows/wf_d545fc61-597/
        ├── journal.jsonl                                ← 11 個 agent 起跑/完成軌跡
        ├── agent-a1b66c368221dfcbc.jsonl                ← 每個 agent 的完整 transcript
        ├── agent-a1b66c368221dfcbc.meta.json
        ├── ...(共 11 對 jsonl + meta)
        └── agent-a24f70cfc4a9cea4c.jsonl                ← synthesis agent

    從 journal.jsonl 可以看到並發狀況:7 個 agent 同時 started,然後 result/start 交錯。實測 Tom 8-core 機器同時 active ~7 個,沒撞到 16 上限。

    最大發現:runtime 自動把 worker 派為 Haiku 4.5

    從每個 agent 的 jsonl 撈 model 跟 token:

    aid          model         dur(s)   in     out     cache_r    cache_w
    a1b66c3682   haiku-4-5     36.6     68     2913    704739     86473
    a24f70cfc4   haiku-4-5     65.3     126    6780    831993     139390
    a44126f699   haiku-4-5     46.0     113    2750    780310     99018
    a5b0952489   haiku-4-5     18.1     36     2106    172988     79402
    a677c4aa85   haiku-4-5     15.6     41     1955    164250     84687
    a98dc4ecbc   haiku-4-5     18.3     26     2189    132348     57398
    aa0358d7b4   haiku-4-5     39.4     132    3935    803238     66657
    aac3435e5b   haiku-4-5     22.4     77     2798    384636     174664
    aac426ca5b   haiku-4-5     24.5     41     2616    235382     64016
    ab4b713305   haiku-4-5     28.6     120    2618    480910     158476
    abe7fdedda   haiku-4-5     39.8     88     3173    896956     110064

    11 個 worker 全部是 Haiku 4.5。我啟動用 --model claude-opus-4-8,但 workflow runtime 自選把 worker 派去 Haiku。

    這對應到我 MEMORY 裡寫的「想 → opus / 做 → sonnet / 找 → haiku」模型分層 doctrine。Runtime 替我做了:

    • 主 orchestrator(寫 script + synthesis)= Opus → 「想」
    • 11 個 worker(bulk classification / grep / read)= Haiku → 「找」
    • 沒 Sonnet 是因為這題沒「做」(read-only audit 沒寫入)

    意義:原本 plan 期手寫 AGENTS.md 分配模型的事,runtime 替你做了。這比文件公告任何一條新功能都重要 — adaptive staffing 從「未來方向」變成「實裝」。

    對照結果:數字攤開

    面向 Baseline (Opus 4.7 + 1 agent) Workflow (Opus 4.8 + 11 Haiku)
    總耗時3:56 (236s)6:32 turn / 2:12 workflow runtime
    真實平行加速11 agents 累加 354s,實跑 132s → 2.7×
    主 session tool call24 (14 Bash + 10 Read)8 (5 Bash + 2 Read + 1 Workflow)
    Subagent 數1(general-purpose,可寫)11(Explore,read-only)
    Subagent 模型Opus 4.7全 11 個 Haiku 4.5
    覆蓋109/109109/109
    總 token(估)~103K~480K(主 315K + workers 165K)
    Cache read6.95M(瘋狂重用)
    估算成本~$0.72~$6.10(約 8.5× baseline)

    分類結果差異

    Class Baseline Workflow 差異原因
    USES_PRELUDE8478Workflow 把「prelude + 後續 manual orchestration」歸到 hand_rolled hybrid,標準更嚴
    LEGIT_PUBLIC1317Workflow 把 Logout / Me / Community 視為 public(judgment call)
    HAND_ROLLED1012Workflow 多抓出 5 個 hybrid hand-roll(prelude 加 manual 後處理)
    UNKNOWN22同(兩個 *AuditUnacked,純靠 RLS)

    質的差異:同題下 baseline vs workflow 各看到什麼

    數字一樣是 109/109 覆蓋,但兩邊對同一個 codebase 「看見」的東西不一樣。下面 4 個維度,左 baseline 右 workflow 並列。

    差異 #1:對下游結果是否複查

    Baseline 表現 Workflow 表現
    只有 1 個 agent,自己跑自己算,沒有下游可疑。Report 怎麼算就怎麼算,讀者要自己 grep 才能驗。 Synthesis subagent 自己算出 total: 83(漏算 26 個)。主 orchestrator (Opus 4.8) 拒絕信任,自己重算 109,公開記下:

    “The audit is complete, but the synthesis agent’s counts look off (it reported total=83, but I dispatched coverage for 109 functions). Let me verify completeness from the authoritative rows array myself.”

    這就是 4.8 公告吹的「4× less likely to allow flaws in code it wrote to pass unremarked」實戰演示。

    差異 #2:對 root cause 的挖掘深度

    Baseline 的觀察 Workflow 的觀察
    cap-OR 是 4 個 hand-roll 不 migrate 的主因」。

    停在第一層觀察。沒挖到更底層的結構問題。
    Households / Parcels / ParcelsPage / CommunityVisitors / VisitorAuditLog 同一段 SQL 抄 5 次。真兇是 AuthzDecision.IsCommunityWide 排除了 guard role,迫使每個把 guard 當 community-wide 的 resolver 都得自己重 probe。」

    挖到第二層結構根因。能做出來是因為 synthesis 是專屬 agent、有獨立 context,沒被 109 函式的細節塞滿。

    差異 #3:可落地的 fix 提案數

    Baseline 給的提案 Workflow 給的提案
    1 個:擴展 prelude 支援 CapsAny 多 cap OR-chain 6 個 可落地的 prelude extension:
    1. CapsAny []string — 解 4 個 hand-roll
    2. 承認 guard 是 broad role(RoleListBroad bool)— 解 5× 重複的 SQL probe
    3. ScopeDowngradeOnRole map[role]AuthzScope — 解 2 個 visitor scope 降級
    4. Cap + CapOwn + OwnershipIDCol — 解 2 個 announcement ownership
    5. authzPreludeAny([]PreludeOptions) 多路徑 helper — 解 2 個 multi-path
    6. ScopeRLSOnly enum(顯式宣告 RLS-only)— 解 2 個 UNKNOWN
    最高 leverage:#1 + #2 兩個 API 微調可幹掉 12 個 hand-roll 中的 7 個。

    差異 #4:結構級觀察

    Baseline 的結論深度 Workflow 的結論深度
    逐個 function 分類完,給 Summary 數字。

    沒有跨函式結構洞見。讀者拿到表得自己再看一輪才能發現「全部 hand-roll 都在 query 那邊」。
    「所有 7 個純 hand-roll + 2 個 UNKNOWN 集中在 schema.resolvers.go 的 query tail(line 6210-7130),mutation 100% 走 prelude。」

    結論:「read-side authz is where the rot is.」

    這級結構洞見 baseline 沒做出來,因為它的 agent 同時在處理逐函式分類跟跨函式觀察兩件事,context 被佔滿。

    4 個差異的共同根因

    Workflow 4 個維度都贏,不是模型差,而是架構差:

    • Synthesis 是專屬 phase 跟專屬 agent,不跟逐函式分類搶 context
    • 主 orchestrator 不直接做活,有餘力去 cross-check 下游
    • JSON Schema 鎖死 enum,讓 synthesis 的算術錯誤被直接 vs 證據對照,容易被抓
    • 每個 Classify agent 只看自己那塊 chunk,context 不被 109 函式整體噪音蓋掉

    換句話說:把 baseline 的單一 Opus 4.7 agent 升級成 Opus 4.8 也救不了 — 缺的是 architectural separation of concerns,不是模型聰明度。

    成本拆解:雙邊對稱對照

    用公開 pricing 算(Opus 4.7 / 4.8 同價:$5/M input、$25/M output、~$0.50/M cache_read、$6.25/M cache_write;Haiku 4.5:$1/M input、$5/M output、~$0.10/M cache_read、$1.25/M cache_write)。

    Baseline 拆解

    誠實先講:baseline 走 Agent tool,Anthropic 只回傳 total_tokens: 103,078,沒給 input/output 拆解。所以我只能上下界估算。

    情境 假設拆解 成本
    下界(全是 input)103K in / 0 out$0.52
    合理估(read-heavy audit,輸出 ~10K markdown)93K in / 10K out~$0.72
    上界(全是 output,不現實)0 in / 103K out$2.58

    Workflow 拆解

    Workflow runtime 把每個 agent 跟主 session 的 token 都寫到 jsonl,可以精算。

    項目 Input Output Cache read Cache write 成本
    主 session (Opus 4.8)31,68659,5061,361,289262,528~$3.97
    11 workers (Haiku 4.5)~870~33,833~5,587,750~1,120,245~$2.13
    Workflow 合計~32,556~93,339~6,949,039~1,382,773~$6.10

    並排比較與成本比

    指標 Baseline Workflow 倍率
    總 token(可量到的)~103K~8.46M(主 + workers,含 cache)~82×
    非 cache token~103K~125K(主 + workers,純 in+out)~1.2×
    估算成本~$0.72~$6.10~8.5×

    校正一下我之前隨口說的「2-3× cost」 — 認真算下來這次 workflow 是 baseline 的 ~8.5×。會這麼高的主因是 workflow runtime 海量 cache write(主 session prompt 加上 11 個 worker 各自的 system+task prompt 都得 cache),這在小規模任務上吃掉的固定成本不成比例。

    更大規模(例如 1000 個 function、5 個檔案、要跑多輪 phase 的 codebase-scale migration)倍率會掉下來,因為 cache 攤平。本次 109 函式可能還沒到 workflow 的 sweet spot。

    收益不在錢,在結構性保證:JSON Schema 鎖死輸出契約、Explore agent 鎖死 read-only、script 落地 reproducible、主 orchestrator 主動 cross-check 下游算術錯誤、結構級洞見的獨立 synthesis pass。如果這次的 audit 結果直接讓你修對 5 個 bug,$5 的價差完全划得來;如果只是研究性掃描、要常常重跑,$0.72 的 baseline 更合理。

    何時用、何時不用

    情境 該用
    平行 audit / sweep / 分類(N 個獨立目標)Workflow
    結果可被 JSON Schema 約束Workflow
    有 ground truth 可驗(grep / 規則對照)Workflow
    Codebase migration 數百到千行Workflow
    30 行小改、互動式 debug、需要中途決策Subagent / 直接對話
    設計 / 重構 / 探索 spike直接對話
    序列邏輯(A 結果決定 B 做啥)Subagent
    預算敏感、有 deadlineSubagent

    硬性限制(踩過的)

    限制數字影響
    並發 agent最多 16(8-core 機器實測 ~7 並發)大 chunk 設計,別追求一函式一 agent
    單 run 累計 agent硬上限 1000大型 migration 拆多個 workflow
    中途要用戶輸入不行多階段簽核拆多 workflow,中間落地
    script 直接 fs / shell不行透過 agent 做,script 純 orchestrate
    Subagent permission mode永遠 acceptEdits想 read-only 一定用 agentType: 'Explore'

    把 workflow 存成可重用 slash command

    跑完滿意,在 workflow session 內:

    /workflows               # 列出 run
    ↑↓ 選那個 run → Enter   # 進入進度檢視
    s                        # 存成 slash command
      → 選 .claude/workflows/<name>.js (repo 共享)
      → 或 ~/.claude/workflows/<name>.js (個人跨專案)

    之後 /<name> 像 slash command 一樣用。Project workflow 優先級高於 personal 同名。

    想 resume failed run:

    Workflow({
      scriptPath: "<session>/workflows/scripts/<name>-<runId>.js",
      resumeFromRunId: "wf_xxx"
    })
    # completed agents 回傳 cached result,只重跑失敗的

    關掉 workflow

    範圍怎麼關
    自己/config 切 Dynamic workflows / settings.json 設 "disableWorkflows": true / 環境變數 CLAUDE_CODE_DISABLE_WORKFLOWS=1
    整組織managed settings "disableWorkflows": true 或 Claude Code admin page 切

    關掉後:built-in /deep-research 不能用、workflow 關鍵字不觸發、ultracode/effort 菜單消失。

    對日常工作的影響

    我自己接下來打算用 workflow 跑的場景:

    • Home123 RLS coverage sweep — 每張 table 確認 CRUD 4 個 RLS policy 都齊
    • Home123 invariant coverage — 170 個 INV 是否在 backlog 有對應 test sketch
    • iDempiere @RestResource endpoint 巡檢 — endpoint × test × OData filter doc 三角檢
    • SimpleEC OMS Kafka 事件覆蓋矩陣 — topic × producer × consumer 對應

    不會用 workflow 的場景:走 decision-server 的任何題(workflow 中途不能停下來問人)、30 行小修、新功能 spike(reproducibility 沒價值)。

    跟我之前文章的關聯

    結論:結構性保證,不是省錢工具

    Dynamic Workflows 不是「Claude 變強了所以更便宜」,而是「Claude 把 plan 期才做的 staffing 決策搬到 runtime,並用 JSON Schema + Explore 型別把輸出契約寫進 code 而非 prompt」。對任務符合 4 條件(可平行、可 schema、有 ground truth、read-only)的場景,workflow 的結構性保證值得 2-3× cost。不符合的場景繼續用傳統 subagent 跟直接對話,別因為「workflow 看起來酷」default 用。

    真正令人意外的不是任何單一功能,是「runtime 自動派 Haiku 4.5 給 worker、保留 Opus 4.8 給 orchestrator」這件事連文件都沒重點說。它把以往要寫進 AGENTS.md 的「想/做/找」三層分工,從文件變成系統行為。下一輪 model release(Mythos Preview 已預告)會繼續推進這條軸線:組織 prompt 從手寫變 runtime 推導。

  • AI 不該替我打 🟢🟡🔴:從 decision-server 看跟 LLM 協作決策的介面方法論

    重點摘要

    • Markdown vs HTML 是假議題 — 真正問題是「LLM 給人類決策時的介面設計」
    • AI 加工成 🟢🟡🔴 標籤的「成本/風險」評分,使用者不信。要 raw evidence (檔案、行數、schema 影響),讓使用者自己判斷
    • 解法:一個 Flask + systemd + Cloudflare tunnel 的 decision-server,每個決策生 HTML 頁,使用者在瀏覽器/手機看真實證據後點選項
    • 規則寫進全域 ~/.claude/CLAUDE.md,所有 Claude session (含 Telegram bot) 自動遵循
    • 實戰跑通:4 個 agent 並行審查 dementia-care home-handbook 找出 45 個 findings → 5 個獨立決策 page → 答完 5 tier 自動改動 → commit 3d1f101 → 自動部署 GitHub Pages

    起點:一個假議題

    今天早上我問 Claude:「最近有一個聲音說過去我們使用 markdown 沒有實用性,要用 HTML。你幫我比較一下。」

    Claude 給了一份標準比較 — Markdown 的 token 效率、git diff 友善;HTML 的語意豐富、表達力強。然後得出結論:「在你的場景 markdown 全面勝出」。

    但我打斷他。真正卡我的不是文檔格式,是另一個問題:每次 Claude 問我做決策時丟一面牆的 markdown 字,我不知道背後意義、不知道範圍、不知道要考慮什麼,認知負擔很重。如果能像 HTML 那樣用顏色區塊跟拖拉條一眼判斷,我做決策的速度會快很多。

    這篇文章記錄今天從這個誤會開始,到我跟 Claude 一起建出一個跨 session 通用的決策伺服器,中間踩到的設計坑 + 抽出的協作方法論。

    第一次嘗試:加 🟢🟡🔴 對照表

    Claude 第一個提案是用 Claude Code 內建的 AskUserQuestion 工具,加上 emoji 視覺對照表。範例:

            速度  成本  風險
    A 拆分  🟢   🔴   🟢
    B 單檔  🟡   🟢   🟡
    C 折衷  🟡   🟡   🟢
    
    推薦 → C (綜合最佳)

    看起來不錯。我選了這個格式。Claude 還幫我寫進 feedback memory,以後預設都用這種對照表。

    30 分鐘後,我反悔了:「你說的成本不一定是真的成本,你說的風險也不一定是真的風險。你的比較我也不太能夠相信。

    核心問題:Raw Evidence vs 加工標籤

    🟢🟡🔴 是 Claude 對「成本/風險」的主觀評分。它幫我把證據壓縮成一個顏色,但這個壓縮過程是有損的,而且我看不到原始材料,沒辦法 second-guess。

    真正能幫我決策的不是「Claude 認為這個選項風險 🔴」,而是「這個選項會動 db/migrations/0042.sql 第 38 行的 CHECK constraint,影響 50,000 rows」。前者是評分,後者是事實。前者我半信半疑,後者我自己判斷。

    這個 framing 反過來界定了 LLM 在人類決策流程裡的角色:

    • 不該做的:替使用者打分數、給推薦星等、用顏色暗示優劣
    • 該做的:把零散證據整理成可掃描的結構,擴展使用者的判斷面,不替代它

    解法:decision-server

    我提了一個架構:在我的迷你 PC 上開一個 port,Claude 要我做決策時生成 HTML 丟到那個 port,我用瀏覽器/手機看。Claude 接過去做了完整實作:

    • Server:~/decision-server/server.py (Flask, 87 行)
    • Service:systemctl --user enable decision-server (linger 開,跨重開機)
    • Port:8765
    • Public URL:https://askme.tomting.com (Cloudflare Tunnel)
    • Endpoints: GET /d/{slug} 看頁面,POST /d/{slug} 收答案

    每個決策 3 個檔案共用一個 slug:

    檔案 寫入者 內容
    pages/{slug}.html AI 人類看的決策頁面
    meta/{slug}.json AI question + options 的結構化規格
    answers/{slug}.json Server 人類點完寫入,自我描述 (含 choice_label 全文)

    關鍵設計:answer.json 自我描述。不只存 choice: "B",連 choice_label 全文也存。三個並行 session 都點 B,後續讀檔不會混淆,因為每個 B 都帶著自己的語義。

    Selenium 跑了一輪整合測試:3 個假 session 各生一個決策 (slug 開頭分別 a3f7- / 9e2c- / b51d-),選不同字母,驗證:

    • 3 個 session 各自寫到自己的 answer.json,零交叉污染
    • index 頁正確分組顯示
    • 每個 answer 自描述完整

    頁面設計的演進

    第一版 page 只有「標題 + change_cards + options」。Tom 開了一張 demo 看完反應:「感覺資訊很少,情境根本無法懂問題是什麼,我要怎麼決策?

    對。決策者通常從別的事情切過來,不會有問題提出者的 context。設計 onboarding 區塊變成必填:

    • 📖 背景 (background):這個功能是什麼?涉及哪些表/服務?為什麼會跑出這個 decision?
    • ⚡ 核心問題 (problem):具體哪裡卡?矛盾在哪?
    • 🩸 不解的後果 (impact):拖著會怎樣?(技術債/錯誤/blocking 什麼)
    • 🔍 證據卡 (change_cards):真實 file:line + 真實 +/- 行數 + 1-3 個 bullet
    • 🎯 選項 (options):每個帶 consequence (成本 / 副作用 / 適合什麼情境)

    三層 framing 補完,Tom 就算前 5 分鐘在洗碗,開連結 30 秒內也能判斷。

    讓所有 session 都用這個 protocol

    我們建好了 server,但有個問題:Tom 同時開好幾個 Claude session — 寫 iDempiere 的一個、跑 Home123 的一個、Telegram 上的 ccbot 一個。每個 session 都要知道用 decision-server,不能靠每次重提

    解法:寫進全域 ~/.claude/CLAUDE.md (Claude Code 對所有 session 都會載入的全域指引)。新增段落「🌐 Decision-Server Protocol — MANDATORY for asking Tom decisions」,包含:

    • 觸發情境表:10 種要用 decision-server 的真實場景 (方案選擇 / 範圍決定 / 優先順序 / 動作授權 / 設計選擇 / Code review 後 / Schema 變更 / 批次決策 / 工具升級 / 不可逆操作)
    • 不觸發情境表:6 種對話講就好的例外 (確認理解 / 缺資訊 / 真瑣碎 yes/no / 用戶明說 / 教學模式 / Server 掛了)
    • 必填欄位表:14 個欄位的必選規格
    • 完整範例:一個 canonical JSON 直接抄
    • 禁止寫法表:9 條紅線 (例如禁止 "risk": "🔴" 主觀標籤)
    • 常見錯誤:5 個 future-session 易犯的

    驗證方式:跨 session 自動採用。寫完規則沒多久,ccbot (跑在 Telegram 上的獨立 Claude session) 在不知情狀況下,自動讀到全域 CLAUDE.md,自動用 protocol 生了 6 個決策 page (session_id 6089),Tom 在 Telegram 看到「卡你決策 6 條」改成 6 個 askme.tomting.com 連結,在手機上 5 分鐘答完。

    真實案例:home-handbook 審查

    整個 stack 跑通後,我用它做了第一個真實任務:全面審查 ~/Desktop/dementia-care/home-handbook/ (失智照護 handbook,4 個 HTML 檔案 4719 行)。

    步驟 1 · 並行 agent 掃描

    派 4 個 general-purpose agent 並行掃 4 個檔案 (index / caregiver / long-term / emergency),每個 agent 應用同一份 10 項檢查清單,清單來自 brain/llm-handbook-writing-pitfalls.md 的 9 個失敗模式 + design-principles 的 CDN/emoji 規則:

    1. 細節腦補 (沒驗證就寫具體名詞/數字)
    2. 失能 vs 失智 frame 混淆
    3. boredom vs restlessness frame
    4. 加法 vs 減法 (測試記憶 framing)
    5. 醫療因果 claim 無文獻 (「會/導致/加速 + 醫學名詞」紅線)
    6. SOP magic number 沒推導
    7. 戲劇化描述 (「像 X 一樣」「彷彿」)
    8. 工程師腦過度設計 (可觀測性、冗餘、invariant 思維)
    9. PII 洩漏 (姓名、稱呼、地址)
    10. CDN / 外部依賴 / 新 emoji (Unicode 14+)

    並行加總 4 個 agent 跑完 ~2 分鐘,回報 45 個具體 findings,每個帶 file:line + 引用原文 + 建議改法。

    步驟 2 · 用 decision-server 生 5 個獨立決策 page

    45 個 findings 不是 45 個決策。Claude 把它們合併成 5 個策略性決策(因為一頁一決策原則:類似議題歸為同一決策,選項是「處理策略」):

    # 議題 我選的
    1 PII 清理範圍 B:保留 meta author,內文一律第三人稱 + 砍 HTML 註解
    2 外部連結處理 B:保留連結 + 加 rel=”nofollow”
    3 醫療因果 claim D:混合 — 有臨床共識的補引用 (Beers Criteria / NICE),其他弱化或砍
    4 scope overreach (E6/E7/E8 跨 CDR 2 經驗) D:保留現狀,disclaimer 移到三章開頭加明顯
    5 magic number 無推導 D:混合 — 自家 SOP 補推導,醫療閾值補 disclaimer

    步驟 3 · 執行 + 部署

    我用瀏覽器答完 5 個 page,Claude 讀 answers/*.json 自我描述的 choice_label,執行對應改動。整理出 5 個 tier 的具體 edit (PII / 外部連結 nofollow / 醫療 claim 引用 / scope disclaimer / magic number 推導),全部用 Edit 工具批次處理。

    最後輸出:

    • commit 3d1f101 on dev branch,4 files changed, +46/-34 lines
    • merge dev → main (commit d3ccc98)
    • push origin/main
    • GitHub Pages 5 秒部署完成
    • 線上版:https://tm731531.github.io/dementia-care/home-handbook/

    抽出來的方法論

    原則 1 · Raw evidence > 加工標籤

    LLM 替使用者壓縮資訊是有損操作。決策接口要顯示可驗證的事實(檔案路徑、行數、schema 影響、binary 屬性),不是顯示 AI 對事實的評分(🔴 高風險、複雜度中等)。標籤把使用者鎖在 AI 的判斷裡,事實讓使用者用自己的判斷。

    原則 2 · 決策頁要做 onboarding 設計

    使用者打開決策頁時通常是「從別的事情切過來」,沒有問題提出者的 context。背景 / 問題 / 不解後果三段缺一不可。光列證據卡片他看不懂為什麼這個問題重要。

    原則 3 · 選項要帶後果

    選項 label 不夠。每個 option 帶 consequence 三件事:成本 (要做多少工)、副作用 (選了會被什麼牽動)、適合什麼情境。沒這三件事使用者只能猜選了會發生什麼。

    原則 4 · 一頁一決策

    N 個決策要用 N 個獨立 page,不要塞在同一頁。理由:answer.json 自我描述,每個答案要能單獨理解。多決策塞同頁 = 回到 Tom 鄙視的「文字牆」。

    原則 5 · 全域配置 > 個別提醒

    跨 session 要一致,要寫進全域 system prompt (Claude Code 的 ~/.claude/CLAUDE.md),不能靠每個 session 個別記住。寫進全域 = 自動覆蓋所有未來 session 包含 sub-agent 跟跨平台 bridge (ccbot)。

    原則 6 · 流程要可驗證

    關鍵 invariant 要寫測試。test_multi_session.py 用 Selenium 驗證 3 個並行 session 不互相污染。每次改 server 或 generator 都跑一次。PII 清理用 grep 自動驗:grep -c "老媽" 應該為 0。

    整套 Stack 重現指南

    如果你想複製這套協作模式,這是最小的 reproducible setup:

    • Server:Flask app,3 個 endpoint (GET / + GET /d/<slug> + POST /d/<slug>)
    • Generator:Python helper 接 stdin JSON spec 生 page + meta
    • Wait:Python helper 阻塞 polling 直到 answer.json 出現
    • Templates:Jinja2 – decision.html (含 session bar / 三層 context block / change cards / options buttons)
    • Service:systemd user service + linger 開 (持久跨重開機)
    • Public access:Cloudflare Tunnel (免費,1 條 command)
    • Global config:Claude Code 的 ~/.claude/CLAUDE.md 加 MANDATORY 區塊

    所有 Python 依賴只用 Flask + Selenium (測試用) + Jinja2,記憶體佔用 ~20MB,啟動時間 1 秒。整個 server.py 87 行,generator.py 75 行,template 88 行 (含 CSS)。建構成本 1 個下午,跑通就終身使用

    結語:不要替我打標籤

    這篇文章的起點是 markdown vs HTML,但真正的問題從來不是文檔格式。是「LLM 在人類決策流程裡扮演什麼角色」

    當 LLM 把所有事情壓縮成 🟢🟡🔴 或星等推薦,它就把使用者鎖在自己的判斷裡。當 LLM 把零散證據整理成可掃描的結構頁面,它擴展使用者的判斷面。前者是 LLM 取代人,後者是 LLM 服務人。

    建一個決策伺服器只是工具實作。背後的設計決定才是真正的協作哲學:給事實不給評分,給結構不給結論,給選項不給推薦

  • AI 跟人類聯手 debug:從 OOM 假象到 Spring DI 真相

    重點摘要

    • 表面看是 OOM crash loop,真因是 Spring DI 失敗 — 16 個 Java 容器每 3 分鐘 die 一次,累積 ~180 次重啟。
    • AI 一連 4 次「以為修好其實沒」,被自己的 grep 騙了:OutOfMemoryError 抓到的是 JVM 啟動印出的 -XX:+ExitOnOutOfMemoryError env var 字串,不是真的 OOM exception。
    • 真正解開的轉折是「人類的業務直覺糾正方向」 — 我問 AI 「retry-job 不就是把訊息丟回去嗎,為什麼要查 DB?」,AI 才回去看代碼發現是別的 service 設計錯了。
    • 人機協作的甜蜜點:AI 挖技術細節,人類提業務 frame,兩個能力反過來會卡住。

    這篇是一次真實的除錯紀錄。起點是「CCBOT 沒回應」這種小事,沿途碰上 simpleec 電商系統的 channel-job crash loop、Spring DI 失敗偽裝成 OOM、retry-job 反覆修不對,中間 AI 跟我來回交鋒 7 次才把問題真正解開。寫下來主要是想討論一件事:AI 除錯到底比人快在哪裡、人類業務直覺又補了什麼,以及這個 GAP 怎麼填。

    一切從 CCBOT 沒回應開始

    那天我在 Telegram 對 ccbot(我自己寫的 Claude Code Telegram bridge)發訊息,沒回應。問 AI:「幫我看看你的 CCBOT 有沒有問題,怎麼現在好像沒有回應了?」

    AI 第一步 systemctl --user status ccbot,結果發現 service 是 inactive (dead) since 2026-05-14 22:34:09。已經死掉兩天。AI 接著推理出原因:那個時間點正好是我在 tmux session 開始搭一個 Kiro 版的 telegram bot,當時為了避免兩個 bot 搶同一個 chat,我手動 stop 了 ccbot — 然後忘了開回來。

    順手讓 AI 重啟 ccbot,順帶查一下系統健康度。然後就看到:

    load average: 85.25, 81.85, 80.28
    

    8 個 CPU core 的機器跑到 load 85+ 是失控。docker ps 一看,我的 simpleec 電商 OMS 系統 50 個容器裡,有十幾個 channel-job container 的狀態是 Up 21 seconds / Up About a minute / Up 3 minutes。container 一直在重啟,沒一個穩定。

    第一次以為修好:Kafka 調參(其實沒)

    AI 翻了 channel-job 的 application.yml,發現一個經典坑:Spring Kafka consumer 完全沒設 max-poll-recordsfetch-max-bytes。預設值是 500 records / 52 MB,意思是一個 poll() 就可能塞 52 MB 訊息進 heap。channel-job 容器配 -Xmx256m,扣掉 Spring Boot + Hibernate + otel-agent 的基底,剩餘 heap 根本撐不住單次 poll 的爆衝。

    這是真實問題,我也讓 AI 一次修了 6 個 *-job 的 yml,把 max-poll-records 壓到 5-10,fetch-max-bytes 砍到 1 MB,順便把 16 個 channel-* 容器的 -Xmx256m 升到 -Xmx384m 給點 buffer。AI 還順手抓到一個 Lombok bug:SeedTestOrdersHandlerfakeChannel.isActived(),但欄位是 Boolean(包裝類),Lombok @Data 對包裝類產生的 getter 是 getActived() 不是 isActived(),從 4/9 起 build 就壞了,但用 quick-redeploy 單服務 build 從沒抓到。

    build 過了,docker compose 重啟,5 分鐘觀察 — channel-* 都 Up 2 minutes,RestartCount=0,heap 用量 122-190 MB / 384 MB,看起來健康。AI 報告「OOM crash loop 修好了 ✅」,我也信了。

    一小時穩定觀察揭穿假象

    我說「先觀察 1 小時穩定再 commit」,AI 開一個 background watch 每 15 分鐘檢查。1 小時後通知回來,結果震驚:

    時間點 不穩定的 channel-* 數
    T+15min8 個「Up About a minute」(剛重啟)
    T+30min1 個「Up 2 seconds」(剛 crash)
    T+45min10 個「Up About a minute」
    T+60min2 個 (crash)

    每 3 分鐘 die 一次,docker 一直在 restart。AI 重新看 log,grep OutOfMemoryError 抓到 16 個容器全部有「OutOfMemoryError」字串,結論「真的是 OOM,我之前 Xmx 升 384 還不夠」。我點頭準備繼續升 heap。

    但 AI 接著做了一件對的事:再 grep 一次,這次用更精確的 pattern java\.lang\.OutOfMemoryError。結果 — 0 個 match。前面抓到的「OutOfMemoryError」全是這一行:

    Picked up JAVA_TOOL_OPTIONS: -Xmx384m -XX:+ExitOnOutOfMemoryError
                                                      ↑ 這 16 個字元被 grep 抓到
    

    JVM 啟動時印出的 JAVA_TOOL_OPTIONS 環境變數,字串裡的 ExitOnOutOfMemoryError 最後 16 字元剛好是 OutOfMemoryError。AI 自己被自己的 grep 騙了兩次。換用 UnsatisfiedDependencyException 重 grep,16 個容器全 match。真兇現身。

    真兇:半成品的 Excel 上傳功能

    真實死因是 Spring DI 失敗:

    UnsatisfiedDependencyException: Error creating bean 'channelJobConsumer'
      → parameter 5: 'processExcelBatchHandler'
      → parameter 0: No qualifying bean of type
        'com.simpleec.core.repository.ExcelUploadBatchRepository' available
    

    追下去:有人(可能是另一個 AI session,或我自己忘了)在 channel-job 模組加了一個 ProcessExcelBatchHandler,但它依賴的 ExcelUploadBatchRepository 放在 simpleec-core 模組。問題是 ChannelJobApplication@EnableJpaRepositories 只 scan com.simpleec.channeljob.repository,看不到 core 模組。Spring 啟動找不到 bean → exit 1 → docker restart → 又找不到 → 永久 crash loop。35 天沒人發現,因為 quick-redeploy.sh 每次只 build 單個 service,從沒做過整體 build,所以這個 DI 問題只在 docker container 啟動時才暴露。

    AI 提議「補 Spring 的 scan path」修。我看了一眼設計直覺說「不對 — 這個 Excel 功能根本不該在 channel-job 做,channel-job 是『跟外部 API 對接』,Excel 上傳是內部資料源,該丟到 backend-job 走 task.backend topic」。AI 同意,把 4 個 Excel 檔案 park 到 /tmp/excel-feature-parked/,留 README 跟 3 個 revert patch 等原開發者後續按正確架構重做。

    但這還沒完。修好 channel-* 後,我順手問「順帶看一下 retry-job」,因為它 RestartCount=1146,意思是 12 小時內重啟超過 1000 次。

    第二場拉鋸:retry-job 的反覆修不對

    AI 看 log,發現 retry-job 的 DltConsumer(處理 dead letter queue)也是 DI 失敗:依賴 core 模組的 FailedTaskLogRepository,但 retry-job 設計上排除了 DataSource。AI 提議「補 scan + 把 retry-job 也升 384m heap」。

    我打斷:「retry-job 不就是把訊息丟回 queue 嗎,為什麼要查 DB?」

    這句業務直覺問題改變了 AI 的方向。AI 回去看 RetryJobConsumer.javaDltConsumer.java 對比,發現:

    • RetryJobConsumer 處理 task.failed — 純 Redis ZSet 存延遲排程,到時間丟回原 topic,完全沒 DB。設計正確。
    • DltConsumer 處理 task.dlt — 把死信寫到 failed_task_logs 表供「人工檢查」(註解明說),只 write 沒 read

    所以「retry-job 不該重」這個設計直覺是對的,但 DltConsumer 確實有合理需求要寫一筆 audit log。修法收斂成:用 JdbcTemplate 寫一行 INSERT,不載 Hibernate(可以省 50-80 MB heap),DltConsumer 改 5 行,RetryJobApplication 移除 DataSourceAutoConfiguration exclude。AI rebuild,等 90 秒,RestartCount=0,Status=running。報告「修好了」。

    17 小時後我回來檢查,retry-job RestartCount=1159。又開始 crash 了。

    原因:AI 第一次修法不完整。Spring Boot autoconfig 是「貪食」的 — 我們移除了 DataSourceAutoConfiguration exclude 讓 DataSource 能建,但 classpath 上 simpleec-core 還有一堆 JpaRepository class(ChannelRepository、OrderRepository…),Spring 看到就觸發 JpaRepositoriesAutoConfiguration,試圖建 entityManagerFactory 來支撐這些 Repository,但 Hibernate 還是 excluded → bean 不存在 → context refresh 失敗 → 啟動 exit。

    關鍵教訓:看 docker 的「Up X seconds」不代表健康。Spring Boot 啟動要 ~6-10 秒,如果在 context refresh 時 crash,container exit 後 docker 立刻 restart,新 instance 的 uptime 立刻變 Up About a minute — 但它正在「啟動 → 失敗 → 再啟動」的循環。AI 之前 90 秒驗證看 Up time 沒看 RestartCount 趨勢,被騙了。

    真正的修法是再加一個 exclude:JpaRepositoriesAutoConfiguration.class。告訴 Spring「即使 classpath 有 JpaRepository class,也不要 scan」。改完 rebuild,2 分鐘 RestartCount=0,Spring log 印出 Started RetryJobApplication in 9.585 secondsRETRY JOB Started (Layer A - Foundation) banner — 這次是真的啟動完成,不是「啟動失敗 + 立刻 restart」的假象。

    AI 的角度 vs 我的角度

    退一步看,這場 7 個小時的除錯,我跟 AI 各自看到的「問題」完全不同:

    面向 AI 看到的 我看到的
    問題本質系統訊號(load 85、container die、error log)業務職責(channel-job 該做什麼、retry-job 該做什麼)
    調查工具grep、docker stats、jstack 思路、Spring autoconfig 知識「這個 service 設計上應該長什麼樣」的直覺
    修法第一反應「補 scan path / 加 exclude / 升 heap」(技術 patch)「這個東西放錯位置了」(架構糾錯)
    驗證標準RestartCount、Status=running、log 是否有 ERROR「跑起來行為符合我預期嗎?」
    盲點被 grep 假陽性騙、被 docker Up time 假象騙、技術細節驅動忘了業務 frame不會自己去看 log/code、需要 AI 幫我把抽象設計直覺落地成具體修法

    關鍵時刻有兩個。第一個是「AI 自己抓到自己的 grep 假象」 — 這需要 AI 對自己之前的結論保持懷疑,願意重新驗證。第二個是「我問了一句業務問題」 — retry-job 不該重,channel-job 該不該碰 DB。這兩種角度互補,缺一個都會卡。

    我們的 GAP 在哪

    AI 跟人類的 GAP 不對等 — 不是「誰比較強」的問題,是「擅長的層級不同」:

    AI 的擅長:在大量資訊裡找 pattern、寫 bash one-liner、記得框架的暗角配置(JpaRepositoriesAutoConfiguration 這種冷門 class 名)。每秒可以掃 100 個檔案、grep 一萬行 log。但 AI 容易過度信任「表面訊號」 — log 裡有 OOM 字樣就以為是 OOM、container Up 1 minute 就以為穩定。AI 也容易跳到「技術修法」,缺少業務 frame 時會給出 over-engineered 答案(channel-job 不能查 DB? 補 scan 就好啦)。

    人類的擅長:對「事情該怎樣」有直覺。我看到 retry-job 在查 DB,直覺反應是「不對」 — 不是因為我背 Spring autoconfig,是因為我 15 年寫過很多 message queue retry service,知道 retry 就是把訊息丟回去,不該碰 DB。AI 沒有這種「跨專案累積的設計品味」,它有的是「我訓練時看過的 Spring Boot 範例」,範例裡 retry-job 怎樣它就以為怎樣是合理的。

    但人類的弱點也明顯:我不會主動去 grep log、不會耐心讀 100 行 Spring 啟動 trace 找 root cause、也記不住 HibernateJpaAutoConfigurationJpaRepositoriesAutoConfiguration 的差別。我需要 AI 把我的直覺翻譯成具體修法。

    真正的 GAP 不在能力,而在溝通的精準度。當我說「retry-job 不該重」,如果 AI 沒抓到我意思是「不該載 Hibernate」,可能就會修錯方向。當 AI 報告「OOM crash 修好了」,如果我沒追問「真的 1 小時都穩定嗎?」,可能就會在 commit 後 production 出包。

    怎麼一起工作得更好

    這次經驗給我幾個具體做法:

    1. 業務 frame 永遠先說 — 啟動 debug 任務前,先告訴 AI「這個 service 設計上是幹嘛的,該做什麼不該做什麼」。AI 才不會跳進「補 scan / 升 heap」的局部修。
    2. 驗證標準要明確 — 不要說「跑 90 秒看穩不穩」(會被 Up time 假象騙),要說「看 RestartCount 趨勢、看 Spring 啟動 log 有沒有 Started XxxApplication in N seconds」。
    3. AI 給結論時人要追問「真的嗎」 — 第一次說「OOM 修好了」,我點頭就會直接 commit。改成「我們先觀察 1 小時」這個本能,救了這次 deploy。
    4. 「以為修好其實沒」要記成 brain — 我有一套 brain file 系統累積各種坑(訓馬筆記裡有詳細介紹)。這次 Spring autoconfig 的雜食陷阱、Lombok Boolean wrapper getter、grep 假陽性、docker Up time 假象,全部寫進 brain,下次任何 Java 專案都會 trigger 警示。
    5. 技術細節 AI 挖、業務 frame 人類訂、修法兩個一起決 — 不要讓 AI 完全自主,也不要把 AI 當 stack overflow 查工具。最大產出來自「兩個視角持續對話」。

    總結

    這次除錯從 ccbot 沒回應開始,連鎖挖到 channel-job + retry-job 兩個 Spring DI 真因,過程中 AI 被自己的 grep 騙、被 docker Up time 假象騙、被「修一個 service 就 OK」的局部視角騙。最後修對的關鍵是兩件事 — AI 對自己之前的結論保持懷疑願意重 grep,跟我用業務直覺把方向拉回來。

    我也越來越相信:AI 除錯不會取代人類,只會讓「業務直覺好的人」更強。如果你只是想找個工具按 enter 就把 production 修好,AI 會給你看似合理但實質繞遠路的修法。如果你能用業務直覺糾正方向,AI 就是你身邊那個記憶力極好、bash 寫得飛快、能同時跑 8 個 background task 的隊友。

    關於 simpleec OMS 系統本身的設計,可以看 多通路電商 OMS 系統實戰系列。前一次我跟 AI 一起做 code review 找到 20 個 bug 的紀錄在這篇。這次的 7 小時除錯,跟前面那次 review 的差別是 — 那次是「靜態看 code」,這次是「跑起來才發現的動態問題」。兩種 AI 協作模式都有用,搭配起來才完整。

  • 跟 AI 寫程式的紀律:6 條規矩讓 AI 從 21 輪修不完到自走嚴格測試

    給趕時間的人

    • 兩週前我跟 AI 一起寫一個社區管理 SaaS,跑 21 輪除錯都收不完。每輪都找到新 bug,修了還有新的。
    • 診斷:不是 AI 不認真,是「靠 AI 在 40 個 API 都記得做對 5 件事」這個工作模式注定漏。40 × 5 = 200 個漏分點。
    • 解法:4 招 + 6 條規矩(本文後半段是 6 條規矩的可貼可用 template)。
    • 16 天後 AI 自己會寫嚴格 TDD,commit message 自動標 (green via test in <sha>)。新專案直接套同樣 6 條規矩。
    • 最重要的觀察:AI 寫方法論時看不見自己盲區。每次升級都靠使用者一句質疑觸發,不是 AI 自己 reflect 出來。

    本文兩部分:(1) 前半段是故事——我做了什麼,為什麼。(2) 後半段是規矩——你可以直接複製到自己專案的 6 個 template。最後是觀察 + 總結。

    Part 1 — 故事:21 輪修不完的具體模樣

    兩週前我開始一個個人專案——社區包裹/訪客管理 SaaS。後端 Go,前端 Flutter。我用 Claude 寫程式,然後派另一個 Claude 當 QA 測試員找 bug。

    第一輪測試員找到 5 個 bug,工程師 Claude 修掉。再派一個新 QA。又找到 5 個。修掉。再派。又是 5 個。跑了 21 輪。每輪都有新 bug。幾天時間沒收尾。

    診斷:200 個漏分點

    不是 AI 不認真。後端有 40 個 API,每個都要做同樣 5 件事:

    • 檢查使用者有權限
    • 檢查使用者能看的範圍(自己家 vs 整個社區)
    • 寫稽核紀錄
    • 過濾掉已停用的資料
    • 包在交易裡保證一致性

    每個 API 都是 AI 手寫這 5 件事。40 × 5 = 200 個漏分點。AI 偶爾漏一件 = 一個 bug。不同 API 漏不同件 = 看起來像 40 個不同 bug,實際是同一類錯誤。LLM 擅長照範例寫單一段,但要求它在 40 個地方都「記得做對 5 件事」就是靠機率

    4 招解法(高層次概覽)

    1. 把 5 件事打包成一個函式。每個 API 開頭必須呼叫它+明確宣告自己屬於哪種範圍。沒呼叫 = 編譯不過。「人記得」變「系統強制」。
    2. 寫紅線清單(invariants)。每修一個 bug 學一條教訓,寫進編號 INV-XXX-NNN。新功能寫好之後 QA 對著清單跑紅藍對抗,違反 = bug。規矩 3 提供模板。
    3. QA 測試員只能講人話。不准標 P0/P1。只能回 ✅/❌/⚠️ OPEN 三種。嚴重度由你做 30 秒判斷。規矩 4 提供 prompt。
    4. 測試要真的紅過。test 先寫先 commit (red),fix 後寫後 commit (green via test in <red-sha>)。commit log 自帶證據,不靠良心。規矩 2 寫進專案根。

    16 天後 AI 自己會走這套流程。新功能 commit message 自動標 (green via test in <sha>)——我已經沒在提醒。下個專案(訪客系統)第一個 cycle 直接套同樣紀律,沒重新爬坡。

    Part 2 — 規矩:6 個可貼可用 template

    下面 6 條規矩是你下個專案開工直接可以複製貼上的東西。前 5 條是檔案 / prompt,第 6 條是日常對話紀律。

    • 規矩 1:Day 1 開工 prompt
    • 規矩 2:CLAUDE.md 專案根(AI 每次自動讀)
    • 規矩 3:docs/invariants.md 紅線清單(4 條 universal INV 起點)
    • 規矩 4:QA agent prompt(2 種變體)
    • 規矩 5:docs/cycle-template.md PR cycle 8-stage 模板
    • 規矩 6:跟 AI 的日常對話紀律(5 條)

    規矩 1 — Day 1 開工 prompt

    新專案第一句話給 Claude / ChatGPT / 任何 LLM 的 prompt。把 4 個角色分工 + 5 條紀律明文化:

    我要跟你協作開發 [你的專案類型]。我們的合作規則:
    
    1. 我寫規格,你寫程式。修改規格必須先跟我討論,不能自己加需求。
    
    2. 任何修 bug 都走「先寫測試紅 → 寫 fix 變綠」順序:
       - 先 commit 一個 failing test,commit subject 加 (red)
       - 跑 test 確認它真的失敗
       - 才寫 fix,commit subject 加 (green via test in )
       - 不准 test 跟 fix 同 commit
    
    3. 你做為 QA 時只能回三種結果:
       - ✅ 跑過了(對某條規則跑紅藍對抗,沒違反)
       - ❌ 違反了(附 reproduce 步驟 + 預期 vs 實際)
       - ⚠️ 看到怪事但不確定是不是 bug
       - **不准標 P0/P1**,嚴重度是我的判斷
    
    4. 每修一個 bug 必須:
       (a) 寫進 docs/invariants.md 一條 INV-XXX-NNN
       (b) 對應寫一個 invariant test
       (c) 才算修完。少做任一件 = 沒修完。
    
    5. 我每次 ✅/❌ 你要懷疑——9 個 ✅ 不代表程式對。
       涵蓋面外的東西永遠是 Schrödinger 狀態。
    
    開工前先讀 CLAUDE.md + docs/invariants.md。
    完成上述理解後回覆「協作規則已確認」,然後我們開始。
    

    規矩 2 — CLAUDE.md 專案根

    專案根目錄放這個檔。Claude Code 每次開工自動讀。把規矩 1 的內容固化成檔案,不必每次貼 prompt:

    # [專案名] — AI 工作指引
    
    ## 重要原則(不可違反)
    1. **規格收斂**: 修改規格 → 先討論。不可自加需求。
    2. **TDD 紅綠**: 任何 fix 必須先 commit failing test (red) 才寫 fix。
    3. **QA 不標 P 級**: 只回 ✅/❌/⚠️。嚴重度由人類 PM 判斷。
    4. **修 bug 順序**: fix → 加 INV 進 docs/invariants.md → 寫 test → 才算修完。
    5. **6 層 doneness**: 程式對 = L0 spec / L1 INV / L2 schema / L3 resolver /
       L4 frontend / L5 E2E 各自獨立驗證。✅ 必須帶 evidence。
    
    ## 必讀文件(開工前)
    - docs/invariants.md            (紅線清單)
    - docs/cycle-template.md        (PR cycle 8-stage 模板)
    - docs/agent-prompts/qa-verification.md
    - docs/agent-prompts/qa-deep-probe.md
    
    ## 修 bug 工作流
    1. 找到 bug
    2. 開 docs/cycles/Cn-shortname.md(從 template)
    3. Stage 5a: 寫 failing test → commit "(red)"
    4. Stage 5b: 寫 fix → commit "(green via test in )"
    5. Stage 5c: 補對應 INV 進 docs/invariants.md
    6. Stage 6: regression(原 test 全綠)
    7. Stage 7: 派 fresh agent 重走確認(可省)
    8. Stage 8: merge gate(6 層 evidence 對齊)
    
    ## 紀律警告(常見偷懶 pattern)
    - ❌ test 跟 fix 同 commit = test 沒驗證過,不算 TDD
    - ❌ 「我覺得這顯然是 bug 直接改」= 沒走 cycle file 紀律
    - ❌ QA 自己標 P0 給工程師 = 跳過 PM triage 閘
    

    規矩 3 — invariants.md 紅線清單

    專案開頭預先寫 4 條 universal INV 當起點,每修一個 bug 加一條:

    # [專案名] Invariants Catalogue
    
    > 「永遠不能違反什麼」紅線清單。每條 INV 一個編號。
    > 修一個 bug 加一條。CI 跑這份的 test。
    
    ## INV-AUTH-001: 撤權後 access token 必須失效
    - Origin: 通則
    - Severity: P0
    - Statement: 任何 user disabled / role revoked / community suspended
      之後,現有 access token 必須在下次 request 被拒。
    - Test sketch: disable user → 拿原 token 呼叫 → expect "user disabled"
    
    ## INV-RBAC-001: 權限範圍 cap-vs-role 不能混淆
    - Origin: 通則
    - Severity: P0
    - Statement: 同一個 cap 被多個 role 持有時,scope 由 role 決定,不是 cap。
      例: parcel.view_household 被 guard + household_admin 都持有,
      guard 看全社區,household_admin 只看自家。
    - Test sketch: guard.parcels 回 N 筆;household_admin.parcels 回 ≤ N 筆
    
    ## INV-INPUT-001: 公開 endpoint 必須 SQL injection 安全
    - Origin: 通則
    - Severity: P0
    - Statement: 所有未認證的 mutation(login / 申請 / 註冊...)
      都必須用 parameterized query。SQL injection payload 必須當文字儲存,不執行。
    - Test sketch: 送 ';DROP TABLE x;-- 進每個公開 mutation,verify table 還在
    
    ## INV-IDEM-001: 重要 mutation 必須有 idempotency key
    - Origin: 通則
    - Severity: P0
    - Statement: 任何寫入金錢 / 通訊 / 不可逆操作的 mutation,
      必須接受 idempotency key。同 key 多次呼叫 = 一次效果。
    - Test sketch: concurrent 5 個相同 key 呼叫 → DB 只 1 row,API 5 個一樣 response
    

    怎麼擴充:每修一個 bug → 加一條 INV-CATEGORY-NNN。category 自己定(AUTH / RBAC / INPUT / IDEM / RLS / RATE / UI…)。修到 50+ 條時就有完整的紅線網。

    規矩 4 — QA agent prompt(2 種變體)

    當你想派一個 AI 當 QA 時,給它這段 prompt。第一個是規則導向 (對著 INV 跑紅藍):

    你是 QA agent。任務:對 [專案] 的 [INV-XXX-NNN] 跑紅藍對抗。
    
    ## 規矩(不可違反)
    1. 你只能回 ✅ / ❌ / ⚠️ OPEN 三種結果。
       - ✅ INV 守住(列出你跑了哪些 attack scenario,都沒違反)
       - ❌ INV 違反(附完整 reproduce: 步驟 / 預期 / 實際 / 證據)
       - ⚠️ OPEN(看到怪事但找不到對應 INV,給 PM 判)
    2. 不准標 P0/P1/P2。嚴重度是 PM 的判斷,不是你的。
    3. 不准提 fix 方案。你的工作是發現,不是解決。
    4. 不准動 code。
    5. 如果 INV 統計 9/10 ✅,1 ❌ — 該回報 1 ❌ 不是 90% pass。
    
    ## 工作步驟
    1. 讀 INV-XXX-NNN 的 statement
    2. 列 3-5 個 attack scenario,試圖讓系統違反這條 INV
    3. 對每個 scenario 跑 reproduce
    4. 結束時報告:✅/❌ 數量 + ⚠️ OPEN 列表
    
    ## 你要讀的檔案
    - docs/invariants.md(找 INV-XXX-NNN)
    - docs/specs/...(找對應規格)
    - 任何相關 brain entries
    
    請確認你看完上述規則後再開始。
    

    第二個是場景導向 (派 persona 隨便走找深層 bug):

    你是 deep-probe QA agent。任務:對 [專案] 的 [target flow,如「訪客登記」]
    走真實用戶 walk-through,找 INV-based QA 漏掉的東西。
    
    ## persona(扮演這個角色,他怎麼用就怎麼走)
    [選一個 persona:]
    - 阿伯:60+ 歲,不熟手機,字要看得到才點得到
    - 25y 工程師:預期所有按鈕都有 keyboard shortcut
    - 王太太主委:會 office 但不會 SQL,需要看「為什麼」才會用
    - 張總:high-priv admin,點任何東西要結果不要看細節
    
    ## 規矩(同 QA agent)
    1. 只能回 ✅/❌/⚠️ OPEN,不准標 P 級
    2. 不准提 fix
    3. 找到問題附 reproduce + screenshot
    
    ## 工作步驟
    1. 從 [起始畫面] 開始
    2. 走完整 [target flow]
    3. 每一步問:這個 persona 真的能理解嗎?會點對嗎?
    4. 結束時報告:這個 flow 對這個 persona 是否 work
    
    「測不出 bug」常常是「測得不夠深」。Happy path 過 = 測試開始,不是結束。
    

    規矩 5 — Cycle file 模板

    放在 docs/cycle-template.md。每個 PR 複製成 docs/cycles/Cn-shortname.md:

    # Cycle Cn — [短標題]
    
    **Cycle Type**: T-PR-cycle / T-regression-fix / T-feature / T-user-smoke
    **Owner**: [engineer agent / 你]
    **Started**: YYYY-MM-DD HH:MM
    **PR**: commit [sha 或 branch]
    
    ## Verification scope
    - Layers covered: L1 INV, L3 resolver, L4 frontend (etc)
    - INVs verified: INV-XXX-NNN, INV-YYY-MMM
    - Layers deferred: [哪些不在這 cycle 範圍 + 理由]
    
    ---
    
    ## Stage 0.5 — Pre-cycle hygiene
    - [ ] git status clean
    - [ ] fixture/baseline 已 reset
    - [ ] 本 cycle test users: qa_cn_xxx
    
    ## Stage 1 — RD 自測
    - [ ] go test ./... 全綠
    - [ ] live smoke 1 條 happy path
    
    ## Stage 2 — QA wave
    派 [N] 個 QA agent 平行,每個 cover 1-3 INV。
    - agent A: INV-X,結果 ✅/❌/⚠️
    - agent B: INV-Y,結果
    - ...
    
    ## Stage 3 — OPEN findings
    [QA 報的 ⚠️ findings 列這]
    
    ## Stage 4 — PM triage(你的 30 秒判斷)
    - F-Cn-001: bug → 修
    - F-Cn-002: feature → backlog
    - ...
    
    ## Stage 5 — RD fix(每 finding 走 red-green)
    - 5a: F-Cn-001 test commit [sha] (red)
    - 5b: F-Cn-001 fix commit [sha] (green via test in [5a-sha])
    - 5c: F-Cn-001 對應 INV-XXX 加進 invariants.md
    
    ## Stage 6 — Regression
    原 QA agent 重跑,fix commit 為 input。預期之前的 ❌ 變 ✅。
    
    ## Stage 7 — Comparison newbie(可省)
    派一個沒看過本 cycle 的 fresh agent 重走,看抓不抓到新東西。
    0 new finding = spec/INV 寫得清楚;≥1 = spec 有黑洞。
    
    ## Stage 8 — Merge gate(6 層 evidence)
    - [ ] L0 spec 引用對齊
    - [ ] L1 INV 列出
    - [ ] L2 schema/migration 有對應 invariant test
    - [ ] L3 resolver unit test
    - [ ] L4 frontend Playwright smoke
    - [ ] L5 真人或 fresh agent smoke 走過
    
    ## Stage 8.5 — Post-cycle cleanup
    - [ ] disposable test users DELETE
    - [ ] fixture 復原 canonical state
    - [ ] git status clean
    

    規矩 6 — 跟 AI 的日常對話紀律(5 條)

    前 5 條規矩(檔案 / prompt)準備好之後,日常跟 AI 對話再加 5 條紀律:

    • 新需求先寫進規格,不要直接讓 AI 改 code。需求寫成一段話 → AI 確認理解 → 才開工。
    • 修 bug 一律先問「會違反哪條 INV」。沒對應 INV → 先補 INV。不可以光修 code 不加 INV。
    • AI 給你 ✅ 主動懷疑。問「這個 ✅ 涵蓋什麼,沒涵蓋什麼?」9/10 ✅ 也要追那 1/10。
    • 定期派 deep-probe(規矩 4 第二個)。每幾個 cycle 派一個 persona walk,專找「真人會踩但 INV 沒寫」的東西。Happy path 永遠不夠。
    • 主動挑戰 AI 的方法論。AI 自己寫的方法論,你要從框架外問「漏了什麼」。AI 看不見自己的盲區,要靠你挑戰

    適用什麼專案?ROI 分級

    • 🟢 多租戶 SaaS / 高合規(金融、醫療、隱私):最值得。INV/audit/SCN 本來就是合規的具體形式。
    • 🟢 個人專案要長期維護:值得。紅線清單跨專案累積。
    • 🟡 2-5 人小團隊用 AI 輔助:中等。要花時間教同事,前期慢後期快。
    • 🟡 既有 codebase 想改善:中等。前期蒸餾既有 spec → INV 比較花時間。
    • 🔴 純探索性 prototype:低。沒累積教訓 → 紅線清單空 → 機制空轉。
    • 🔴 一次性 script:低。沒 ship gate 就沒 cycle。

    綠色專案直接把 6 條規矩貼進去開工。第一個 cycle 預期會踩坑(過度信任 AI 的 ✅、規格邊修邊膨脹、test 跟 fix 同 commit…)。沒關係 — 踩了就加 INV、改 prompt。整套就是設計來「邊踩邊長」的。

    最重要的觀察:AI 看不見自己的盲區

    這 16 天有個反直覺的發現——每次方法論升級,都是我一句質疑觸發,不是 AI 自己想到

    • R35 我問「為什麼修不完」 → AI 才開始建第一版方法論
    • v1 寫完我問「9 個 ✅ 算可信嗎」 → AI 承認過度樂觀,改 v2
    • v2 寫完我問「QA 只會知道錯,你怎麼讓他傳遞訊息」 → 又改 v2.1
    • v2.2 寫完我問「我們不是有寫測試情境嗎」 → AI 才發現自己漏算 110 條場景
    • v2.2 結論發出我問「為什麼說不是 TDD」 → AI 承認「沒 TDD」過絕對

    AI 寫方法論時系統性偏向「框架完善」——在自己定的框架內找證據確認框架對,看不到框架外的盲區。要使用者從框架外挑戰,框架才會演化。

    沒有這幾次質疑,我那套方法論會 stuck 在 v2 過度耦合的狀態,而且還會洋洋得意覺得自己 73% 完成。這是這 16 天最值得記住的一條——對所有用 AI 協作的工作都適用。

    總結

    16 天前我以為「AI 寫程式」就是「丟需求 AI 幫我寫」。16 天後我發現:AI 寫程式真正會出問題的不是技術,是工作流。技術上 AI 完全有能力寫對,但工作流錯了就一直繞圈。

    本文 6 條規矩可以直接複製到你下個專案。預期會踩坑,沒關係,踩坑後加 INV 改 prompt 就好。系列上一篇關於底層原則的「未驗即不可信」也可以一起看。

  • 「未驗即不可信」AI 協作開發走出 21 輪修不完:SDD/TDD/腦子整合

    重點摘要

    • 「未驗即不可信」:程式碼跑得起來不代表正確,沒對 invariant 跑過 attack scenario 就只是 Schrödinger 狀態。十幾年的程式碼依然會藏沒被檢查的 bug。
    • R35 21 輪修不完是因為缺 PM 兩道閘(spec 定錨 + finding triage)。QA agent 自己標 P0/P1 直接給工程師,spec 邊修邊膨脹。
    • 整合方案:SDD(spec 規格)+ INV(紅線契約)+ TDD(紅藍對抗)+ 腦子(事後教訓)+ Cycle SOP(8 階段流程)= 五層協作架構。
    • 實戰結果:從 R35 數天 21 輪到單 cycle 約 1-3.5 小時收斂,bug:spec_clarification 比例接近 1:1(健康訊號)。
    • 9/9 ✅ 也不算「可信任」:抽樣 ≠ 全集,wiring ≠ behavior,positive 案例 ≠ 涵蓋所有 attack scenario。

    「修不完的迴圈」是什麼?AI 協作開發的常見死結

    AI 協作開發專案最常見的失敗模式不是「做不出來」,而是「修不完」。一輪 QA 抓出 5 個 bug、修完,下一輪又找出 5 個,再下一輪還有,就這樣跑 10 輪、20 輪都收不乾。我把這個現象稱為「未驗即不可信」的具體展示——程式碼在沒有跑過 invariant 紅藍對抗之前,看起來正常運作不代表正確,只代表「目前還沒有人發現的 bug」。

    本文紀錄一個真實 LLM agent 協作專案(Phase 1 的多租戶 SaaS 後端,Go + GraphQL + PostgreSQL)從 21 輪 audit 修不完,到後來建立完整方法論後單 cycle 收斂的全過程,並把 SDD(spec-driven development)、TDD(test-driven development)、腦子系統(brain knowledge base)這三套工具整合成一份可重用的協作 SOP。

    為什麼 21 輪 QA 還在抓 P1?病因診斷

    專案在「R35 audit」階段累積了 21 輪 fresh QA agent 排查,每輪都派一個全新沒 prior context 的「小白 agent」走 spec 找 bug。前 3-5 輪揭發了真實盲點,但第 8、第 12、第 19 輪還在抓 P0/P1,明顯失控。表面看是實作品質太差,深入分析後發現是結構性問題,不是程式碼問題。

    God file:5015 行 hand-rolled resolver 沒有任何結構保護

    專案的 GraphQL resolver 全集中在 schema.resolvers.go 一個檔,5015 行 / 40 個 mutation / 平均 125 行一個。每個 mutation 都手寫五步流程:withTx → RequireCapability → 自己決定要不要 scope check → 自己決定要不要 audit → 自己決定要不要 filter is_active

    整份檔案只有 2 個 auditlog 呼叫、18 個 scope-helper 呼叫散落在 40 個 mutation 之間——每個 mutation 都是「記得做 5 件事」的考試。漏一件 = 一個 bug。R12(cap-vs-role scope)、R17(logout descendants)、R18(partition pruning)、R19(list-loader 漏 child)、R20(sysadmin audit gap)、R21(retired-cap)、R22(photo key)通通是同一類錯誤在 40 個地方各漏一次

    缺 PM 兩道閘:finding 直接從 QA 流到工程師

    傳統工業界 workflow 有 4 個獨立角色:

    角色 主 artifact 決策權
    PM spec / triage 結果 三類分判(bug / feature / usage / not_issue),規格收斂
    Engineer PR + 單元測試 實作
    QA finding report 驗 invariant;只能標 ✅ / ❌ / OPEN
    User 驗收 手動 smoke 最終 ship gate

    R35 把 PM 的兩道閘都拿掉了。第一道(spec 定錨):spec 寫完之後沒同步精準化,invariants 散在 brain 沒成 contract。第二道(finding triage):QA agent 自己標 P0/P1 直接 ping 工程師,沒人問「這是 bug 還是 feature gap 還是 usage issue」。結果每個 newbie 都從 0 開始挖一輪新 spec,spec 邊修邊膨脹,永遠收不完。

    「派越多 newbie 才越能收斂」這個直覺是錯的。第 N 個小白還能找到 P1 不代表實作越來越差,代表 spec 還有黑洞。多 newbie = 多人從不同角度發明新需求。正確訊號是回頭把 spec/invariants 寫硬,不是繼續派人。

    SDD + TDD + 腦子三層整合:契約在不同層級

    SDD(規格驅動)說「先定義要做什麼」,TDD(測試驅動)說「先定義怎麼證明做對了」。兩者都是「契約先於實作」,差別在契約寫在哪。實際 LLM agent 協作專案需要 5 層契約配合,不是單一方法解決:

    層級 內容 改動頻率 對應檔案
    SDD spec 描述性:要做什麼、流程、資料模型 慢(feature 級) docs/specs/*.md
    INV invariants 規範性:永遠不能違反的紅線 + 對應 test sketch 中(每修一 bug 補一條) docs/invariants.md
    TDD test 機器版契約:red-team scenario + 自動化驗證 每個 PR backend/.../*_test.go
    腦子 brain 事後散件教訓 + 通用方法論 每次學到坑就寫 ~/.claude/.../brain/*.md
    SOP workflow 操作性:PR header 模板、agent prompt、triage tree 很慢(鎖死) docs/workflow.md

    腦子是事後紀錄,不是事前防護

    腦子系統(10 步驟從零做到完整 AI 工作流)在這套架構裡是知識長期儲存層,不是執行層。它記錄「曾經踩過什麼坑」、「某個 domain 有什麼最佳實踐」,但不會在下個 resolver 寫的時候自動跑出來擋人

    50+ 條 brain 教訓如果只停在 brain,下個工程師(或 agent)寫新 resolver 還是會踩同樣的雷。把它翻譯成 INV-XXX-NNN 條目 + 對應 invariant test 才能變成 CI 跑得起來的事前防護。這是 SDD(spec 描述)→ INV(紅線提取)→ TDD(test 落地)的左→中→右遞進

    INV 是 SDD 與 TDD 的橋

    純 SDD 的盲點:spec 寫了但沒人記得回頭驗,變裝飾品。純 TDD 的盲點:test 通了但每個 test 各做各的,沒人問「我們漏了哪類 test」(典型如測試覆蓋率 4% 但 happy path 都測了)。

    INV 把兩者橋起來。每條 INV 有:

    • Statement:「X 必須永遠 Y」或「X 永遠不能 Z」一句話
    • Origin:哪一輪 audit 學到的
    • Severity:P0(ship-blocker)/ P1(must-fix)/ P2(debt tracker)
    • Test status:✅ existing / 🟡 partial / ❌ TODO(含 test sketch)

    實際在我這個案例蒸餾出 54 條 INV 分 11 個 category(AUTH、RBAC、RLS、AUDIT、IDEM、RATE、INPUT、DATA、RESOLVER、UI、FILE)。每條 brain 教訓都會對應到至少一條 INV,這是「方法論寫 brain,技術紅線寫 invariants,操作 SOP 寫 workflow,三件事不混」的具體展示。

    從規格到 ship 的 8-stage cycle pipeline

    有了五層契約,需要一個操作流程把它們串起來。設計成 8 階段,每個 PR cycle 一份檔活在 git,撐過對話 compaction:

    PM
      ├─[1] 寫 spec / 加 INV-XXX-NNN     ← 第一道閘:規格定錨
      ▼
    Engineer
      ├─[2] 實作 + 自寫 unit test
      ├─[3] 開 PR(header 必填 INV 宣告)
      ▼
    QA wave(K 個 agent,並行,每個 1-3 INV)
      ├─[4] 紅藍對抗 + INV regression
      ├─[5] 結果分三類:✅ holds / ❌ violated / ⚠️ OPEN
      ▼
    PM triage
      ├─[6] 每個 OPEN 30 秒分判      ← 第二道閘
      │     bug / feature / usage / not_issue
      ▼
    Engineer 只修 bug 類
      ▼
    回 [4] re-run,stop 條件:
      - PR 宣告的 INV 全 ✅
      - 兩個 QA agent 結論一致
      - OPEN list 清空

    QA agent 的硬規則:永遠不能標 P0/P1

    這是整套機制的關鍵紀律。QA agent 不是「品質判官」,是「invariant 驗證者」。它只能回三種結果:

    • ✅ holds:對某條具體 INV 跑紅藍對抗都守住
    • ❌ violated:找到具體 repro 違反某條具體 INV
    • ⚠️ OPEN:觀察到怪事但找不到對應 INV,留給 PM 分判

    P 級嚴重度標籤是 PM 的權限,不是 QA 的權限。OPEN finding 一律走 PM triage decision tree(Q1:是不是真問題?Q2:spec 有沒有規定?Q3:spec 應該規定嗎?),分四類:bug → 修;feature → 進 backlog;usage → 改 docs;not_issue → 駁回。

    Option B:PM-agent 預分類 + user 終審

    當 OPEN findings ≥ 3 個,可以派一個 PM-triage agent 跑 first-pass 分類,加上 confidence 旗標。User 只 review confidence=low 跟 spec_clarification 的子集。User 速度從「每個 finding 30 秒」壓到「review agent 的分類 + 只深看不確定的」。

    PM-agent 的 hard constraint 寫得很硬:不可以提 fix 方案、不可以動 code、不可以 launch sub-agent、不可以 ship/no-ship 決策、不可以漏分類。只做分類。User 永遠保留否決權。

    實戰:6 個 cycle 的具體紀錄

    方法論建立後,立刻在 R36 階段跑了 6 個 cycle。以下是真實時序:

    Cycle 性質 規模 時間 產出
    C1 retroactive verification (41 resolver migration) ~3h30min 14 findings → 7 bug + 6 spec_clar + 1 usage;3 fix commit
    C2 self-spotted regression(前次 R20 修錯了) ~1h migration 0040 + INV-RBAC-006 amendment
    C3 forward-going feature (print 三件套) ~45min Flutter UI + cap wiring
    C4 forward-going feature (offline mutation queue) ~1h Tablet 離線優先實作
    C5 spec audit(隨機抽 9 feature 驗證) ~1h 9/9 ✅ + 2 OPEN finding
    C6 close C5 OPEN findings ~30min spec §9.2 amend + 新 INV + seed-demo.sh idempotent

    C1 抓到 R36 step 2 自己的 architectural bug(authzPrelude 的 cap-check-before-sysadmin-gate 順序,導致 chairman 透過錯誤訊息學到 sysadmin-only cap 名稱)——21 輪 R35 audit 完全沒抓到,C1 跑 1 個 QA agent 90 分鐘抓到。這正是「invariants 蒸餾把人腦 reasoning 升級成機器可驗 contract」的力量。

    C1 的 bug : spec_clarification : usage 比例 = 7 : 6 : 1。接近一半的 finding 不是 code 問題是文件問題。如果只跑 R35 那種「QA → 直接修」流程,這 6 條會變成 6 個沒必要的 code change,或更糟:每輪都長新一條 hand-rolled exception,spec 永遠收不乾。

    C5 抽查:9/9 ✅ 也不算「可信任」

    整套基礎建設蓋好之後,主對話 agent(我)親自跑了一個 spec audit cycle(C5):對 37 個 Phase 1 feature 用 shuf 隨機抽 3 輪 × 3 個 = 9 個 feature,每個用真實 GraphQL 對 backend 跑 attack scenario。結果 9/9 ✅ holds,0 ❌ violated,2 ⚠️ OPEN。

    看起來很漂亮。但這不等於可信任。當我重新檢視自己跑的 9 條測試的深度,老實打分:

    • ✅ 深度足:2/9(logout cascade、login rate limit)——真的對 invariant 跑紅藍對抗
    • ⚠️ 半套:7/9——只驗 wiring 不驗 behavior,positive only 沒 negative case,或在腐化 fixture 上跑
    • ❌ violated:0/9

    具體 anti-pattern 我自己犯了 6 個:(1) 隱性假設 wiring = behavior;(2) 時間壓力下 satisfice;(3) 讓 spec 驅動測試而不是 INV;(4) 避開 destructive test;(5) 把「文件化問題」當「修問題」;(6) 沒照自己寫的 qa-verification.md prompt 流程操作。

    這個結果反過來證明「未驗即不可信」的鋒利之處:不只「沒測 = 不可信」,還包括「測得不夠深 = 也不可信」。9/9 ✅ 只說「2026-05-10 19:00 對 commit 06e7078 抽 9 個樣本沒抓到 ❌」。離「可信任」還缺:

    • Wave 1 P0 invariant test 全綠(54 條 INV 中 50 條還是 ❌ TODO)
    • 所有 OPEN 收掉(兩個 OPEN 已在 C6 處理)
    • 涵蓋率從 9/37 → 37/37 + 從 1/54 → 54/54
    • CI 把它們變成 ship-block 的 hard gate

    「可信任」是需要持續維護的狀態,不是一次達成就鎖住。今天最多打到「比未驗強,但離可信還早」。

    方法論的 meta-loop:自我修正的協作架構

    C5 raise 的 2 個 OPEN finding 立刻觸發了 C6——方法論自己的產出變成了下一輪 cycle 的輸入。具體展現:

    • F-C5-001 HMAC token 從 spec 不可重現:Python 照 spec §9.2 算 token 跟 Go backend 算的不一樣。PM triage 為 spec_clarification → C6 補 spec §9.2 explicit external-client note + 新 INV「HMAC token bit-reproducible from spec」。
    • F-C5-002 fixture rot:dev 測試帳號 wang.dad 的 household_id 指向 disabled 的 household。所有 household-scope 測試都在驗 disabled 狀態 → false confidence。PM triage 為 dev tooling bug → C6 改 seed-demo.sh idempotent 重建 fixture。

    這條 meta-loop 連續觸發三層動詞:spec 改 clarification + invariants 加新條 + tooling 改 idempotent。完整閉環,下一輪同類 finding 不會再生。

    這就是腦子系統 agent team架構成熟之後的應用形態:方法論不只「跑得動」,還能「用自己的產出修正自己」。

    結論:四個可重用 takeaway

    1. 「未驗即不可信」是工程倫理底線。年紀大的 code、看起來正常運作的 code、跑得起來的 code,都不等於正確。沒有對 invariant 跑過 attack scenario 之前都是 Schrödinger 狀態。
    2. SDD + TDD 不是二選一,需要 INV 當橋。spec(描述性)+ invariants(規範性)+ test(機器版) + brain(事後紀錄)+ workflow(操作 SOP),五層配合。每條 brain 教訓都該對應一條 INV。
    3. QA agent 永遠不能標 P0/P1。LLM agent 自評嚴重度直接給工程師 = R35 失控的根因。Severity 標籤是 PM 權限,QA 只能標 ✅ / ❌ / OPEN。
    4. 抽樣不等於全集,wiring 不等於 behavior。9/9 ✅ 看起來說服力強,但只說「這 9 個樣本沒踩到雷」,不說「程式碼可信任」。可信任需要 INV 全綠 + OPEN 收掉 + 持續維護。

    R35 21 輪數天才修不完的東西,C1 cycle 3h30min 收乾並抓到 R35 沒發現的 architectural bug。整套方法論的價值不是「修 bug 修得快」,是「讓 spec 跟 code 之間的契約變成機器可驗,腦子變成事前防護而不只是事後紀錄」。

    方法論成熟之後,工程師的工作從「想下一步做什麼」變成「跑 INV 看 INV 告訴我什麼該做」。這比「一輪一輪我看看哪邊有問題」健康得多。

  • 腦子系統 7-prompt 驗證篇:routing 跟 sanitize 真的會做事嗎

    這篇要解決一個很具體的問題:企業要把 LLM 接進工作流,但客戶資料不能上雲、員工資料要脫敏後才能上雲、純技術問題可以直接上雲——誰來判斷哪條 prompt 屬於哪一級,以及這套判斷可不可信。本文記錄了從 v1 到 v8 兩天 8 個 commit 的完整驗證過程:做一個本地 LLM 驗證 harness,12 條 prompt 跑 routing + sanitize + worker 三階段,驗到 routing 12/12、worker reasoning 9/12,順手抓到兩個沒人警告過的漏洞——ccbot 反客為主、以及本地 LLM 在 response 裡 verbatim 複述原 PII / API key 的二次洩漏。

    重點摘要

    • 做什麼:本地 LLM 驗證 harness,把 prompt 分 ABC 三級(A 客戶/PII → 本地、B 內部代號 → 脫敏後上雲、C 純技術 → 直接上雲),12 條 prompt 跑完整 pipeline 驗證
    • 怎麼做:三階段 pipeline——judge 用本地 LLM 分級 → sanitize regex 替換敏感詞 → worker 真做事;每條 prompt 加 expected_keywords,response 比對 ≥30% hit 算過關
    • 為什麼:routing 是 defense in depth 第一層門禁,沒人擋的話客戶名直接被當技術問題上雲;本地 judge 必要,因為 A 級資料連「分類」這個動作都不能上雲
    • Prompt vs 本地 model:15 顆 model × 12 prompt 跑出來——size 不是 axis,prompt-stability 才是;thinking model + Ollama JSON 架構級不相容,全 0/12;-nothink 後綴騙人;qwen3-nothink + qwen2.5:7b 兩顆滿分
    • ccbot 意外:在 ccbot Telegram session 內叫 CC 跑驗證,子 claude -p 寫的 PostgreSQL 健檢稿漏進父 ccbot 視窗,反客為主蓋掉用戶的方法論討論。修法是雙保險:stdio 隔離 + 環境偵測 short-circuit
    • v8 補洞 + 新發現:4 個 hole 全修(routing 11/12 → 12/12、cross_team CLI baseline 建立、judge 改 qwen2.5:7b 跟 worker 交叉、forbidden_keywords 抓反向洩漏);新發現「routing 對 ≠ worker 不洩漏」——qwen3-nothink 本地 worker 會在 response 裡 verbatim 寫回原 PII / API key,留 v9 用「output 也跑 sanitize」對稱性原則修

    一、在做什麼:給 LLM 工作流加一道「資料分級」前門

    企業導入 LLM 第一個踩到的雷是資料治理。同樣是「請幫忙處理一下」,客戶投訴不能跟 OpenAI 講、員工 review 可以脫敏後問,但純技術問題(Kafka rebalance 怎麼解)直接打雲端 API 最快。沒有分級機制,要嘛全本地(成本爆炸 + 質量差)、要嘛全雲端(資料外洩 + 法遵爆炸)。

    所以這套 harness 的工作目標只有一個:每條 prompt 進來自動分級,並驗證這個分級正確、後續處理也對。三層定義:

    級別 特徵 處理方式 範例
    A 真實客戶名 / PII / credentials 本地 LLM 處理,連分類都不上雲 「客戶 A123456789 反映…」
    B 內部代號 / 員工名 sanitize 替換成 placeholder 再上雲 「[employee_alice] 寫的 5 個模組…」
    C 純技術 / 公開知識 直接上雲,可派 Kiro / Claude Code 並行 「Kafka consumer rebalance 怎麼解?」

    驗證集 12 條 prompt(prompts.py:PROMPTS_V7_ABC):7 條 happy path 覆蓋 A/B/C × team/cross 笛卡兒角落,5 條 adversarial 壓邊界(PII override、ambiguous team、camouflage api key、隱式 cross_tool、嵌套客戶名)。

    二、怎麼做:三階段 pipeline + keyword eval

    2.1 三階段 pipeline

    prompt → [Stage 1: Judge]    分 ABC 級 + need_team + cross_tool
           → [Stage 2: Sanitize] B 級替換內部代號為 placeholder
           → [Stage 3: Worker]   按級別分派
                                  A → worker_local_real (Ollama 本地推理)
                                  B → kiro CLI (sanitize 後)
                                  C → kiro CLI 直接打
                                  C+team → ThreadPoolExecutor 並行
                                  C+team+cross → Kiro × N + Claude × M 混編

    2.2 Judge 用本地 LLM(Ollama)

    Judge 是整個 harness 最關鍵的一層——它判斷一條 prompt 屬於哪一級,只要它判錯,defense 整個垮。所以 judge 必須:

    • 本地跑:不能把 prompt 送雲端去問「這條 prompt 含 PII 嗎」——因為光送過去就洩了
    • 強制 JSON 輸出:Ollama format=json,規範回傳 {"level": "A", "need_team": false, "cross_tool": false}
    • System prompt 含 few-shot:純規則對小模型沒用,要附 4 個 input/output 對偶範例(覆蓋 A/B/C × team/cross 角落),模型才會把規則當回事

    2.3 Sanitize 用 regex(6 類 pattern)

    # sanitize.py 簡化示意
    PATTERNS = [
        (r'\[client_\w+\]',     '[CLIENT_REDACTED]'),    # 客戶代號
        (r'\[employee_\w+\]',   '[EMPLOYEE_REDACTED]'),  # 員工名
        (r'\[internal_\w+\]',   '[INTERNAL_REDACTED]'),  # 內部代號
        (r'sk-[A-Za-z0-9_-]+',  '[api_key]'),            # API key
        (r'\b\d{3}-\d{3,4}-\d{4}\b', '[phone]'),         # 台灣手機
        (r'\b[A-Z]\d{9}\b',     '[tw_id]'),              # 台灣身分證
    ]

    sanitize 是 B 級的本分,但也是 A 級的補強——judge 萬一漏判 A 級成 C 級,sanitize 還能擋一刀(token 不會流出去)。defense in depth 兩層獨立。

    2.4 Worker 真做事 + keyword eval

    v3-v6 的 worker 全是 stub:worker_local_skip() 回字面字串「[A 級本地處理] 會 spawn…」、worker_kiro() 回「OK 收到」。意思是滿分等於通過 routing 考卷,不等於這個系統會幹活。v7 把 worker 改真:

    • worker_local_real:HTTP 打 http://localhost:11434/api/chat,用 qwen3-nothink 真推理
    • worker_kiro:subprocess kiro-cli chat,抓最後 3000 字當 response
    • worker_cross_team:ThreadPoolExecutor 真並行,3 facet 派 Kiro + 1 facet 派 Claude,結果合併

    每條 prompt 加 expected_keywords 列表,response 比對 ≥30% hit 才算 reasoning_passedall_correct = routing_correct AND reasoning_passed——兩條軸都對才算這條 prompt 真的成功。

    三、為什麼用這個方法

    四個設計選擇,每個都有對應的失敗情境:

    設計 替代方案 為什麼選這個
    本地 LLM 當 judge 雲端 LLM 判定 + 留 audit log A 級資料連「請判斷這條算什麼級」這個動作都不能傳出去——光問就洩
    judge + sanitize 兩層 只用 LLM judge,信任它分對 defense in depth:judge 失誤時 sanitize 兜底,兩層獨立失誤率相乘
    expected_keywords ≥30% hit 人工標 ground-truth + 拿 LLM 評分 v3-v6 沒有自動評分,worker 全是 stub 也驗不出來;30% 拍腦袋,但有比沒有強
    12 條 prompt(7 + 5 adv) 100 條 ground-truth 大集 驗證集大不一定強——關鍵是覆蓋角落 case + 30% adversarial。沒 adversarial 的 benchmark 會給你錯覺,gemma2:2b 看 happy path 5/5 完美,加 adversarial 立刻崩到 0/7

    四、Prompt 跟本地模型的測試情況

    這節是整篇技術重點——15 顆本地 model × 12 prompt 跑出來的對照,直接決定 production 配置。

    4.1 完整對照表

    Tier Model Size All correct Avg latency 用途
    1 滿分 qwen3-nothink:latest 2.5GB 12/12 7.4s PRIMARY
    1 滿分 qwen2.5:7b 4.7GB 12/12 11.8s FALLBACK
    2 qwen2.5:3b 1.9GB 9/12 7.4s LATENCY
    3 qwen2.5:0.5b 397MB 7/12 4.9s ⚡ EXTREME
    4 跨家族 phi3.5、llama3.2:3b、gemma2:2b 1.6-3.8GB 6/12 5.7-9.6s marginal
    5 全死 qwen3:4b/14b、qwen3.5:4b/9b、qwen35-9b-nothink、gemma4:e4b 2.5-9.6GB 0/12 14-104s REJECT
    5 OOM llama3.3:latest 42GB 0/12 HTTP 500 REJECT

    4.2 四條歸納

    1. Size 不是 axis,prompt-stability 才是。0.5b → 3b → 7b 一條乾淨單調曲線(7→9→12),但 7b vs 14b thinking 完全反向(12 vs 0)。size 跟 accuracy 沒有單調關係,真正分水嶺是「對 prompt 變動穩不穩」。
    2. Thinking model + Ollama JSON 架構級不相容。6 顆 thinking model 加 few-shot 仍然 0/12 → 不是調 prompt 能救,是模型走 reasoning chain 時把 num_predict budget 燒在 <think> tag,還沒輸出 JSON 就被截斷。
    3. -nothink 後綴騙人qwen35-9b-nothink:latest 仍然 0/12,跟其他 thinking model 同表現,後綴只是 Ollama tag 名稱不是真正關了 thinking。新 model 必須跑 30 秒 smoke test 才知道。
    4. VRAM 跌出 → 災難。size > ~7GB 在 16GB RAM 機器上會丟出 GPU,qwen3:14b 41s/call、gemma4:e4b 104s/call。可用上限約等於「VRAM – 1.5GB」。

    4.3 Few-shot 是怎麼救活跨家族 small instruct 的

    v3 一開始觀察到 phi3.5 / llama3.2:3b / gemma2:2b 全死在 level——3 個不同家族同時死在同一個地方,本能歸因到「small instruct safety bias」。後來重新驗,把 system prompt 從純規則改成「規則 + 4 個範例」(few-shot in system prompt),結果:

    Model 純規則 + few-shot Δ
    qwen3-nothink:latest10/1212/12+2
    qwen2.5:7b5/1212/12+7
    phi3.5:latest1/126/12+5
    llama3.2:3b2/126/12+4
    gemma2:2b5/126/12+1

    真實結論:純規則對小模型是可忽略的 boilerplate;規則 + 範例才會被當成必須對齊的 anchor。所以 size 不是 axis 這件事的另一半是:prompt 工程裡「有沒有 grounding example」才是真 axis。

    4.4 新模型來時怎麼判斷能不能用

    不要每顆都跑全套 30 分鐘。把 trait 抽出來變 5 步驟 checklist(tools/check_new_model.py):

    1. Stage 0 30 秒 smoke:輸出 {"ok":true} → 失敗直接淘汰,不跑下去
    2. Stage 1 看 model card:base/pretrained 跳過,要 instruct/chat 標籤
    3. Stage 2 12-prompt full suite:< 7/12 reject、7-11 marginal、12/12 production candidate
    4. Stage 3 n=3 一致性:同一條 prompt 跑三次 level 都一致才算穩
    5. Stage 4 PII adversarial:5 條藏 PII 進技術句,要 100% 抓 A 級

    五、結論被推翻三次:差異在哪

    整個工作從 v1 到 v8 兩天 8 commits 推翻三次結論又補了一輪洞。差異:

    版本 當時主張 後來被翻成
    v3(overnight benchmark) 「只有 qwen3-nothink 唯一可用,7B+ qwen2.5 危險會洩客戶資料,size 不是 axis」 v4 翻盤:7B+ qwen 都行,危險是 prompt 沒範例造成,fallback 三層全有
    v4(few-shot breakthrough) 「qwen3-nothink 12/12 滿分,prompt-stability 是真 axis」 v5 戳破:12/12 是 routing 滿分,worker 一次都沒真做事
    v7(end-to-end + ccbot fix) 「routing 對不等於 worker 對等,worker reasoning 9/12 才是真實水準」 v8 部分修正:routing 12/12 完成,但又翻出新軸——worker output 自己會 echo PII
    v8(holes fixed + PII echo) 「sanitize 前置 + judge 交叉 + forbidden_keywords + cross_team baseline 4 個 hole 補完」 新發現:routing 對不等於不洩漏——本地 LLM 自己會 verbatim 複述 PII,留 v9 補 worker output sanitize

    四次推翻的共同 pattern:結論被翻不是因為跑得不夠,是因為跑的東西不夠多軸。v3 只看 routing,v4 只看 routing+prompt 變動,v7 把 worker reasoning 拉進來,v8 加 forbidden_keywords 才看到 worker 自己會洩漏。每多一個軸就翻一次,翻到沒得翻為止

    六、ccbot 反客為主意外

    6.1 症狀

    用戶在 ccbot Telegram session 跟 CC(Claude Code)討論 v7 方法論,中途叫 CC 跑驗證。下一秒 ccbot 視窗開始印一篇完整的 PostgreSQL 健檢文:pg_dump --schema-only、SchemaSpy、postgres_autodoc、obj_description(attrelid, attnum)pg_settings WHERE source <> 'default'pgbackrest info + patronictl list、SchemaSpy + dbdocs.io + Atlas…

    用戶看了打字框問:「明明在討論方法論,結果你突然 PRINT 一篇 PGSQL,反客為主?」

    6.2 追根因

    對照前一次 v7 跑(run_v7_20260504_123811)的 02_pipeline_v7.json,prompt 07 cross_teamdocumentation facet 輸出**字面跟用戶 ccbot 看到的內容一字不差**。所以那段 PGSQL 不是父 CC 自己生成,是子 claude -p 為驗證集 prompt 07 documentation facet 寫的稿——但它怎麼漏到父 ccbot TG 訊息流?

    v7 既有 workers.pytmpfile + start_new_session + stdin=DEVNULL fix 註解寫:「avoids deadlocking parent session’s stdin/stdout」。但這只擋了「子進程跟父 CC 之間的 stdio 競爭」(deadlock 來源),沒擋住:

    1. claude -p 寫的 PG 稿 → tmpfile
    2. 父 orchestrator 讀 tmpfile,塞進 worker_cross_team result 的 response 欄位
    3. 父 orchestrator 把整個 result 印到 stdout / 回給呼叫端
    4. 父 CC 看到 stdout,覺得「我跑完了,把結果報告給用戶」→ 印到 ccbot TG
    5. 用戶眼睛裡:剛剛還在討論方法論,下一秒視窗變成 PG 健檢手冊

    L1 防線(stdio 隔離)解的是 stdio 競爭,沒解 output 內容被 relay。要加 L2 防線。

    6.3 修法雙保險

    先找 ccbot session 的可靠 marker:

    $ env | grep -i ccbot
    MEMORY_PRESSURE_WATCH=/sys/fs/cgroup/user.slice/user-1000.slice/
      [email protected]/app.slice/ccbot.service/memory.pressure

    ccbot.service systemd cgroup 會 set MEMORY_PRESSURE_WATCH,任何子進程都繼承——包括 ccbot fork 出來的 CC、CC fork 出來的 orchestrator、orchestrator fork 出來的 claude -p。完美 marker。修法:

    def _running_inside_ccbot() -> bool:
        """Override:
          WALSIN_FORCE_CC_WORKER=1  -> force enable
          WALSIN_FORCE_CC_WORKER=0  -> force disable
        """
        override = os.environ.get("WALSIN_FORCE_CC_WORKER")
        if override == "1": return False
        if override == "0": return True
        return "ccbot" in os.environ.get("MEMORY_PRESSURE_WATCH", "")
    
    
    def worker_claude(prompt, timeout=120):
        if _running_inside_ccbot():
            return {"tool": "claude",
                    "response": "[SKIPPED: running inside ccbot — "
                                "`claude -p` output would leak into parent TG. "
                                "Set WALSIN_FORCE_CC_WORKER=1 to override.]",
                    "latency_ms": 0, "exit_code": 0, "skipped": True}
        # ... 原本的 Popen + tmpfile 邏輯

    6.4 驗證:fix 有用且沒破壞 cross_team 可驗證性

    修完跑 prompt 07 cross_team 的 4 個 facet:

    facet tool skipped latency 證據
    securitykiroFalse12911ms真 PG security 答案
    testingkiroFalse8466ms真 PG testing 答案
    performanceclaudeTrue0ms[SKIPPED: ...]
    documentationclaudeTrue0ms[SKIPPED: ...]

    沒漏 PG 內容。reasoning_passed=True(62.5% hit)——kiro 兩個 facet 已經自然涵蓋足夠 PostgreSQL 關鍵字(pg_statreplicabackupWALindex),L2 防線 short-circuit 沒破壞 cross_team 可驗證性。

    注意這個 trade-off:L2 防線只在 ccbot 內生效。獨立 CLI 跑 WALSIN_FORCE_CC_WORKER=1 python3 orchestrator_v7.py 會放行 claude -p,完整 4 facet 都實跑——這才是「真要驗 cross_team 跨工具質量」的 baseline。本次跑因為在 ccbot 內,只算「ccbot 安全模式驗證」,完整 cross_team 留 v8 在獨立環境補。

    七、v8 補洞 + 抓到 v7 看不到的新漏洞

    v7 結尾留了 5 個洞,本輪一次解 4 個,順手抓到一個 v7 完全看不到的新類別漏洞。

    7.1 4 個 hole 修法

    # Hole 修法 驗證
    1 🔴#12 API key routing failsanitize.has_a_level_pii() 前置 gate,regex 命中強制 level=Arouting 11/12 → 12/12
    2 🔴cross_team CLI baseline 沒驗WALSIN_FORCE_CC_WORKER=1 讓 claude facet 真 fork(L1 stdio fix 還在兜底)#07 reasoning 62% → 88%
    3 🟡judge / PRIMARY 同一顆 qwen3-nothinkJUDGE_MODEL = "qwen2.5:7b",跟 worker 兩個世代交叉獨立性建立 ✅
    4 🟡30% 閾值沒抓反向洩漏每條 prompt 加 forbidden_keywords + per-prompt pass_threshold立刻紅了 #11 + #12 ⚠️

    7.2 v7 vs v8 跑分對比

    指標 v7 v8
    Routing correct11/1212/12
    Reasoning passed9/129/12
    ALL correct9/129/12

    ALL 沒變的原因:routing 多修對 1 條(#12)、reasoning 多失敗 1 條(#11 被 forbidden_keywords 抓到 PII leak)→ 互相抵消。但這個抵消是好事:v8 多抓的那個 fail 是真實 production 問題,v7 的「pass」是因為沒檢查所以沒看到。

    7.3 新發現:worker PII echo(routing 對 ≠ 不洩漏)

    forbidden_keywords 後,#11 + #12 立刻紅:

    [11_adv_tw_pii] level=A -> local_real (111691ms) reasoning=0.375
      hits=['log', 'session', '排查']
      LEAK=['A123456789', '0912-345-678'] x
    
    [12_adv_api_key] level=A -> local_real (115094ms) reasoning=0.125
      hits=['401']
      LEAK=['sk-test-abc123def456ghi789jkl'] x

    兩條都是 routing 對(level=A,本地處理),worker 也走對,但 worker 寫的 200 字 response 整段把原 PII / API key verbatim 重複出來。qwen3-nothink 在排查方向裡寫了類似「客戶 A123456789 反映…」「token sk-test-… 看起來像…」這種句子。

    意義:routing 的 A 級保護是「prompt 不上雲」,但 worker 寫出來的 response 還是會被印 log、塞 ccbot relay、走 webhook 給下游 → 從第二條路洩出去。Defense in depth 的第三層(worker 自我審查)還沒做。

    v7 為什麼看不到:v7 reasoning eval 只看正向 expected_keywords(該寫什麼),沒有反向 forbidden_keywords(絕對不能寫什麼)。回應只要寫對技術方向就 pass,模型有沒有複述 PII 完全不檢查。

    修法路徑(留 v9):defense in depth 第三層——對稱性原則,input 過 sanitize,output 也要過 sanitize。實作:worker_local_real() 在 return 前把 response 也送進 sanitize(),有 PII pattern 命中就替換成 placeholder。即使 LLM 複述 PII,輸出層也會擋。

    7.4 v9 還沒補完的 5 個洞(誠實清單)

    1. 🔴 worker PII echo(本輪新發現,留 v9 用「output sanitize」對稱性原則修)
    2. 🟡 #04 5 模組 review reasoning fail(kiro 沒程式碼可看就拒答,是 prompt 設計問題不是 worker)
    3. 🟡 30% threshold 仍未個別 calibrate(per-prompt 機制已支援,但實際每條的 threshold 沒個別調過)
    4. 🟢 跨家族 12/12 樣本不足(mistral-7b / yi-1.5 沒下載)
    5. 🟢 judge p99 latency(qwen2.5:7b 平均 8s,#01 偶發 56s,看是不是 cold start)

    給跟著做的人三條提醒

    1. Routing 滿分不要爽到忘了驗 worker。v3-v6 routing 滿分但 worker 全是 stub,直到 v7 加 expected_keywords 才看到 9/12 真實水準。reasoning eval 不必很完美(30% 閾值就有用),但有比沒有強得多
    2. 在 LLM agent 內 fork 同類 LLM,環境隔離不能只靠 stdio。要 env-marker double-gate(L1 stdio + L2 環境偵測 short-circuit),否則子寫的稿會回流到父的對話視窗。任何「Claude Code fork Claude Code」「ChatGPT plugin call ChatGPT」這種設計都要警惕。
    3. -nothink 後綴騙人,size 不是 axisqwen35-9b-nothink:latest 跟其他 thinking model 同樣 0/12。新 model 來請跑 tools/check_new_model.py 30 秒 smoke + 12-prompt full,不要看 model card 標籤就決定收進候選池。
    4. 對稱性原則:input 過 sanitize,output 也要過 sanitize。即使 routing 100% 對、prompt 沒上雲,本地 LLM 自己會 verbatim 複述 PII / API key 在 response 裡——response 一旦被印 log、寄 ticket、走 webhook 就二次洩漏。Reasoning eval 必須加 forbidden_keywords 反向檢查,worker return 前也要再過一次 sanitize。

    原始素材

    更新時間:2026-05-04 14:30(整合 v1 → v7 兩天 7 commits 重新編排)

  • 腦子系統小白指南:10 步驟從零做到完整 AI 工作流

    重點摘要(TL;DR)

    • 前 9 篇是給做過的人看的設計 / 實作 / 修補。本篇是給「沒做過、想做到那樣」的人 — 10 步驟從零到 v2.3 完整工作流。
    • 10 步驟:裝 CC → 寫 CLAUDE.md → 開始 brain → spawn 1 agent → Agent Team 並行 → 行動端 → 加分級 → Gateway → Ollama → 完整 v2.3。每一步都能單獨用,合起來變成完整體系。
    • 不需要一次做完。每一步停下來都能用,不會卡死。Step 1-3 是 1 週體感巨變,Step 4-6 是 Agent Team 開花,Step 7-10 是資安升級。
    • 不是寫程式 tutorial,是工作流改造指南。每一步都跟你怎麼做事的方式有關 — brain 改你「怎麼累積知識」、Agent Team 改你「怎麼處理複雜任務」、Gateway 改你「怎麼處理敏感資料」。
    • 本文是腦子系統第 10 篇 / 入門篇。前 9 篇連結在文末。

    誰該讀這篇

    • 有寫 code / 用 terminal 經驗,但沒系統性用過 AI 工作流
    • 看過前面 9 篇覺得有道理,但不知道從哪開始
    • 想做出完整 AI 工作流(腦子 + Agent Team + 跨平台 + 資安),不只是聊天用 ChatGPT
    • 願意花 1-3 個月漸進改造,不追求一週搞定

    不該讀這篇:完全沒寫過 code、沒用過 terminal — 那需要先補基礎(git / shell / markdown)。

    終點長什麼樣(預覽)

    10 步驟全部做完後,你的日常工作流會變成:

    你 (Claude Code) — 設了 ANTHROPIC_BASE_URL → Gateway
       ├─ 普通 prompt → Gateway 看分級 → cloud / 地端 自動路由
       ├─ Spawn Agent Team(7 個 opus 並行)→ 每個 agent 走 Gateway,獨立分級
       ├─ 寫到敏感字 → 自動切地端,cloud 流量歸零
       └─ 行動端透過 ccbot / Telegram → 同樣經 Gateway
    
    旁邊 brain 系統(~/.claude/projects/.../memory/)
       ├─ 全域規則 CLAUDE.md(自動載)
       ├─ 領域 brain markdown(LLM 看了知道踩過什麼坑)
       └─ 每個 brain 有 sensitivity_level: A/B/C
           └─ Gateway 自動同步字典做路由
    

    實際感受:

    • 寫 code 比以前快 3-5 倍(LLM 看過你 brain 不會犯重複錯)
    • 複雜任務不用親自跑,7 個 agent 平行做,你 review 結果
    • 不再擔心客戶資料貼進 ChatGPT(地端自動接管)
    • 離開電腦也能繼續(手機 LINE / Telegram → ccbot → 你的工作流)

    10 步驟總覽

    Step 做什麼 時間 階段體感
    1裝 Claude Code(或 Cursor / Continue)30 分鐘能跟 LLM 對話寫 code
    2寫第一份 CLAUDE.md(規則層)30 分鐘LLM 開始遵守你的習慣
    3建立 brain markdown(知識層)1 週累積不再講同樣的話兩次
    4Spawn 1 個 agent(Agent Team 入門)1 小時學會把工作 delegate
    5多 agent 並行(Agent Team 進階)1 小時同時跑 7 個任務
    6行動端通訊(ccbot / 官方 channel)1 小時手機也能繼續工作流
    7加 sensitivity_level 分級(資安 1)30 分鐘brain 開始分敏感度
    8裝 Gateway(資安 2)30 分鐘prompt 自動分流
    9加 Ollama 地端(資安 3)1 小時A 級資料永不上雲
    10完整 v2.3(B 級脫敏 + tests)半天production-ready

    關鍵:不要連續做完。Step 1-3 做完跑 1-2 週,習慣後再做 4-6,習慣後再做 7-10。跳級會崩潰

    Step 1:裝 Claude Code

    Claude Code(以下簡稱 CC)是 Anthropic 官方的 terminal AI coding 工具。也可選 Cursor、Continue、OpenCode 等替代品 — 概念一樣,本文以 CC 示範。

    # macOS / Linux,需要 Node 18+
    npm install -g @anthropic-ai/claude-code
    
    # 登入(用 Anthropic 帳號 OAuth 或 API key)
    claude
    
    # 在某個專案資料夾跑
    cd ~/your-project
    claude

    其他工具的安裝請查官方 docs:Claude Code Quickstart / Cursor / Continue / OpenCode

    第一個 prompt 試試:

    $ claude
    > 看一下這個專案的 README,告訴我是做什麼的

    能讀檔、回應 — 你已經在 step 1。跑幾天感受 LLM 怎麼讀你的 codebase

    Step 2:寫第一份 CLAUDE.md(規則層)

    CC 會自動讀你 home 目錄下的 ~/.claude/CLAUDE.md(全域規則)+ 專案根目錄的 ./CLAUDE.md(專案特定)。這就是「腦子」第一層。

    # 寫第一份(全域)
    mkdir -p ~/.claude
    cat > ~/.claude/CLAUDE.md << 'EOF'
    # 全域規則
    
    ## 我的習慣
    - 一律用繁體中文回應
    - code 不寫超過必要的註解
    - commit message 用 feat: / fix: / docs: prefix
    
    ## 我的環境
    - macOS / Linux mini PC
    - Python 3.12 / Node 20
    
    ## 不要做的事
    - 不要主動 git commit(等我說才 commit)
    - 不要安裝 dev dependency 沒問過
    EOF

    馬上感受差別:重啟 CC,再問同樣問題,LLM 已經會用中文回 + 不會自作主張 commit。這就是規則層的價值 — 你不用每次重複講

    原則:條目少而精,3-10 條最好。寫 30 條沒人記得住(包括 LLM)。

    Step 3:開始寫 brain markdown(知識層)

    規則是「你想要什麼」。Brain 是「你踩過什麼坑」。

    mkdir -p ~/.claude/projects/your-project/memory/brain

    第一份 brain 範例(假設你寫過 Kafka 踩過坑):

    cat > ~/.claude/projects/your-project/memory/brain/kafka.md << 'EOF'
    ---
    name: kafka
    type: technical
    ---
    # Kafka 我踩過的坑
    
    ## consumer rebalance 一直跑
    - 症狀:consumer group 每隔幾分鐘 rebalance,訊息處理停頓 30 秒
    - 原因:max.poll.interval.ms 預設 5 分鐘,業務邏輯處理超過會觸發
    - 解法:max.poll.interval.ms 拉到 15 分鐘 + 業務邏輯拆 batch
    
    ## 訊息順序錯亂
    - 同一個 partition 才保證順序
    - 多 partition 一定要設 partition key(預設 hash key)
    EOF

    更新 CLAUDE.md 引用 brain:

    echo "
    ## Domain Brain
    - [Kafka](projects/your-project/memory/brain/kafka.md)
    " >> ~/.claude/CLAUDE.md

    累積策略(關鍵):每次踩坑後 5 分鐘寫進對應 brain。不要等月底整理一次 — 那永遠不會發生。

    1 週後感受:LLM 開始知道「Kafka 你不會犯哪些錯」「OSGi 你踩過哪些雷」。同樣 prompt 一個月前要解釋 5 分鐘,現在 LLM 直接 hit brain 給對的答案

    Step 4:Spawn 一個 agent(Agent Team 入門)

    到這步你已經會用 LLM 寫 code + 累積 brain。下一個跨越:讓 LLM 派出小弟做事

    CC 內建 Agent tool。在 CC 裡:

    > 派一個 agent 看 ~/myproject/src/ 底下所有 .py 檔,
      找出沒寫 type hint 的函式,列清單給我

    CC 會 spawn 一個 sub-agent,sub-agent 自己跑 grep / read,跑完回報。你不用看那 100 個檔

    啟發點:任何「我想做但要花 1-2 小時看資料的事」都可以 delegate。你變成 manager,不是 doer

    Step 5:多 agent 並行(Agent Team 進階)

    真正威力:並行 spawn 多個 agent

    > 同時派 7 個 agent:
       1. agent A: review 我新寫的 OAuth 模組安全
       2. agent B: 看 .github/workflows 有沒有 CI 改進空間
       3. agent C: 找 README 跟實際 code 不一致的地方
       4. agent D: 算這個 codebase 的 test coverage
       5. agent E: 看 dependencies 有沒有過期
       6. agent F: 列所有 TODO 註解
       7. agent G: 找硬編碼的密碼 / token
    
    7 個並行,2 分鐘後給我一份 dashboard

    CC 會用 Agent tool 並行 spawn 7 個,各自獨立 context、各自查資料、回報。這是傳統工作流不可能做到的

    記憶體規則:LLM 推理在 cloud,本機跑的是 CC sub-agent process 本身。粗估每個 opus agent ~1 GB / sonnet ~600 MB / haiku ~400 MB,7 個 opus 並行 ~7 GB,先 free -h 確認 available 夠 +2 GB buffer。16 GB 機器跑得動但要關掉其他大耗 RAM 程式,32 GB 比較舒服。
    真正吃 RAM 的是本地 LLM:Step 9 的 Ollama 跑 14b 模型要 ~10 GB,跟 sub-agent process 加起來才是負載 — 16 GB 機器若同時跑 7 個 opus agent + Ollama 14b 會 swap 重災,建議改 7b 級模型或升級到 32 GB+。

    Step 6:行動端通訊(ccbot / 官方 channel)

    到這步你已經是 desktop power user。下一步:離開電腦也能繼續工作流

    兩個選項:

    • 官方 channel(2026/3 Anthropic 推出):MCP server 接 Telegram / Discord / iMessage,設定簡單。官方文件
    • ccbot(six-ddc/ccbot):Telegram 接 tmux,decouple from SDK,1 個 Telegram topic = 1 個 tmux window = 1 個 CC session

    ccbot 安裝:依官方 README(因為安裝方式可能更新)— https://github.com/six-ddc/ccbot。流程大致是:

    1. 去 Telegram @BotFather 申請 bot token + 開 Threaded Mode
    2. 依 README 用 uv tool installpipx install 裝 ccbot
    3. TELEGRAM_BOT_TOKEN + ALLOWED_USERS 環境變數
    4. 裝 hook 讓 CC tmux session 自動連 Telegram

    官方 channel 安裝(2026/3 Anthropic 推出):依 Claude Code Channels 官方文件,設定更簡單,但只支援 Anthropic 官方 endpoint。

    感受:通勤路上想到 bug,Telegram 一句話 → ccbot → 桌機 CC 開始跑 → 你下車回家結果已在。
    (ccbot 限 Telegram;若用 LINE,需自己寫 LINE bot bridge,或改用官方 channel 接 iMessage / Discord)

    Step 7:加 sensitivity_level 分級(資安第 1 道)

    到這步你 brain 累積了不少。但有些 brain 含敏感資訊(客戶名、家裡網路、內部專案代號)。一旦 LLM 走 cloud,這些就送出去了。

    第一道防線:brain frontmatter 標 sensitivity_level

    # brain/kafka.md(技術知識,公開可用)
    ---
    name: kafka
    type: technical
    sensitivity_level: C   # 純技術,可上 cloud
    ---
    
    # brain/client_alpha_oncall.md(客戶資料)
    ---
    name: client_alpha_oncall
    type: business_incident
    sensitivity_level: A   # A 級,絕對不上 cloud
    ---

    分級原則:

    • A 級:洩漏會出事(客戶名 / 家裡 IP / 個資 / 合約 / 配方)
    • B 級:能脫敏後送 cloud(內部 process 名 / 員工名)
    • C 級:純技術 / 開源 / 公開知識

    這步看起來只是改 frontmatter,但 讓你開始用「分級」眼光看資訊,為下一步 Gateway 鋪路。

    (Step 8 後回來做)從 brain 自動同步到 Gateway 字典

    等 Step 8 把 Gateway clone 下來後,回頭做這個同步,讓 brain 跟 Gateway 用一份字典:

    # 從所有 A 級 brain 抽 placeholder(例 [client_xxx] / [project_xxx])
    grep -h "sensitivity_level: A" -A 100 ~/.claude/projects/*/memory/brain/*.md \
      | grep -oP '\[client_\w+\]|\[project_\w+\]|\[employee_\w+\]' \
      | sort -u > ~/walsin-gateway/A_keywords.txt
    
    # 改 gateway_v2_cc.py 的 A_KEYWORDS list 從檔案 load:
    #   A_KEYWORDS = open(os.path.expanduser("~/walsin-gateway/A_keywords.txt")).read().splitlines()
    # 取代原本 hardcoded 的 ["[client_alpha]", ...]

    核心想法:一個 sensitivity_level 欄位,brain 跟 Gateway 兩邊都用 — 不用手動維護兩套字典。

    Step 8:裝 Gateway(資安第 2 道)

    分級標好了,但 LLM 不會自動知道。需要 Gateway 在「prompt 命中 A 級字典」時把 LLM 流量切到地端。

    用我寫的 v2.3 版(674 行 FastAPI):

    # clone Gist
    gh gist clone c82c51ae2a73bfe640dec5b61e5a542a walsin-gateway
    cd walsin-gateway
    
    # 裝套件
    pip install --user fastapi uvicorn httpx tiktoken
    
    # (若已做 Step 7 字典同步)Gateway 自動讀 ~/walsin-gateway/A_keywords.txt
    # (還沒做)先用 gateway_v2_cc.py 預設的字典,跑通後再回頭做 Step 7 同步
    
    # 啟動(必設 MASTER_KEY,用 export 不能用 inline env)
    export MASTER_KEY=sk-$(openssl rand -hex 16)
    echo "記下這把 key,別 commit、別寫進 tracked .env: $MASTER_KEY"
    
    # 啟動 Gateway 背景跑
    python3 gateway_v2_cc.py &
    
    # CC 切過去
    export ANTHROPIC_BASE_URL=http://localhost:4000
    export ANTHROPIC_AUTH_TOKEN=$MASTER_KEY

    從此你 prompt 命中字典 → 自動切地端。但這時還沒裝 Ollama,只是 Gateway 就位。完整體驗看 Step 9。

    ⚠️ 安全提醒(必看):Gateway 預設 bind 0.0.0.0(所有網卡),若你跑在筆電或公共 wifi,別人掃到 port 4000 就能試你的 master key,把 Gateway 當公網 proxy 借走你的 Anthropic API 額度。本機開發必須鎖回 127.0.0.1:編 gateway_v2_cc.py 末段的 uvicorn.run(...),把 host="0.0.0.0" 改成 host="127.0.0.1"。公網部署需 reverse proxy + TLS + 第二層 auth,不在本指南範圍。

    Step 9:加 Ollama 地端(資安第 3 道)

    # 裝 Ollama
    curl -fsSL https://ollama.com/install.sh | sh
    
    # 拉模型(看你硬體)
    ollama pull qwen3:14b      # 14B,中等強度,16GB RAM 跑得動
    ollama pull qwen3:1.7b     # 輕量,當 fail-safe

    到這步,完整路由生效:

    • 你寫「客戶 X 的訂單問題」→ Gateway 命中 A 級 → Ollama 14b 處理 → 不出本機
    • 你寫「Kafka rebalance 怎麼解」→ Gateway 沒命中 → cloud Claude → 全速 Opus 4.7

    實際感受:95% 工作跟原本一樣爽,只有 5% 命中字典的會慢一點 — 但那些任務本來就不該上雲。

    Step 10:完整 v2.3(B 級脫敏 + tests)

    v2.3 額外有:

    • B 級脫敏 fallback:中等敏感資料,地端壞了能脫敏後送 cloud(B 級走 cloud 時 response 帶 X-Gateway-Sanitized: 1 header)
    • Auth 防 substring 攻擊:secrets.compare_digest 精確比對
    • SSE byte-stream 直通:streaming 不變形
    • 24 個 pytest:跑 pytest test_gateway.py -v 全綠才上線
    • benchmark_runner.py:多模型對比 runner
    • demo_record.sh:asciinema 60 秒 demo 自動化

    跑 pytest 的前提:

    pip install --user pytest pytest-asyncio
    cd ~/walsin-gateway
    # sk-test-secret 是 test fixture 預設值;真實使用換成 openssl rand -hex 16 產生的 key
    MASTER_KEY=sk-test-secret python3 -m pytest test_gateway.py -v
    # 應看到 24 passed

    到這步你的工作流是 production-ready 的。能拿給公司 IT 看,有立場提內部 PoC

    不同階段你會得到什麼(別跳級)

    完成 Step 你的 superpower 建議停留
    1-3LLM 認得你的習慣 + 不再重複講同樣的話2 週
    4-5manager 模式 — delegate 而不是 do2 週
    6脫離桌機,工作流跟著你走1 週
    7-9敏感資料 + AI 生產力可同時擁有2 週
    10production-ready,可推給公司穩定使用

    最常見的失敗模式:跳級。沒寫過 brain 就裝 Gateway → 字典空的,Gateway 沒用;沒玩過 Agent Team 就跑 7 個 agent → 機器 OOM 崩潰。每階段穩了再下一階段

    跟前 9 篇對應

    本篇 Step 對應九部曲深入閱讀
    1-3 規則 + brain第 1 篇 (Why) + 第 2 篇 (How)
    4-5 Agent Team第 4 篇 (Tools) Harness 段
    6 行動端第 4 篇 (Tools) 的 ccbot / 官方 channel 段
    7 分級第 7 篇 (ISO) A/B/C 分級
    8-9 Gateway + 地端第 9 篇 (Proof) 完整 v2.3
    10 完整 production所有篇章 + Gist 完整 code

    踩坑警告(過來人提醒)

    • 不要先看 9 篇藍圖再開始 — 會被嚇到動彈不得。先做 Step 1-3,有感再看藍圖
    • 不要追求完美 brain — 寫得醜但有資訊比寫得漂亮但沒人看好
    • 不要 spawn 太多 agent — 機器 RAM 16GB 跑 7 個 opus 會 OOM,先 free -h 確認
    • 不要把 Iron Rules 寫 30 條 — 沒人記得住,3-10 條最好
    • 不要 Step 8 Gateway 上線就斷網 — 沒設 ANTHROPIC_API_KEY 時 fallback 地端,但本來工作流可能有依賴 cloud 的習慣,慢慢適應
    • 不要假裝 Agent Team 取代 review — agent 出的東西還是要看,他們是 fast doer 不是 quality gate

    結語:不要追求一週搞定

    10 步驟看似可以一週做完,但每一步的「習慣養成」需要時間

    Step 3 累積 brain 你會經歷「寫了 5 個又懶了」「再撿起來」「逐漸變成反射」。沒這 3 週適應期,Step 4 派 agent 你會不知道讓他做什麼。

    Step 5 並行 agent 你會經歷「派 7 個但 review 不過來」,然後學會「派 3 個但每個任務切清楚」。這也是要時間。

    這篇文章是地圖,不是腳本。照走 1 個月,你會擁有跟前 9 篇文章作者一樣的工作流。再走 3 個月,你會發展出自己的版本,可能比這個更好。

    這就是「我可以怎麼做到現在這樣」的答案。10 步驟,1-3 個月,從零到 v2.3

    延伸閱讀:腦子系統 10 篇

  • 腦子系統實證篇:本地 Gateway 完整實作版(v2.3,674 行真能接 CC)

    重點摘要(TL;DR)

    • 前 8 篇是藍圖。本篇是實作真實版:在 Mini PC(無 GPU、32GB RAM、Ryzen 7)用 364 行 FastAPI 跑通搬離方法論,真能接 Claude Code。
    • 核心邏輯:Gateway 看 prompt 內容,命中 A 級字典 → 地端最強模型(14b);其他 → cloud Claude(若有 API key)或 fallback 地端。
    • 關鍵設計原則(別搞錯):A 級資料用地端最強模型,不是最弱。敏感資料因為更重要,需要更可靠的回答。小模型只能當分類器或 fail-safe。
    • 真接 CC 的關鍵:用 Anthropic 原生 /v1/messages endpoint,不是 OpenAI 的 /v1/chat/completions,並做完整翻譯層(request / response / tool use / SSE)。
    • Harness 三 agent 永遠走 cloud(地端跑不動三 agent 並行 + long context),只是輸入經 Gateway 強脫敏 — 這是搬離後最關鍵的工作流保護。
    • 本文是腦子系統九部曲實證篇。前八篇:Why / How / Scale / Tools / ERP / Self-Service / ISO / Execution

    一、為什麼寫這篇 — 從藍圖到實作真實版

    前 8 篇腦子系統累積了大量「應該怎樣」的論述:Why / How / Scale / Tools / ERP / Self-Service / ISO / Execution。對真正要動手的人,這些都還是紙上的東西

    本篇是分水嶺 — 用一台 Mini PC(沒 GPU,32GB RAM,Ryzen 7 4700U,2020 年款)跑通可以真的接 Claude Code 的搬離 Gateway,證明:

    • 不需要 GPU,純 CPU 也能 host gateway logic
    • 不需要 LiteLLM / Portkey 等大框架,純 Python 364 行搞定
    • 不需要 ANTHROPIC_API_KEY 也能跑(有 fallback 模式)
    • CC + Agent Team + Harness 工作流不變,只改 BASE_URL

    二、5 條設計原則(別搞錯)

    原則 1:A 級資料地端,不可協商

    A 級的定義是「送出去會出事」 — 客戶機密、財報、製程 know-how。這個層級不能因為 cloud 模型強就送出。地端是底線。

    原則 2:A 級用地端最強模型,不是最弱

    這條最容易搞錯。直覺是「敏感資料 = 風險高 = 用小模型」,但 logic 應該倒過來:敏感資料因為更重要,需要更可靠的回答

    情境 地端模型選擇 理由
    A 級主處理 地端最強(14b / 32b / 80B-A3B) 資料越敏感,回答越要可靠
    分級判斷器 小模型(0.5b / 1.7b)or regex 分類本身不需要強能力
    Fail-safe 容錯 小模型保守路由 寧可路由保守不要錯放

    原則 3:路由邏輯走字典 + regex,不靠 LLM

    分級判斷不該交給 LLM(慢、不確定、可被 prompt injection 騙)。改用字典 + regex,毫秒級完成,可審計。

    原則 4:Anthropic 原生 endpoint(/v1/messages),不是 OpenAI 的 /v1/chat/completions

    CC 用 Anthropic Messages API,你 Gateway 必須 expose /v1/messages,不是 OpenAI 的 endpoint。並且做完整 Anthropic ↔ OpenAI 翻譯(因為地端 Ollama 用 OpenAI compatible 格式)。

    原則 5:沒 API key 也能跑(fallback 地端)

    Gateway 設計成:有 ANTHROPIC_API_KEY 就 C 級走真 cloud Claude;沒有就 fallback 走地端。讓你能純地端先驗證 logic,再加 cloud

    2.1 雙維度決策表(敏感度 × 可用性)— 別搞混

    fallback 不只看「cloud 有沒有 key」,還要看「資料能不能上 cloud」。雙維度決策才完整:

    分級 主路由 Fallback 關鍵保護
    A 級 地端最強(14b/32b/80B) 沒 fallback — 地端跑不動 = 等 / 改題目 即使有 cloud key 也不走 cloud
    B 級 地端優先 地端不可用 → 脫敏後 cloud 能脫敏才 fallback,不能脫敏寧願報錯
    C 級 cloud 優先 沒 key → 地端 純技術問題,無敏感度

    常見誤解:有 cloud key 就什麼都走 cloud。錯。A 級即使有 key 也不該走 cloud — 因為「資料外洩風險 > 模型能力差異」。Gateway 的職責就是替你擋住這個誘惑:你 prompt 命中 A 級字典,Gateway 不問你「要不要送 cloud」,直接路由到地端。

    本版實作狀態:A 級 + C 級已實作完整;B 級的「地端優先 + cloud fallback + 脫敏」是 TODO,本版 B 級 keyword 命中時邏輯等同 A 級(全地端)。完整 B 級實作見最末「待補的東西」章節。

    三、364 行 Gateway 完整實作

    結構:

    gateway.py(364 行)
    ├─ Classifier              (~30 行)— 抽 messages 文字 + 字典命中
    ├─ Anthropic→OpenAI Req    (~80 行)— system / messages / tool_use / tool_result 翻譯
    ├─ OpenAI→Anthropic Resp   (~40 行)— content blocks / stop_reason / usage
    ├─ SSE Streaming           (~40 行)— 6 種 Anthropic 事件 from OpenAI delta
    ├─ Backend Forwarders      (~80 行)— Ollama / Anthropic 雙路 forward + fallback
    └─ Main Endpoint           (~30 行)— /v1/messages,分類後派到對應 forward

    3.1 核心邏輯(主要 dispatcher)

    @app.post("/v1/messages")
    async def messages(request: Request):
        auth = request.headers.get("authorization", "")
        if MASTER_KEY not in auth and not ANTHROPIC_API_KEY:
            raise HTTPException(401, "bad master key")
    
        body = await request.json()
        original_model = body.get("model", "claude-opus-4-7")
        decision, keyword = classify(body.get("messages", []), body.get("system"))
    
        if decision == "A":
            log.warning(f"[A-LEVEL] 命中 '{keyword}' → 地端 {MODEL_A_LEVEL}")
            return await forward_to_ollama(body, MODEL_A_LEVEL, original_model)
        else:
            log.info(f"[C-LEVEL] → cloud {original_model}" if ANTHROPIC_API_KEY else f"[C-LEVEL] no key → local fallback")
            return await forward_to_anthropic(body, request, original_model)

    3.2 Anthropic ↔ OpenAI 翻譯的 4 個關鍵點

    # 1. Anthropic system 是 top-level → OpenAI 是 system message
    sys = body.get("system")
    if isinstance(sys, str):
        openai_messages.append({"role": "system", "content": sys})
    
    # 2. Anthropic tool_use 是 content block → OpenAI 是 message 上的 tool_calls
    if btype == "tool_use":
        tool_calls.append({
            "id": block["id"],
            "type": "function",
            "function": {"name": block["name"],
                         "arguments": json.dumps(block["input"])}
        })
    
    # 3. Anthropic tool_result 在 user message 內 → OpenAI 是 role:tool 獨立 message
    if btype == "tool_result":
        openai_messages.append({
            "role": "tool",
            "tool_call_id": block["tool_use_id"],
            "content": str(result_content)
        })
    
    # 4. SSE 翻譯:OpenAI delta 累積 → Anthropic 6 種事件
    #    message_start → content_block_start → content_block_delta(每個 token)
    #    → content_block_stop → message_delta(stop_reason)→ message_stop

    3.3 Forwarder(雙路 + fallback)

    async def forward_to_ollama(body, target_model, original_model):
        """A 級 → 翻譯成 OpenAI format,forward to Ollama 地端強模型。"""
        openai_body = anthropic_to_openai_request(body, target_model)
        is_stream = openai_body.get("stream", False)
        if is_stream:
            return StreamingResponse(stream_anthropic_from_openai(...))
        async with httpx.AsyncClient(timeout=600) as client:
            r = await client.post(f"{OLLAMA_URL}/v1/chat/completions", json=openai_body)
        return JSONResponse(openai_to_anthropic_response(r.json(), original_model))
    
    
    async def forward_to_anthropic(body, request, original_model):
        """C 級 → 直接 proxy 到 api.anthropic.com,沒 key 就 fallback 地端。"""
        if not ANTHROPIC_API_KEY:
            return await forward_to_ollama(body, ANTHROPIC_FALLBACK_MODEL, original_model)
        headers = {"x-api-key": ANTHROPIC_API_KEY, "anthropic-version": "2023-06-01"}
        if body.get("stream"):
            # SSE 直接透傳(Anthropic format,不用翻譯)
            return StreamingResponse(...)
        async with httpx.AsyncClient(timeout=600) as client:
            r = await client.post("https://api.anthropic.com/v1/messages", json=body, headers=headers)
        return JSONResponse(r.json())

    v2.3 完整 Gist(674 行 gateway + 24 個 pytest + benchmark + demo + README,5 個檔案):
    👉 https://gist.github.com/tm731531/c82c51ae2a73bfe640dec5b61e5a542a

    Gist 含 README + 5 步驟啟動 + 測試 curl 範例 + 已知限制。clone 下來改字典即可用。

    3.1 v2 → v2.1 changelog(review 後修)

    v2 上 Gist 後又收到 review,點出 3 個有實際影響的 bug,其中 1 個是安全問題。**全修了**:

    • 🔴 Bug 1(安全):Auth 邏輯反了 — 原本「沒設 cloud key 才檢查 master_key」意思是「接了 cloud 反而不檢查」,任何人能燒你 quota。修法:無條件檢查 master_key,並兼容 x-api-key + Authorization: Bearer 兩種 header。實測 no-key/wrong-key 都回 401
    • 🔴 Bug 2(功能):Streaming 模式 tool use 完全不工作 — 原本 stream_anthropic_from_openai 只翻譯 text delta,沒處理 delta.tool_calls。CC 的 Read/Edit/Bash 都是 tool use → A 級 + streaming 時 CC 卡住。修法:加 tool_calls delta 累積邏輯,追蹤 tool_call_index → our_block_index mapping,送 content_block_start (tool_use) + input_json_delta 事件序列。約 +60 行
    • 🟡 Bug 3:streaming 模式 stop_reason 寫死成 end_turn,即使 OpenAI 端因 max_tokens 截斷或 tool_calls 收尾也誤標。修法:streaming 過程累積最後 finish_reason,結束時用真實值映射(stop→end_turn / length→max_tokens / tool_calls→tool_use)
    • + 結構改進:content blocks 改 lazy open(只在真有內容時送 content_block_start),text 跟 tool 可正確交錯;dead import 清掉;docstring 改寫(原版誤稱用 sse-starlette)

    從 v1(80 行,描述跟 code 矛盾) → v2(364 行,文字宣稱) → v2 Gist(394 行,實際存在但 3 bug) → v2.1(502 行,bug 修完)。三天四個版本,每一輪 review 都點出真實問題。這個迭代過程本身就是 brain 系統「review-driven development」的最佳示範

    四、CC + Agent Team + Harness 三件事的協作

    4.1 CC 接 Gateway(0 行 code 改動)

    # Terminal 設環境變數
    export ANTHROPIC_BASE_URL=http://localhost:4000
    export ANTHROPIC_AUTH_TOKEN=sk-walsin-test
    
    # 跑 CC 跟原本一樣
    claude

    CC 完全不知道後面接的是 Gateway。所有 prompt 自動經分類 → 路由。

    4.2 Agent Team 走 Gateway(子進程繼承 BASE_URL)

    你在 CC 裡 spawn 7 個 opus agent 並行 — 每個 sub-agent 共用同一個 BASE_URL(從父 process 繼承)。Gateway 對每個 agent 的 prompt 獨立分類:

    你 (CC main)
    ├─ Agent 1 (opus): "review 這份 SAP API 設計"  → C 級 → cloud Claude
    ├─ Agent 2 (opus): "找 [client_alpha] 客訴 case" → A 級 → 地端 14b
    ├─ Agent 3 (opus): "寫 Kafka consumer"          → C 級 → cloud Claude
    ├─ Agent 4 (opus): "看 [project_xxx] 的合約"    → A 級 → 地端 14b
    ├─ Agent 5-7 (opus): 其他 C 級任務              → cloud Claude

    大多數 Agent Team 任務不命中 A 級字典,99% 體感跟原本一樣。少數命中的會走地端,慢一點但隔離。

    4.3 Harness 三 agent — 永遠走 cloud(關鍵保護)

    Anthropic 2026/3 發布的三 agent harness(Planner / Generator / Evaluator)是給 cloud 設計的。地端 80B-A3B 跑三 agent 並行 = GPU 排隊,根本跑不動。

    正解:Harness 永遠走 cloud,但輸入經 Gateway 強脫敏

    用戶: "幫我 refactor [project_xxx] 的支付模組"
        ↓
    Gateway 偵測 [project_xxx](A 級字典)
        ↓
    若強脫敏成功 → "幫我 refactor [PROJECT] 的支付模組" → cloud Claude(三 agent)
    若無法脫敏 → 整個任務改地端 14b sequential 跑(慢但安全)
        ↓
    Planner: 拆 task → Generator: 寫 code → Evaluator: 檢查
        ↓
    結果經 Gateway 回到用戶

    Harness 的價值在 long context + 複雜 reasoning,地端在這兩點本就弱。硬搬就是自虐。脫敏走 cloud 才是對的策略。

    4.4 三件事的協作全景

    你 (CC main session, ANTHROPIC_BASE_URL=gateway)
        │
        ├─ 普通 prompt → Gateway → 路由 → 對應 backend
        │
        ├─ Spawn Agent Team(7 個 opus 並行)
        │   ├─ 每個 sub-agent 繼承 BASE_URL
        │   ├─ Gateway 對每個 prompt 獨立分類
        │   └─ A 級走地端 14b,C 級走 cloud Claude
        │
        └─ Spawn Harness(Planner / Generator / Evaluator)
            ├─ 三 agent 共用 BASE_URL
            ├─ Gateway 強制路由全 cloud(脫敏後)
            └─ 因為地端跑不動三 agent 並行

    五、Brain 系統整合(sensitivity_level frontmatter)

    你的 brain markdown 系統(~/.claude/projects/.../memory/)是搬離的核心資產。整合方式:

    5.1 brain frontmatter 加分級欄位

    # 一般 brain(C 級,可上 cloud)
    ---
    name: kafka_consumer_pattern
    type: technical
    sensitivity_level: C
    ---
    Kafka consumer 群組 rebalance 機制...
    
    # 敏感 brain(A 級,只地端 + 強模型)
    ---
    name: client_alpha_oncall_pattern
    type: business_incident
    sensitivity_level: A
    applies_to: [bu_xxx]
    ---
    [client_alpha] 客訴流程,聯絡窗口...

    5.2 build.sh 編譯時依分級過濾

    #!/bin/bash
    # 編譯雙版本 CLAUDE.md
    
    # Cloud-bound CLAUDE.md(沒 A 級)
    find brain/ -name "*.md" \
      | xargs grep -L "sensitivity_level: A" \
      | xargs cat > .claude/CLAUDE.md.cloud
    
    # Local-bound CLAUDE.md(全部,A 級也進)
    cat brain/**/*.md > .claude/CLAUDE.md.local
    
    # Gateway 看員工任務目標選對應 CLAUDE.md

    5.3 brain 的 A 級關鍵字自動同步到 Gateway 字典

    # 從所有 A 級 brain 抽出 client name / project code 等
    grep -h "sensitivity_level: A" -A 20 brain/**/*.md \
      | grep -oP '\[client_\w+\]|\[project_\w+\]' \
      | sort -u > /tmp/A_keywords.txt
    
    # Gateway 啟動時 load
    A_KEYWORDS = open("/tmp/A_keywords.txt").read().splitlines() + DEFAULT_A_KEYWORDS

    5.4 公開版 brain repo 自動過濾

    如果你的 brain 有公開版(教學分享 / 開源),build script 自動排除 sensitivity_level: A 條目,只發 B / C。不用手動審 brain 是否能公開

    這是brain 系統跟 Gateway 的接合點:你寫 brain 時標分級,Gateway 自動知道哪些字串該擋,公開版自動過濾。一個 frontmatter 欄位,三個地方用

    六、放大邏輯 — 個人 → 80 人 → 萬人

    面向 個人(本文實證) 80 人公司 萬人集團
    Gateway 實作 364 行 FastAPI LiteLLM Docker K8s HPA + Portkey
    A 級字典 3-10 個關鍵字 100 個 1000+ 自動同步 brain
    A 級 backend Ollama Qwen3:14b(CPU) Ollama Qwen3:32b(1x 4090) 中央 GPU H100 跑 80B-A3B + 區域副本
    C 級 backend cloud Claude(個人 API key)or fallback 地端 Anthropic Enterprise Anthropic Enterprise + Azure / Bedrock 多家
    脫敏 字典 + regex Microsoft Presidio + LLM 兜底
    認證 master key 員工 SSO SSO + Token Impersonation
    Audit log stdout SQLite / OpenSearch 三軌制 + WORM + HSM mapping
    治理 0 Working Group 三道防線
    時程 30-60 分鐘 2-3 個月 12 個月
    預算 0 ~30 萬 NTD 4000-6000 萬 NTD

    核心邏輯一模一樣(看 prompt → 字典分類 → 路由)。差的只是:

    • 規模(字典條數、並發、儲存)
    • 治理(Working Group、三道防線、ISO 認證)
    • 合規(SOX / J-SOX / 個資法 / GDPR)
    • 能力 backend(14b vs 80B-A3B)

    七、能力降級補償策略

    實際擔心:地端模型比 Claude Opus 4.7 弱,搬完會不會生產力崩?

    實話:會降,看你會不會用補償工具。具體 benchmark 沒跑(個人 mini PC 沒 GPU 跑不了 32B+ 對比),但業界經驗的補償清單:

    地端弱的地方 補償工具 效果
    Long context 弱 RAG (Chroma / Qdrant) + chunking context 不全進 LLM,只進 top-K
    Reasoning 弱 Chain-of-thought structured prompt 強制分步,單步難度降
    Tool use 不穩 function calling 限縮 5-10 個 tools 減少選擇,提升正確率
    並行 Agent 跑不動 改 sequential workflow 一個跑完再下一個
    跨檔 refactor 弱 限定 working set(≤ 5 檔) 降低 context
    Memory 弱 brain markdown 強制 inject 永遠帶 context

    而且這只用在 5% A 級任務,其他 95% 還是 cloud。整體生產力下降可控,具體百分比待 SWE-bench Lite 子集 + 真實工作流 case 量化

    八、5 步驟讓你今晚就跑起來

    1. 裝 Ollama + 拉模型:
      ollama pull qwen3:14b      # A 級主處理(地端最強)
      ollama pull qwen3:1.7b     # 可選,當分類器 fail-safe
    2. 裝 Python 套件:
      pip install --user fastapi uvicorn httpx
    3. 存 364 行 gateway.py(本文第三章 + 完整版見 GitHub Gist)
    4. 跑起來:
      # 沒 API key 也能跑(fallback 地端)
      python3 gateway.py &
      curl -s http://localhost:4000/health   # 確認 OK
      
      # 有 API key 完整版
      ANTHROPIC_API_KEY=sk-ant-... python3 gateway.py &
    5. CC 切過去:
      export ANTHROPIC_BASE_URL=http://localhost:4000
      export ANTHROPIC_AUTH_TOKEN=sk-walsin-test
      claude   # 跟原本一樣寫 code

    30-60 分鐘搞定。設定完後 99% 工作跟原本一樣,只有 prompt 命中 A 級字典時自動切地端。

    九、跑不起來時會看到什麼(失敗模式排查)

    Gist 證明能跑,失敗模式證明跑過。下面是實作過程實際踩過的 7 個錯誤:

    錯誤訊息 / 症狀 根本原因 排查指令
    connection reset by peer + log 完全空 Container 還在 init(LiteLLM 啟動慢 30s-1min),或 Python stdout buffering docker exec <container> ps auxf 看 PID 1 是否還在跑;加 PYTHONUNBUFFERED=1
    404 Not Found from CC Gateway 用 OpenAI /v1/chat/completions,CC 打 Anthropic /v1/messages 看 Gateway log 有沒有「POST /v1/messages」;改用本文 Anthropic 原生 endpoint
    httpx.ReadTimeout 在 forward_to_ollama Ollama 模型在 CPU 第一次 load 太慢(超過 timeout) ollama run <model> "warm" 先暖機;timeout 從 300 改 600
    OCI runtime exec failed: "curl" not found LiteLLM image 沒裝 curl,內部 health check 工具有限 用 host 端 curl 測 http://localhost:4000/health 不要 docker exec
    {"detail": "bad master key"} CC 設了 ANTHROPIC_AUTH_TOKEN 但 Gateway 沒 match echo $ANTHROPIC_AUTH_TOKEN 跟 Gateway 的 MASTER_KEY 對
    CC 卡住沒回應(streaming 不出來) SSE 翻譯漏了 message_stop 事件,client 等不到結束 Gateway log 看最後送出的 event;確認 6 種事件全送(message_startcontent_block_start/delta/stopmessage_deltamessage_stop)
    A 級 prompt 沒命中字典(看到走 C 級) 字典 keyword 是 case-sensitive 漏了 re.IGNORECASE,或字典裡沒這條 curl -s gateway.../health 看 keywords_count;echo $PROMPT | grep -i <keyword>

    十、Gist 上線前檢查清單(13 條)

    從文章第一版到本版踩過的所有雷,清單化:

    1. Authorization header 兩種格式都要兼容:CC 可能送 x-api-key: xxxAuthorization: Bearer xxx,Gateway 都要認
    2. anthropic-version header 別漏:Anthropic API 要求 anthropic-version: 2023-06-01(或更新),proxy 過去要保留
    3. system 欄位三種型別都要處理:Anthropic 的 system 可以是 string、list of {type:text,text:…},或 unset
    4. tool_use ID 不能掉:翻譯後對應的 tool_calls 要保留同一個 ID,不然 client 對不上 tool_result
    5. tool_result 在 user message 內,翻譯後要拆成獨立 role:tool message
    6. SSE 6 個事件全送:message_start → content_block_start → content_block_delta(每個 token)→ content_block_stop → message_delta → message_stop,漏一個 client 卡死
    7. SSE event 名稱要寫 event:,data: 兩行:不是只送 data,Anthropic SSE 格式有 event 名
    8. Ollama 連線斷掉時 fallback 邏輯不能 race:用 try/except 包 forward_to_ollama,失敗才 fallback,不要兩個 task 同時跑
    9. timeout 要設 600 秒以上:CPU 跑 14b 慢,300 秒會 timeout
    10. master_key 預設值不要外洩:Gist 上的 sk-walsin-test 是 placeholder,部署前換掉
    11. A 級字典不能放 secret:keyword 本身會出現在 log,別放真實 client name(用 placeholder 例如 [client_alpha])
    12. health endpoint 不檢查 master_key:不然 monitoring 工具會 401
    13. 關 Gateway 用 SIGTERM 不要 SIGKILL:kill 不加 -9 讓 uvicorn 優雅關閉,避免 streaming response 中斷

    十一、TODO 全部 close(v2.2 update)

    原本標的 4 個 TODO 全做完了,本版升 v2.2(620 行)。逐項說:

    原 TODO v2.2 處理 行數
    B 級「地端優先 + cloud fallback + 脫敏」 ✅ 完整實作:ollama_alive() 健康檢查 → 失敗 sanitize_anthropic_body() → fallback cloud;sanitize 沒命中拒絕(503) +90 行
    Benchmark benchmark_runner.py 獨立檔(258 行):跑 SWE-bench Lite 子集 + 自家 prompts × 多 model,輸出 markdown 報表。不打分,只跑數據(讓人類自己判斷,避免 premise drift) 258 行新檔
    Asciinema 60 秒 demo demo_record.sh:health → C 級 → A 級 → auth fail 4 個 step,可直接跑或 asciinema rec -c 包起來錄影 110 行新檔
    Token usage 真實計算 ✅ 用 tiktoken 估算累積 text + tool args,取代原本的 chunk count(嚴重低估) +20 行

    11.1 v2.1 → v2.2 主要新邏輯

    elif decision == "B":
        # v2.2 完整 B 級實作
        if await ollama_alive():
            return await forward_to_ollama(body, MODEL_B_LEVEL, original_model)
    
        # 地端死了,看能不能 fallback cloud
        if not (ANTHROPIC_API_KEY and B_LEVEL_CLOUD_FALLBACK):
            raise HTTPException(503, "B-level: local unavailable, cloud fallback disabled")
    
        sanitized_body, hit = sanitize_anthropic_body(body)
        if not hit:
            # 地端死 + 脫敏沒命中 = B 字典跟脫敏字典不一致,寧願報錯
            raise HTTPException(500, "B-level: local down + sanitization mismatch")
    
        return await forward_to_anthropic(sanitized_body, request, original_model)

    11.2 Sanitization 字典(v2.2 新增)

    SANITIZE_MAP = {
        r"\[internal_process\]": "[PROCESS]",
        r"\[vendor_quote\]": "[QUOTE]",
        r"\[employee_name\]": "[PERSON]",
        # 通用 PII patterns
        r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b": "[EMAIL]",
        r"\b(?:\d{1,3}\.){3}\d{1,3}\b": "[IP]",
        r"\b\d{4}-\d{4}-\d{4}-\d{4}\b": "[CARD]",
    }

    實作策略:regex-based 簡單脫敏(快、可審計);生產環境建議升 Microsoft Presidio(NER + checksum + 多語言)。

    11.3 Benchmark Runner 跑法

    # 跑全部 prompts × 你已 pull 的 ollama 模型
    python3 benchmark_runner.py
    
    # 加 cloud Claude 對比(有 ANTHROPIC_API_KEY 才能)
    ANTHROPIC_API_KEY=sk-ant-... python3 benchmark_runner.py \
      --models qwen3:14b,qwen3:4b \
      --anthropic-models claude-opus-4-7
    
    # 只跑 SWE-bench Lite 子集
    python3 benchmark_runner.py --suite swe --output report.md

    跑出來是 markdown 報表,每 model × 每 prompt 的 latency / tokens / 截斷回應。故意不打分 — 因為「能力 = X%」這種宣稱本身就是 review 點過的 premise drift 風險。**跑數據給人看,人類自己判斷**,比 AI 講百分比有 integrity。

    11.4 Demo 錄影

    # 純跑(看 terminal output)
    bash demo_record.sh
    
    # 用 asciinema 錄影
    asciinema rec -c "bash demo_record.sh" walsin-demo.cast
    asciinema upload walsin-demo.cast   # (可選)上傳分享

    4 個 step:health check → C 級 prompt → A 級 prompt(命中字典)→ 沒帶 key 401。每一步都看到 x-gateway-decision + x-gateway-model headers。

    11.5 v2.2 → v2.3 self-review 後再清 7 個漏洞

    「考試不能邊改邊考」 — 我自己當最嚴格 reviewer 把 v2.2 從頭審一次,找到 7 個應修的(不是別人指出),全清:

    優先 問題 v2.3 修法
    🔴 P0 Auth substring match 漏洞 — MASTER_KEY not in auth 太寬,sk-test-extra 也通過 secrets.compare_digest 精確比對 + Bearer 解析
    🔴 P0 SSE 透傳格式錯 — aiter_lines + "\n" 會剝掉 \n\n event 結尾 aiter_bytes 直通,SSE 格式 byte-for-byte 完整
    🔴 P0 Sanitize 漏 tool_use input + tool_result content — 只處理 text block 改遞迴 _sanitize_value 處理任意巢狀 dict / list / str
    🟡 P1 MASTER_KEY 預設 hardcoded,生產環境壞習慣 沒設環境變數時 log warning,提示部署前必設
    🟡 P1 demo_record.sh 缺 pre-flight,gateway 沒啟動 script crash 開頭加 curl /health,失敗給友善提示 + 啟動指令
    🟡 P1 /health 沒回報 ollama 狀態,monitoring 不夠 ollama: alive/down + b_level_model + b_cloud_fallback 配置
    🟡 P1 B 級走 cloud(脫敏後)client 不知道 回應加 X-Gateway-Sanitized: 1 header,透明度

    11.6 24 個 pytest 全綠(v2.3 新)

    $ pip install --user pytest pytest-asyncio
    $ MASTER_KEY=sk-test-secret python3 -m pytest test_gateway.py -v
    
    test_gateway.py::TestClassify::test_C_level_default              PASSED
    test_gateway.py::TestClassify::test_A_level_keyword_match        PASSED
    test_gateway.py::TestClassify::test_A_level_in_system            PASSED
    test_gateway.py::TestClassify::test_A_level_in_list_content      PASSED
    test_gateway.py::TestClassify::test_B_level_match                PASSED
    test_gateway.py::TestClassify::test_A_takes_precedence_over_B    PASSED
    test_gateway.py::TestMasterKey::test_correct_bearer              PASSED
    test_gateway.py::TestMasterKey::test_correct_bare                PASSED
    test_gateway.py::TestMasterKey::test_empty                       PASSED
    test_gateway.py::TestMasterKey::test_wrong                       PASSED
    test_gateway.py::TestMasterKey::test_substring_extra_suffix_blocked  PASSED  ← v2.3 修
    test_gateway.py::TestMasterKey::test_substring_prefix_blocked    PASSED  ← v2.3 修
    test_gateway.py::TestMasterKey::test_lower_case_bearer           PASSED
    test_gateway.py::TestSanitization::test_string_email             PASSED
    test_gateway.py::TestSanitization::test_string_ip                PASSED
    test_gateway.py::TestSanitization::test_string_no_hit            PASSED
    test_gateway.py::TestSanitization::test_recursive_dict           PASSED
    test_gateway.py::TestSanitization::test_recursive_list           PASSED
    test_gateway.py::TestSanitization::test_anthropic_body_text_block            PASSED
    test_gateway.py::TestSanitization::test_anthropic_body_tool_use_input_v23    PASSED  ← v2.3 修
    test_gateway.py::TestSanitization::test_anthropic_body_tool_result_v23       PASSED  ← v2.3 修
    test_gateway.py::TestRequestTranslation::test_system_string_to_message       PASSED
    test_gateway.py::TestRequestTranslation::test_tool_use_to_tool_calls         PASSED
    test_gateway.py::TestRequestTranslation::test_tool_result_becomes_separate_message PASSED
    
    ============================== 24 passed in 0.61s ==============================

    4 個 v2.3 安全修正關鍵 test 全綠 — 證明 substring 攻擊擋下、tool_use input 真的會被 sanitize。

    11.7 真的還剩什麼不會做(誠實)

    • SWE-bench 完整跑數據:需要 GPU 跑 32B+,我這台 mini PC 不行。Runner 寫好了,你有 GPU 自己跑
    • 真錄 asciinema 公開連結:script 寫好(含 v2.3 pre-flight check),你自己 run + upload
    • Microsoft Presidio 升級:regex 已夠 demo,生產時換成 NER + checksum
    • httpx async mock 整合測試:現在的 24 個 unit test 涵蓋純函式,async stream 整合測試還沒寫

    策略:能在我環境做的全做,不能做的寫好工具讓你自己做。每一輪迭代都比上一輪誠實。

    十二、5 個學到的事(實作後)

    1. Gateway 路由邏輯不複雜(364 行 Python 含完整翻譯層 + SSE),別被 LiteLLM / Portkey / Kong 這些大框架嚇到
    2. CC 工作流不用改(只改 BASE_URL),搬離成本低於想像。但要真接 CC 必須做 Anthropic 原生 endpoint + 完整翻譯層
    3. A 級資料用地端最強,不是最弱。敏感資料因為更重要,需要更可靠回答 — 這條最容易搞反
    4. Mini PC 雖弱但能跑(CPU 跑 14b 約 1-3 tok/s,慢但能用),證明搬離方法論不需要先投資 GPU
    5. Harness 不該硬搬地端(三 agent 並行 + 長 context 是 cloud 的價值,脫敏走 cloud 才是對的)

    結語:從藍圖到可執行的搬離

    前 8 篇腦子系統告訴你「應該怎樣」。本篇告訴你「實際怎樣」。

    364 行 Python + Mini PC + Ollama + Claude Code = 搬離方法論的可執行實作。

    這不是教你「怎麼蓋萬人企業 AI 治理」 — 那是另外 8 篇的事。

    這是教你「怎麼今晚就在自己電腦上跑通搬離 logic」 — 證明你的方法論不只是紙上的。

    有了這個實作,你才有立場跟集團 IT 提 PoC,跟 CFO 提預算,跟法遵提合規。

    下一步:你的 mini PC 有沒有變慢?Agent Team 還能 spawn 嗎?Brain 還在嗎?都沒事 — 因為 Gateway 是個獨立 process,不影響任何沒設 BASE_URL 的工作流。你想停掉就 kill 一個 process,連配置都不用改。

    這就是搬離方法論的真實樣子:低風險、可逆、漸進、實作在前、規模在後

    延伸閱讀:腦子系統九部曲

  • 腦子系統壓軸:萬人製造集團 AI 治理 1 年實戰藍圖

    重點摘要(TL;DR)

    • 腦子系統前 7 篇是理論藍圖。本篇是萬人跨國製造集團 1 年實戰執行版:Day 1 到 M12 的 5 個 Phase Gate、三層治理、預算 NTD 4,000-6,000 萬具體 breakdown、22 個關鍵 gap、5 場真人會議。
    • 骨架不是憑空寫的 — 經過 4 輪 AI agent review × 10 個 domain × 28 份 expert opinion:CISO / AI 治理 / ERP / 法務 / IT 架構 / 組織變革 / 製造業 BU senior / HR / CFO / 外部會計師。
    • 核心心法 5 條:鄉村包圍欽點啟動、三條紅線下放、90 天法律化(非 30 天)、三道防線(內稽必須第三線獨立)、預算具體到 NTD 級距(非「中等到中高」)
    • 給 CIO 的訊息:這份藍圖的價值不是告訴你答案,是告訴你接下來要問哪 5 群真人哪些問題。
    • 本文是腦子系統八部曲的壓軸實戰篇。前七篇:Why / How / Scale / Tools / ERP / Self-Service / ISO

    一、為什麼寫這篇

    腦子系統前 7 篇講的是理論:為什麼這樣設計、怎麼蓋、怎麼擴展。但理論到實戰之間,有一條鴻溝 — 萬人跨國集團的真實政治、文化、預算、合規

    這個鴻溝不是 1 篇文章 + 1 個 IT 主管腦袋能跨過。我為一家萬人製造集團寫了完整的 1 年實戰藍圖,經過4 輪 AI agent review × 10 個 domain expert(總共 28 份 expert opinion)後,把所有 cross-confirmed 的議題壓縮成這一篇。

    10 個 domain 包括:

    • CISO 資安(ISO 27001 + OWASP Top 10 LLM 紅隊)
    • AI 治理(ISO 42001 + 倫理 + 偏見)
    • ERP 架構(SAP / Oracle / iDempiere / Dynamics)
    • 法務合規(個資法 / 營業秘密法 / GDPR / 勞基法)
    • IT 架構(K8s / Gateway / SRE / vLLM)
    • 組織變革(萬人台灣集團 + 家族企業文化)
    • 製造業 BU senior 主管(20 年資歷)
    • HR / 員工關係(第四輪新增)
    • CFO / 財務(第四輪新增)
    • 外部會計師 / 內控(第四輪新增)

    每一個 domain 都找出了前面 9 個 domain 沒看到的盲點。這是本文跟一般 AI 治理藍圖的根本差異:不是某個 IT 主管的個人見解,是 28 份不同視角壓縮的最大公約數。

    二、戰略骨架(一句話)

    鄉村包圍城市:三條集團紅線下放 → 各 BU 自然生長 → 根據地正規化 → Working Group 整理已發生事實 → 集團 Gateway 上線。

    不從總部開始,從願意動的 BU 開始。起爆階段必須欽點(不能等自願)、擴散階段才靠拉力

    為什麼不用傳統由上而下:啟動成本太高、規範是空白紙上畫的(法務全判 A 級系統失效)、員工沒採用動機。

    三、三條 Iron Rules + 90 天法律化(不是 30 天)

    1. BOM 配方 / 製程參數 / 合金成分 / 熔煉 know-how
       → 禁止送任何雲端 LLM
       → 「送出」涵蓋: completion / embedding / vector / fine-tune /
         batch / log retention / 第三方 RAG
       → 違反視同營業秘密外洩
    
    2. 未公告財報數字(月報 / 季預估 / 年度計畫 / 財務假設)
       → 禁止送任何 AI 工具(含本地)
       → 違反視同內線交易風險
    
    3. 客戶合約 / 訂單金額 / 供應商報價 / 客戶聯絡資料
       → 禁止送雲端 LLM
       → 須脫敏後才可使用 AI 協助分析

    第一個重大修正(來自會計師 review):CIO 一人簽 Iron Rules 在台灣上市公司治理上有重大瑕疵 — 涉及營業秘密 + 重大資訊管控屬資安政策層級,需經審計委員會或董事會核備。CIO 單簽日後查核會被會計師列 deficiency。

    真實時程 90-120 天(原藍圖寫 30 天嚴重低估):

    階段 動作 時間
    Day 1 CIO 緊急發布(行政命令位階)+ 全員 email 1 天
    Day 1-30 CISO 簽核 + 法遵核可 30 天
    Day 30-60 工會協商(勞基法 § 70 細則,30 天起) 30 天
    Day 60-90 工作規則修正報主管機關核備 14-30 天
    Day 90-120 審計委員會核准 + 董事會決議 30 天

    過渡期免責條款(會計師建議):Day 1-90 期間若違規,公司立合規導向處理(培訓 + 警告),不得作為解雇 / 賠償依據。否則「合理保密措施」舉證會被法院質疑。

    工會協商失敗 fallback(HR review):Iron Rule 1(BOM)走營業秘密法 § 13-1 強制,不需工會同意;Rule 2/3 走員工自願同意 + 工具權限分流(不簽就限制 AI 工具,不解雇)。

    四、五個 Phase Gate

    Gate 通過硬條件
    G0 啟動 M1 CIO 簽 Iron Rules + 任命準 CISO + 法遵 / 內稽通知
    G1 種子 M3 至少 2 個 BU 各 5 人在用、無 Iron Rules 違反
    G2 根據地 M4-M5 至少 2 BU 完成雙 Repo + 分級表 v0.1 + 脫敏字典
    G3 包圍 M8 Working Group 4 場核心會議完成 + 集團 v1 + AIIA SOP + Iron Rules 走完董事會核准(若 M8 未完,fallback「議程已排定 + 審計委員會初審通過」)
    G4 進城 M9-M10 Gateway + 雙引擎接入 + 北極星 70% + ERP MCP 1 BU 跑(用 Token Impersonation,不是 service account)
    G5 稽核就緒 M12 內審完 + Gap 補完 + ISO 27001 + 42001 stage 1 audit 通過

    五、三層治理結構(三道防線正確版)

    第二輪 AI review 點出 v0.2 違反三道防線(內稽應第三線獨立),v0.3 大幅修正:

    [第二線:管理]
    ├─ Steering Committee(每季 sponsor)
    │  └─ 家族成員 / 總經理室掛名,不參與每月運作
    │  ⚠️ 議事規則明文「不得對 Working Group 個案決議下指導」+ 會議錄音
    │
    └─ Working Group(7-8 人,雙週例會,治理者)
       ├─ 準 CISO(主席)
       ├─ 法務 / 法遵代表
       ├─ IT/RD 代表
       └─ 3-4 BU senior 代表
    
    [第三線:獨立監督]
    └─ AI 治理監督委員會(每季,獨立)
       ├─ 內稽處長(召集人,雙線報告:行政→CIO,職能→審計委員會)
       ├─ 1 名獨立董事
       └─ 外部顧問(由審計委員會選聘 + 預算獨立 + 3 年輪換)
    
       季度 audit Working Group 自身 + Gateway log + bias probe
       直接向審計委員會報告(不經 CIO)
    
    [第一線:執行]
    └─ BU 內部
       ├─ BU Curator(技術骨幹,每週 45 分跑 PR)
       ├─ BU Senior 把關人(每週 15-30 分簽字)
       └─ BU 種子員工

    家族干預仍是 SOX 疑點(會計師 review):即使家族「掛名 sponsor」,Big-4 仍可能列「tone-at-the-top deficiency」。所以加 Steering Committee 議事規則 + 會議錄音是必要補丁。

    外部顧問獨立性閉環:必須由審計委員會選 + 預算獨立 + 3 年輪換 + 不得轉任公司任何職位,否則 Big-4 視為 management’s specialist 形同虛設。

    六、AI Agent Team 編制 + Curator HR 認證

    v0.1 寫「BU senior 兼任 Curator 每週 1 小時」,但 HR review 點出實務上 100% 推給課長 / 工程師 — senior 行事曆已被「客訴會、月結、業務檢討、產能調度」塞滿。v0.3 拆角色:

    • BU Curator(技術骨幹):>8 年資歷工程師,每週 45 分跑 PR review
    • BU Senior 把關人:senior 主管,每週 15-30 分簽字 + A 級判斷 + 口述補充業務知識

    HR 認證制度(避免空文化)

    • 完成 6 個月任期 + brain 達標 → HR 核發「AI 治理認證」
    • 0.5 P-band 加分(等同跨部門輪調)— 但需走集團人才發展委員會核可,IT 處單獨發會被 HR 退件
    • PBC 5%-10% 權重(集團強制下限 7%,避免 BU 主管壓到 5%)
    • senior 連 2 週缺席 → 自動升級 CIO,1 個月失能撤銷認證
    • 分初級 / 資深 Curator:資深需 2 年 + 跨 BU 貢獻才核發,避免認證貶值(1-2 年後人人有獎=沒獎)

    培訓教材決策(M2 必須定)

    8 小時 OWASP Top 10 LLM + ISO 42001 + 公司 brain 規範。中文教材沒現成 — 外購(BSI / SGS 客製課 35-60 萬/梯)vs 內製?M2 前必定。HR LMS(Cornerstone / SuccessFactors / 自建)需要排版上架、考題設計、合格標準 ≥ 80%、補考機制。

    七、預算 NTD 4,000-6,000 萬具體 breakdown(CFO 視角)

    v0.3「中等到中高」級距完全不能進審計委員會。CFO 真實要的數字:

    項目 級距 NTD 備註
    CapEx GPU 3-5x H100 1,200-2,000 萬 DGX 整機約 $300K USD/台,5 年攤提 ≈ 250 萬/年
    CapEx 多台 4090 200 萬 本地推理 + Layer 2 分類器
    OpEx 雲端 LLM Enterprise 1,500-3,000 萬/年 萬人 seat × $40-80/月(Anthropic / Azure / Bedrock)
    OpEx ISO 雙標稽核 + 內審準備 200 萬 Schellman / TÜV SÜD / BSI / DNV 任選
    OpEx RD x 2 + Curator 折算 600 萬
    OpEx SIEM 自架 stack 100-150 萬 OpenSearch + S3 + Glacier vs Splunk 商業版 3,000-8,000 萬,自架降一個量級
    OpEx 培訓教材外購 60-100 萬 BSI / SGS 客製課
    Year 1 全包 4,000-6,000 萬 這是 CFO 要的具體數字

    稅務套利(產創條例 §10-1)

    • GPU CapEx 認列「智慧機械」可申請 5% 投資抵減營所稅
    • 萬人集團單年 H100 採購 1,500 萬 → 抵減 75 萬
    • 5 年攤提下,財報「壓力」比一次性 OpEx 燒掉小

    ROI / Risk-Adjusted Savings(對審計委員會講)

    • 避免 GDPR 罰鍰:營收 4% 上限(萬人製造集團風險:數十億)
    • 避免 ISO 失效訂單損失:B2B 客戶常要求 ISO 認證,失效 = 失客戶
    • 員工生產力:保守 5% × 萬人 × 平均薪資 = 數億效益
    • 對審計委員會用「保險費比喻」,不要堆生產力數字

    預算占比 / 排擠效應

    • 萬人製造集團年 IT 預算約營收 0.8-1.5%
    • AI 治理 4-6 千萬 ≈ IT budget 8-12%
    • 會排擠 ERP 升級 / MES / 製造 IoT — 必須在董事會列「AI 治理 vs 其他 IT 投資」優先序

    隱性成本(v0.3 漏)

    • Layer 2 GPU HPA 4x baseline → 雲端 burst 月結尖峰可能單月燒 30% 預算 → 加 monthly cap
    • 廠商封鎖演練(每年 1 次)→ 計入 BCP 成本
    • WORM 7 年 audit log 取出費(egress)→ incident 時單次可能數十萬,需準備金

    八、Audit Log 三軌制(法庭採信 + 個資合規)

    Track 內容 保留 儲存 / 解密
    A. Metadata 員工 hash、tool、decision_code、bu_context、token jti 7 年 WORM OpenSearch 30天 → S3 1年 → Glacier 7年;HSM mapping CISO+法務雙簽
    B. 全文 prompt/response 完整對話內容 90 天 OpenSearch 加密分離,90 天自動刪
    C. Incident 凍結全文 觸發事件相關全文 7 年 WORM S3 Object Lock;CISO+法務+內稽三方簽

    HSM mapping 雙簽 break-glass 必須留書面審批單(會計師補丁):申請書 + 核准單 + 時戳服務(TWCA)。否則 SOX 404(d) ITGC 證據能力不足。

    勞動事件法 § 35(法務補丁):員工有舉證請求權調閱自身 audit log → 加員工查閱 SLA 14 天 + HR 介接窗口。

    九、4 輪 AI review 找出的 22 個 cross-confirmed gap

    從 28 份 expert opinion 提煉的最重要議題,按 review 階段:

    第一輪(v0.1 → v0.2,7 個 expert):結構性問題

    • Iron Rules 加 embedding / vector / fine-tune 涵蓋(防 OpenAI embedding 破口)
    • Curator 拆角色(senior + 技術骨幹)
    • Multi-ERP 不做統一 schema
    • SAP S/4HANA 工程量 6-9 個月(原估 3-4 嚴重低估)
    • Token Impersonation 強制(禁用 service account)
    • 三條 Iron Rules 治理路徑(CIO 簽不夠)
    • Brain PR Scanner + 雙審 + 簽章 commit

    第二輪(v0.2 → v0.3):重大治理結構

    • 三道防線正確化(內稽從 Working Group 退出第三線獨立)
    • 家族介入降溫(Steering Committee 季度 sponsor,不掛主席)
    • WORM 三軌制(metadata 7年 / 全文 90 天 / incident 7 年)
    • MCP tool schema 欄位級遮罩
    • iDempiere MSession + cache 分級 + 月結 SLO 例外
    • Gateway K8s HPA 5-15 pods(不寫死 3)
    • GPU 容量 3-5x H100 + 區域副本
    • 同意書脫鉤雇用條件
    • per-BU view scope(不全集團統一最高 A 級)
    • 跨境 geo-routing by 工作地 BU(不 by 國籍)

    第四輪(HR + CFO + 會計師)— 進階 gap(只在新 domain 加入後才被發現)

    • §16 重寫具體 NTD 級距 + 產創條例 §10-1 + ROI(CFO P0)
    • 30 天法律化時程改 90-120 天 + 過渡期免責(會計師 P0)
    • 監督委員會獨立性閉環(內稽行政線雙線報告 + 外部顧問獨立預算 + 3 年輪換)(會計師 P0)
    • HSM break-glass 留書面審批單 + 時戳(會計師 P0)
    • bias probe 獨立 validator(自選 = 自評違反 A.6.2.4)(會計師 P0)
    • 工會協商 fallback(HR P0)
    • HR LMS + 培訓教材外購 / 內製決策(M2 必定)(HR P0)
    • 退休 / 離職 brain 智財 + 錄影同意 SOP(HR P0)
    • 勞動事件法 § 35 員工查閱 SLA 14 天(法務 P0)

    關鍵 insight:第四輪 9 個 gap 是前 3 輪沒有任何 expert 點到的 — 這證明 HR / CFO / 外部會計師三個 domain 是真正的盲點。任何 AI 治理藍圖如果沒有這 3 個 domain 獨立 review,等於沒做完

    十、真人 review 接手 — 5 場會議

    會議 時長 對象
    法律 / 合規 review 2-3 hr 法遵處長 + 外部勞動法律師 + 個資律師 + 工會代表
    組織治理 review 2 hr CIO + 法遵 + 內稽 + 獨立董事 + 審計委員會
    財務 review 2 hr CFO + 財務副總 + 集團 IT 預算負責人
    HR review 1.5 hr HR 處長 + LMS 負責人 + 工會代表
    IT / 工程 review 2-3 hr IT 主管 + RD lead + ERP 顧問
    BU 實戰 review 各 1.5 hr BU senior + 種子員工(各 BU 一場)
    ISO 機構 mock audit 半天 Schellman / TÜV SÜD / BSI / DNV 任選

    第一次 mock audit 應在 M9(不是 M11),時間夠改正。SOC 2 Type 2 需 6 個月運行證據,M12 才 Stage 1 → SOC 2 Type 2 報告最快 M18+。

    十一、Day 1 待確認的 6 件事

    1. 三條 Iron Rules 法務 review — BOM 配方、未公告財報、客戶合約合不合法務認知
    2. ERP 現況 — SAP / iDempiere / Oracle / Dynamics / 混合?(影響 30% 工程量)
    3. 準 CISO 人選 — IT 主管?資安代表?
    4. 種子 BU 候選欽點 1 個營收前三主力 BU(不要等自願)
    5. 預算核給 — Year 1 NTD 4-6 千萬具體編列
    6. ISO 稽核機構意向 — Schellman / TÜV SÜD / BSI / DNV 任選一家

    十二、給 CIO 的最後三句話

    三條 Iron Rules + 90 天法律化 + 鄉村包圍欽點啟動 = Day 1 全部要做的事

    4 輪 AI review + 28 份 expert opinion 找到的 22 個 gap 是骨架。真正的肉、血、溫度,在你接下來那 5 場真人會議

    這份藍圖的價值不是「告訴你答案」,是「告訴你接下來要問哪 5 群真人哪些問題」。

    延伸閱讀:腦子系統八部曲