小丁的家

分類: 最佳實踐

  • 跟 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 read低6.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 寫程式的紀律：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 告訴我什麼該做」。這比「一輪一輪我看看哪邊有問題」健康得多。

  • Spring Boot OMS Code Review 實戰：20 個 Bug 與事件驅動架構的一課

    重點摘要

    • 三輪 Code Review 共找出 20+ 個問題，從 NPE 連鎖到種子資料欄位名稱全錯
    • Kafka Seeder 寫了三個版本，每次重寫都是對「事件驅動架構正確入口」理解的加深
    • 能走事件流就走事件流：API → Kafka → Consumer → DB，每一層都有可追蹤、可重試的意義
    • 21 個 Java 容器沒有 JVM 記憶體限制，用 JAVA_TOOL_OPTIONS 一行解決，不需改 Dockerfile

    這是 多通路電商 OMS 系統開發過程中的一天工作紀錄。系統整合了 Momo、Shopee、Yahoo 等電商平台，透過 Kafka 事件流處理訂單同步、退貨與統計。今天的目標：完成 feature/stats-pipeline 分支上的所有待辦修復，讓系統能順利 docker compose up，並驗證端對端資料流。

    三輪 Code Review：每一輪都有新發現

    第一輪：已知清單上的 7 個問題

    進入狀態之前就有一份清單，分為 Critical、Warning、Info 三個等級：

    等級 問題 修復方式
    CriticalOrderUpsertConsumer .get() NPE 連鎖改 .path() + 加 orderDataJson null 守衛
    Criticaldaily_statistics.id 缺 NOT NULL加約束 + DEFAULT partition
    CriticalReturnUpsertConsumer 未寫 stats dirty marker新增 Redis ZSET 寫入
    WarningDailyStatisticsService early return 留舊資料改成刪除過時的 stats 列
    Warningenum 預設值小寫 'pending'改大寫 'PENDING'，與 JPA EnumType.STRING 對齊
    WarningRetryJobConsumer MissingNode cast加 .isObject() 判斷再 cast

    其中 enum 大小寫這個問題值得特別說明。Java 的 @Enumerated(EnumType.STRING) 在讀取時呼叫 Enum.valueOf()，這個方法是 case-sensitive 的。資料庫預設值寫 'pending'，但 enum 常數叫 PENDING，啟動時不會出錯，但一讀到有 DEFAULT 值的列就會拋 IllegalArgumentException。

    第二輪：種子資料是另一個地雷區

    Schema 修完了，以為大功告成，結果種子資料（02-seed-data.sql）是第二個地雷區：

    1. BCrypt hash 是假的：$2a$10$dummyhashfordevonly... 根本不是有效的 BCrypt hash，Spring Security 的 passwordEncoder.matches() 永遠回傳 false，登入 100% 失敗。
    2. 訂單狀態小寫：'completed'、'shipped' — 和上面一樣的 case-sensitive 問題，這次在資料列而不是 DEFAULT 值。
    3. daily_statistics 欄位名稱全錯：用了 order_count、total_amount 這些不存在的欄位名，docker compose up 的 DB 初始化階段會直接 fail。

    這些問題的共同特徵是：compile time 抓不到，schema validate 也抓不到。Hibernate 的 ddl-auto: validate 只單向檢查「entity 中有 mapping 的欄位是否存在於 DB」，不會反向驗證 SQL 腳本的正確性。唯一的防護是跑起來測試。

    第三輪：21 個容器，一個 JVM 記憶體問題

    系統在開發機上跑 21 個 Java 容器（Spring Boot services），沒有任何 JVM heap 限制。JVM ergonomic sizing 預設使用系統 RAM 的 25%，7.4GB 可用 RAM 很快就會不夠。

    解法是在 docker-compose.yml 每個服務加 JAVA_TOOL_OPTIONS：

    environment:
  JAVA_TOOL_OPTIONS: "-Xmx256m -XX:+ExitOnOutOfMemoryError"

    JAVA_TOOL_OPTIONS 是 JDK 標準環境變數，JVM 啟動時自動讀取，不需要修改 Dockerfile 的 ENTRYPOINT。-XX:+ExitOnOutOfMemoryError 讓容器在 OOM 時立刻崩潰（而不是卡死），對 Docker 的 restart: unless-stopped 友好，等於有了自動恢復機制。

    Seeder 的三次重寫：對事件驅動架構的理解之旅

    今天最有收穫的插曲。目標是「準備一個 Docker 服務，打假訂單資料，確認整體資料流順暢」。這個任務看起來很簡單，結果寫了三個版本。

    第一版：直接打 Kafka（被打槍）

    第一直覺：用 kafka-python 直接連 kafka:9092，組好 ORDER_UPSERT 訊息送到 order.process topic。快速、直接。

    問題：系統對外只有 API，直接操作 Kafka 是繞過了系統設計的邊界。內部基礎設施不應該是外部系統的接入點。

    第二版：打 POST /api/orders（沒走事件流）

    改用 REST API。先 login 拿 JWT，再 POST /api/orders。

    問題：OrderController.createOrder() 是直接寫資料庫，跳過了整個 Kafka pipeline。Stats dirty marker 不會被寫入，DailyStatisticsService 不會被觸發，daily_statistics 表不會更新。雖然訂單進了 DB，但「整體資料流」沒有跑通。

    第三版：新增正確的 API 端點（走完整事件流）

    在 UserOrderController 新增 POST /api/user/orders，接收訂單資料後發布 ORDER_UPSERT 到 Kafka，回傳 202 Accepted：

    POST /api/user/orders  (帶 JWT)
  → 查 Channel → Platform（取得 platformId）
  → 組 ORDER_UPSERT 訊息（header + body + hash）
  → kafkaTemplate.send("order.process", ...)
  → 回傳 202 Accepted

接著：
  Kafka order.process
    → OrderUpsertConsumer（Redis 去重 → INSERT/UPDATE）
        → stats dirty marker 寫入 Redis ZSET
            → StatsRecalcHandler（定時掃）
                → DailyStatisticsService.recalculate()
                    → daily_statistics 更新

    端到端，一條不少。

    為什麼「能走事件流就走事件流」不只是口號

    三次重寫讓這個原則從抽象變得具體。走事件流的好處不只是「解耦」這個詞能涵蓋的：

    層面 直接寫 DB 走 Kafka 事件流
    可追蹤性只有 DB recordKafka UI 可看完整訊息歷史，帶 traceId
    錯誤處理拋 exception，呼叫方看到 500失敗走 task.failed → retry → task.dlt
    去重需要自己實作Consumer 有 Redis + DB 兩層去重
    統計觸發需要額外呼叫Consumer 自動寫 dirty marker，批次計算
    一致性邏輯分散在多處無論來源（channel job / API），走同一套邏輯

    最後一點是最重要的：一致性。不管訂單是從 Shopee channel job 來的，還是透過 API 手動新增的，都走同一個 OrderUpsertConsumer，同一套去重邏輯，同一套 stats pipeline。系統裡沒有「繞過」的快捷路徑。

    今日修改摘要

    檔案 類型 說明
    01-schema.sqlBug FixNOT NULL、DEFAULT partition、enum 大小寫
    02-seed-data.sqlBug FixBCrypt hash、訂單狀態大小寫、daily_statistics 欄位名稱
    OrderUpsertConsumerBug Fix.get() → .path()，移除 unused import
    ReturnUpsertConsumerBug Fix加 stats dirty marker、移除 unused import
    DailyStatisticsServiceBug Fixearly return 時刪除過時 stats 列
    OrderServiceBug FixNOT NULL 欄位的 null 守衛
    docker-compose.ymlInfra所有 21 個 Java 容器加 JAVA_TOOL_OPTIONS
    UserOrderControllerFeature新增 POST /api/user/orders → Kafka pipeline
    docker/test-data-generator/FeaturePython seeder，透過 API 打假訂單

    結語：追蹤路徑比結果更重要

    今天花最多時間的不是寫 code，而是「把對的事情弄清楚」。Seeder 寫了三個版本，不是因為技術難，而是因為對系統的理解在逐漸深化。

    一個好的事件驅動系統，它的「正確入口」只有一個。找到那個入口，比快速把功能做出來更重要。這條原則同樣適用於大系統的任何角落：追蹤路徑比結果更重要，因為你下次出問題的時候，你需要知道訊息從哪裡來、往哪裡去。

    能走事件流就走事件流。能用快取盡量快取。這不是教條，是讓大系統在出問題時還能被追蹤、被診斷、被修復的保險。

  • 多通路電商 OMS 系統實戰：系列導讀

    2026 年：AI 衝擊下的軟體產業

    這是一個特殊的時代。

    SaaS 股票從 2021 年的高點崩跌 70-80%。曾經被視為「永遠成長」的軟體訂閱模式，現在面臨嚴峻的質疑。AI 能夠寫程式碼、能夠自動化客服、能夠生成內容——很多人問：軟體工程師還有未來嗎？

    現實的聲音：

    • 「AI 可以寫 80% 的 CRUD，還需要工程師嗎？」
    • 「Copilot 已經能自動補全程式碼了」
    • 「低代碼平台會取代傳統開發」
    • 「SaaS 已死，ARR 不再性感」

    在這個背景下，為什麼我還要寫這系列文章？為什麼 OMS 這種「傳統」的企業系統還有存在價值？

    AI 無法取代的部分

    讓我們誠實面對：AI 確實改變了很多事。但有些東西，AI 要做到需要企業級的整合架構：

    AI 能做的 AI 要做到這些，需要什麼
    生成 CRUD 程式碼 整合架構讓 AI 知道該改哪裡
    寫單元測試 系統設計讓 AI 理解業務邏輯
    補全程式碼片段 標準化介面讓 AI 能套用模式
    呼叫 API OMS 提供統一的 API 讓 AI 操作
    分析數據 系統整合好的數據讓 AI 分析
    關鍵洞察：AI Agent、MCP 等技術正在讓 AI 能操作系統。但 AI 要發揮作用，需要標準化的底層架構。OMS 不是被 AI 取代的對象，而是讓 AI 能發揮的基礎設施。

    SaaS 崩跌教會我們什麼？

    2021 年，SaaS 公司用 30-50 倍 ARR 估值。2024 年，同樣的公司只剩 5-8 倍。這不是 SaaS 模式有問題，而是市場重新認識了什麼是真正的價值。

    泡沫時期的迷思 現實
    用戶增長就是一切 能留住用戶、能收到錢才是
    燒錢換市佔 正向現金流才能活下去
    功能越多越好 解決核心痛點比較重要
    技術債以後再還 技術債會讓你跑不動
    OMS 系統的價值：它不是「酷炫的新創產品」，而是「讓電商能正常運作的基礎設施」。每天處理訂單、同步庫存、產生出貨單——這些boring but essential的事情，才是真正的商業價值。

    為什麼 OMS 在 2026 年仍然重要？

    1. 電商只會更複雜，不會更簡單

    2020 年：蝦皮、Momo、PChome
    2024 年：加上 TikTok Shop、Shopee Food、跨境電商
    2026 年：更多新平台、更多整合需求

    平台越多，整合的需求越大。AI 可以幫你寫對接程式碼，但決定該怎麼對接、如何處理例外，還是需要人。

    2. 「無聊」的系統反而更持久

    一個觀察：最持久的軟體系統，往往是那些「不性感」的：

    • 銀行核心系統（COBOL 跑了 50 年）
    • ERP 系統（SAP 依然是企業標配）
    • 訂單管理系統（每個電商都需要）

    這些系統不會上 TechCrunch 頭條，但它們每天都在創造價值。

    3. AI 是工具，不是替代品

    我現在寫程式碼，確實會用 AI 輔助。但 AI 給我的是草稿，我需要：

    • 理解業務需求，決定架構方向
    • 審核 AI 生成的程式碼是否符合系統設計
    • 處理 AI 不知道的「公司內部潛規則」
    • 跟平台 API 變更搏鬥（AI 不知道蝦皮上週改了什麼）

    這系列文章的價值

    這不是一篇「如何用某個框架」的教學。這是真實企業系統的設計思考。

    你能學到的 為什麼重要
    工廠模式整合多平台 AI 時代更需要好的架構設計
    事件驅動處理高併發 擴展性是系統長期價值的關鍵
    多租戶認證 SaaS 模式的技術基礎
    分散式系統的觀測性 系統越複雜，可觀測性越重要
    Kubernetes 部署 雲原生是現在的標配
    核心觀點：技術會變，但解決問題的思維方式不會變。理解為什麼這樣設計、權衡了什麼、踩過什麼坑——這些經驗在 AI 時代反而更珍貴。

    回到最初的問題：為什麼需要 OMS？

    想像你是一個電商賣家，同時在蝦皮、Momo、Yahoo、PChome、樂天等 17 個平台上銷售商品。

    每天的噩夢：

    • 登入 17 個後台看訂單
    • 在 17 個平台更新庫存
    • 處理 17 種不同格式的出貨單
    • 應付 17 種不同的 API 規格變更

    AI 能幫你自動回覆客服訊息，但它不會幫你把蝦皮的訂單自動同步到你的倉儲系統。這種系統整合的工作，需要專門設計的軟體。

    商業價值（數字說話）

    70%
    人力成本降低
    10x
    處理速度提升
    99%
    庫存準確率
    80%
    擴展成本降低

    這些數字怎麼來的？讓我拆解給你看。

    計算基礎：一個中型電商的假設

    參數 數值 說明
    日均訂單量 500 單 中型電商規模
    銷售平台數 5 個 蝦皮、Momo、Yahoo、PChome、官網
    SKU 數量 2,000 個 中型商品數
    客服/營運人員月薪 35,000 元 含勞健保約 42,000

    1. 人力成本降低 70%：怎麼算的？

    沒有 OMS 的人力配置：

    工作內容 每日耗時 需要人力
    登入 5 個平台抓訂單 2 小時 × 3 次/天 1 人
    手動輸入訂單到 ERP 500 單 × 2 分鐘 2 人
    更新 5 個平台庫存 2,000 SKU × 5 平台 1 人
    產生出貨單（各平台格式） 500 單 × 3 分鐘 1 人
    合計 5 人

    有 OMS 的人力配置：

    工作內容 每日耗時 需要人力
    訂單自動同步 0（系統自動） 0
    審核異常訂單 約 5% 需人工，50 單 × 2 分鐘 0.2 人
    庫存自動同步 0（系統自動） 0
    批次產生出貨單 點一下，500 單 × 0.1 分鐘 0.1 人
    系統維運/例外處理 每天約 2-3 小時 0.5 人
    客服（不變） 需處理客戶問題 0.7 人
    合計 1.5 人
    計算：(5 – 1.5) / 5 = 70% 人力減少

    年省成本：3.5 人 × 42,000 元 × 12 月 = 176 萬元/年

    2. 處理速度提升 10 倍：怎麼算的？

    沒有 OMS（手動流程）：

    步驟 耗時 說明
    平台抓單 等待下次人工抓取 平均等 2-4 小時
    人工輸入 ERP 2-5 分鐘/單 容易出錯要重做
    列印出貨單 3-5 分鐘/單 各平台格式不同
    撿貨出貨 實際作業時間 約 30 分鐘
    總計 4-8 小時 從下單到出貨

    有 OMS（自動流程）：

    步驟 耗時 說明
    訂單自動同步 5 分鐘內 Webhook 或輪詢
    自動寫入系統 即時 無需人工
    批次產生出貨單 1 分鐘/批 統一格式
    撿貨出貨 實際作業時間 約 20 分鐘（有優化動線）
    總計 25-35 分鐘 從下單到出貨
    計算：6 小時 / 30 分鐘 = 12 倍（取保守值 10 倍）

    3. 庫存準確率 85% → 99%：怎麼算的？

    沒有 OMS 的庫存問題：

    問題來源 發生頻率 影響
    平台 A 賣掉，平台 B 還沒更新 每天 5-10 次 超賣
    人工輸入錯誤 約 2% 錯誤率 庫存不準
    更新延遲（人力不足） 下班後無人更新 隔夜超賣
    多平台庫存加總錯誤 每週發生 帳實不符

    估算：2,000 SKU，每天約 300 個有異動，其中 15% 會有某種不準確 = 約 85% 準確率

    有 OMS 的庫存管理：

    • 單一庫存來源，自動同步到所有平台
    • 賣出立即扣庫存，無延遲
    • 異常（負庫存）自動警示
    • 剩餘的 1% 誤差來自：實體盤點差異、退貨處理時間差
    結果：系統化管理後，準確率提升到 99%

    減少損失：假設超賣一次平均損失 500 元（退款 + 負評 + 平台罰款），每天減少 5 次 = 每月省 75,000 元

    4. 擴展成本降低 80%：怎麼算的？

    沒有 OMS，新增一個平台：

    工作項目 耗時 成本
    研究平台 API 文件 1-2 週 工程師人力
    開發訂單同步 2-3 週 工程師人力
    開發庫存同步 1-2 週 工程師人力
    開發出貨單格式 1 週 工程師人力
    測試、修 bug、上線 2-4 週 工程師 + QA
    營運人員培訓 1 週 培訓成本
    總計 8-12 週 約 50-80 萬

    有 OMS，新增一個平台：

    工作項目 耗時 成本
    研究平台 API 文件 3-5 天 工程師人力
    實作 ChannelAction 介面 1 週 套用現有架構
    DTO 轉換器 3-5 天 格式對照
    測試、上線 1 週 已有測試框架
    營運人員培訓 1 天 介面相同，只是多一個選項
    總計 2-3 週 約 10-15 萬
    計算：(60萬 – 12萬) / 60萬 = 80% 成本降低

    時間：從 2-3 個月縮短到 2-3 週

    ROI 總結

    效益項目 年度價值 計算方式
    人力成本節省 176 萬 3.5 人 × 42K × 12 月
    超賣損失減少 90 萬 75K × 12 月
    新通路快速上線（假設年增 2 個） 96 萬 48 萬 × 2 個通路
    出貨效率提升（減少延遲出貨罰款） 36 萬 估算
    年度總效益 約 400 萬
    注意：以上數字基於「日均 500 單、5 個平台」的中型電商假設。實際效益會因公司規模、產業特性而異。但數量級是對的——OMS 的 ROI 通常在 1-2 年內就能回本。

    投資成本與風險揭露

    講完效益，也要誠實談成本和風險。

    導入成本估算

    項目 自建開發 SaaS 方案
    初期建置 300-800 萬 0-50 萬
    月費/維護 5-15 萬（團隊） 2-10 萬（訂閱）
    導入期 6-12 個月 1-3 個月
    客製化程度 完全可控 受限於平台
    回本期 1-2 年 3-6 個月

    常見失敗風險

    導入 OMS 可能失敗的原因：

    • 需求不明確：沒釐清要解決什麼問題就開始開發
    • 低估平台複雜度：每個電商平台的 API 都有坑
    • 團隊能力不足：沒有足夠的開發和維運資源
    • 變更管理失敗：使用者不願意改變工作流程
    • 過度客製化：追求完美導致永遠做不完

    市場方案比較

    自建 OMS 不是唯一選擇。以下是常見方案的比較：

    方案類型 代表產品 適合誰 優點 缺點
    SaaS OMS 91APP、CYBERBIZ、EasyStore 中小型電商 快速上線、低成本、有人維護 客製化受限、數據在別人手上
    平台原生工具 蝦皮賣家中心、Momo 後台 單平台賣家 免費、原生整合 只能管單一平台、功能受限
    ERP 模組 SAP、Oracle、鼎新 大型企業 財務整合、企業級穩定 重、貴、慢、電商功能弱
    自建系統 本文討論的方式 有 IT 團隊的中大型電商 完全客製、數據自主、可深度整合 開發成本高、需要團隊維護
    選擇建議：

    • 日均 < 100 單、1-2 平台：用平台原生工具就好
    • 日均 100-500 單、3-5 平台：考慮 SaaS OMS
    • 日均 > 500 單、5+ 平台、有特殊需求：考慮自建或深度客製

    實際案例參考

    以下是幾個匿名化的導入案例：

    案例 A：服飾品牌（成功）

    規模 日均 800 單、7 個平台
    原本痛點 6 人團隊處理訂單、每天加班、超賣頻繁
    導入方式 自建 OMS，開發期 8 個月
    結果 縮減到 2 人、超賣降到每月 1-2 次、14 個月回本
    關鍵成功因素 老闆全力支持、IT 主管有電商經驗

    案例 B：3C 經銷商（部分成功）

    規模 日均 300 單、4 個平台
    原本痛點 ERP 和電商平台脫鉤、手動對帳
    導入方式 先用 SaaS，後來部分自建
    結果 訂單處理自動化成功，但庫存同步仍有問題
    教訓 低估了 ERP 整合的複雜度

    案例 C：食品電商（失敗重來）

    規模 日均 200 單、3 個平台
    原本痛點 想提升效率、老闆看到別人有就想要
    導入方式 外包開發
    結果 做了 6 個月、花了 150 萬、最後沒上線
    失敗原因 需求一直變、外包商不懂電商、內部沒人能接手
    案例啟示：導入 OMS 不是花錢就會成功。需要明確的需求、有能力的團隊、管理層支持三者缺一不可。

    OMS 可能不適合你

    誠實說，不是每家公司都需要 OMS：

    如果你符合以下情況，可能不需要（或還不需要）OMS：

    • 只在 1-2 個平台銷售：平台原生工具夠用
    • 日均訂單 < 50 單：人工處理得過來，ROI 不划算
    • 沒有 IT 資源：系統會變成另一個維護包袱
    • 業務模式還在摸索：需求不穩定，系統做了也會一直改
    • 現金流緊張：有更急迫的事情要處理

    反思：如果人工作業者也用 AI 呢？

    這是 2026 年必須面對的問題：如果營運人員也會用 ChatGPT、Copilot 等 AI 工具，還需要 OMS 嗎？

    AI 能幫助人工作業的部分

    工作內容 AI 能幫的 效率提升
    填寫表格 自動補全、格式轉換 2x
    回覆客戶訊息 生成範本回覆 3x
    整理 Excel 資料 公式生成、格式處理 2x
    查詢訂單狀態 整理多平台資訊（需人工複製貼上） 1.5x
    產生報表 數據分析、圖表建議 2x

    AI 無法幫助的部分

    關鍵限制：AI 是「對話工具」，不是「系統整合工具」

    • 無法登入平台後台：AI 不能幫你登入蝦皮抓訂單
    • 無法即時同步：你睡覺時，AI 也不會幫你更新庫存
    • 無法批次操作：AI 一次處理一個問題，不能同時處理 500 張訂單
    • 無法跨系統傳遞：AI 不能自動把訂單從蝦皮寫進你的 ERP
    • 無法 24/7 運作：沒有人下指令，AI 就不會動

    調整後的人力需求比較

    情境 需要人力 年人事成本
    純人工（無 AI） 5 人 252 萬
    人工 + AI 輔助 3 人（效率提升約 40%） 151 萬
    OMS 系統 1.5 人 76 萬
    OMS + AI 輔助 1 人（例外處理更快） 50 萬

    重新計算 ROI

    比較基準改變：「人工 + AI」vs「OMS」

    效益項目 人工+AI vs 純人工 OMS vs 人工+AI
    人力成本節省 省 101 萬/年 再省 75 萬/年
    超賣損失 無改善（還是會漏） 省 90 萬/年
    處理速度 快 1.5 倍 快 10 倍
    24/7 運作 不可能 可以
    新通路擴展 一樣要重新訓練人 2-3 週上線
    結論：即使人工作業者使用 AI，OMS 仍然每年省下約 200 萬（75 萬人力 + 90 萬超賣損失 + 其他效益）。

    原因：AI 讓「人」更有效率，但 OMS 解決的是「系統整合」問題——這兩者是不同層次的事情。

    真正的比較：「人+AI」vs「系統+AI」

    情境 A：人工 + AI
    ─────────────────────────────────
    人 → ChatGPT 幫忙寫回覆 → 人複製貼上到平台
    人 → 登入蝦皮看訂單 → 人手動輸入 ERP → 人更新其他平台庫存
    人 → AI 幫忙整理 Excel → 人複製貼上到各系統

    瓶頸：每個動作都需要「人」當中介

    情境 B：OMS 系統 + AI
    ─────────────────────────────────
    訂單 → OMS 自動同步 → 自動進 ERP → 自動更新所有平台庫存
    人 → AI 幫忙處理例外 → 在 OMS 一個介面完成
    報表 → 系統自動產生 → AI 幫忙分析

    瓶頸：只有「例外」需要人處理

    思考框架：

    • AI 提升「點」的效率：讓單一任務做得更快
    • OMS 解決「線」的問題：讓流程自動串連
    • 兩者結合才是最佳解：自動化流程 + AI 處理例外

    系統架構全景圖

    這 10 篇技術文章涵蓋了 OMS 系統的各個層面，以下是它們在系統中的位置：

    ┌─────────────────────────────────────────────────────────────────────────┐
    │ 外部平台層 │
    │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
    │ │ 蝦皮 │ │ Momo │ │ Yahoo │ │ PChome │ │ … │ │
    │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
    │ │ │ │ │ │ │
    │ └───────────┴───────────┴───────────┴───────────┘ │
    │ │ │
    │ ┌──────────▼──────────┐ │
    │ │ [6] HTTP 客戶端 │ ← OkHttp 連線池、重試機制 │
    │ │ [8] JSON 序列化 │ ← 時區處理、格式轉換 │
    │ └──────────┬──────────┘ │
    └───────────────────────────────┼─────────────────────────────────────────┘
    │
    ┌───────────────────────────────▼─────────────────────────────────────────┐
    │ 整合層 │
    │ │
    │ ┌─────────────────────────────────────────────────────────────────┐ │
    │ │ [1] 工廠模式 + 策略模式 │ │
    │ │ ChannelFactory → ShopeeAction / MomoAction / YahooAction … │ │
    │ └─────────────────────────────────────────────────────────────────┘ │
    │ │
    │ ┌─────────────────────────────────────────────────────────────────┐ │
    │ │ [5] DTO 設計 │ │
    │ │ 外部 DTO ←→ Converter ←→ 內部 DTO │ │
    │ └─────────────────────────────────────────────────────────────────┘ │
    │ │
    └───────────────────────────────┬─────────────────────────────────────────┘
    │
    ┌───────────────────────────────▼─────────────────────────────────────────┐
    │ 核心服務層 │
    │ │
    │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
    │ │ OrderService │ │InventorySync│ │ ShippingServ │ │
    │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
    │ │ │ │ │
    │ └───────────────────┼───────────────────┘ │
    │ │ │
    │ ┌──────────────────────────▼──────────────────────────────────────┐ │
    │ │ [3] 多租戶認證 │ │
    │ │ Token 驗證 → SecurityContext → 商戶隔離 │ │
    │ └─────────────────────────────────────────────────────────────────┘ │
    │ │
    │ ┌──────────────────────────────────────────────────────────────┐ │
    │ │ [7] PDF 生成 ← 出貨單、撿貨單、對帳單 │ │
    │ └──────────────────────────────────────────────────────────────┘ │
    │ │
    └───────────────────────────────┬─────────────────────────────────────────┘
    │
    ┌───────────────────────────────▼─────────────────────────────────────────┐
    │ 訊息層 │
    │ │
    │ ┌─────────────────────────────────────────────────────────────────┐ │
    │ │ [2] Kafka 事件驅動 │ │
    │ │ Producer → Topics (per channel) → Consumer Jobs │ │
    │ └─────────────────────────────────────────────────────────────────┘ │
    │ │
    └───────────────────────────────┬─────────────────────────────────────────┘
    │
    ┌───────────────────────────────▼─────────────────────────────────────────┐
    │ 基礎設施層 │
    │ │
    │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
    │ │ [4] 健康檢查 │ │ [9] 分散式追蹤 │ │ [10] K8s 部署 │ │
    │ │ Actuator │ │ OpenTracing │ │ Helm Charts │ │
    │ │ 自訂 Indicator │ │ Jaeger │ │ ConfigMap │ │
    │ └────────────────┘ └────────────────┘ └────────────────┘ │
    │ │
    └─────────────────────────────────────────────────────────────────────────┘
    閱讀建議：

    • 從頭開始：按順序讀，理解系統如何從外到內設計
    • 解決特定問題：直接跳到對應章節
    • 架構設計師：重點看 [1] 工廠模式、[2] Kafka、[10] K8s
    • 後端工程師：重點看 [3] 認證、[5] DTO、[6] HTTP

    系列文章導覽

    # 主題 解決什麼問題 AI 時代的價值
    1 工廠模式 整合 17 個平台的不同 API 架構設計思維
    2 Kafka 事件驅動 高併發訂單處理 分散式系統設計
    3 多租戶認證 一套系統服務多商戶 SaaS 技術基礎
    4 健康檢查 自動監控系統狀態 可觀測性
    5 DTO 設計 管理數百個資料物件 程式碼組織
    6 HTTP 客戶端 穩定呼叫外部 API 整合實務
    7 PDF 生成 統一出貨標籤格式 API 設計
    8 JSON 序列化 處理不同平台的時區 資料處理
    9 分散式追蹤 追蹤請求在各服務的流向 除錯能力
    10 K8s 部署 管理 17+ 個服務部署 雲原生技能

    適合讀者

    角色 可以學到
    正在焦慮的工程師 AI 時代什麼能力還有價值
    想轉型的技術人 企業系統的實戰經驗
    技術主管 如何設計可擴展的系統
    電商從業者 技術如何解決業務痛點

    關於作者

    Tom｜10+ 年軟體工程經驗

    經歷過幾個時代：

    • 2010s：傳統 SI、CRM 系統
    • 2015+：電商爆發、系統整合
    • 2020s：雲原生、微服務
    • 2024+：AI 衝擊、重新定位

    這系列文章來自在精誠開發多通路電商 OMS 系統的實戰經驗。不是教科書理論，是真正上線運營、處理過各種奇怪問題的心得。

    寫這些文章的原因：在 AI 時代，我相信「理解系統為什麼這樣設計」比「會寫程式碼」更有價值。希望這些經驗對你有幫助。

    下一步

    如果你是工程師：

    如果你是技術主管或決策者：

    • 想評估貴公司是否適合導入 OMS？歡迎來信交流
    • 需要技術諮詢或系統規劃？我提供電商系統架構顧問服務
    聯絡方式：

    這是「多通路電商 OMS 系統實戰」系列的導讀篇。點擊上方表格中的連結，深入每個技術主題。

  • K8s 部署實戰：Helm Charts 與服務編排

    商業價值：標準化部署讓「17 個通路獨立升級不互相影響」，確保 導讀篇提到的「系統穩定性」——單一通路故障不會拖垮整個系統。

    為什麼不用其他方案？

    方案 優點 缺點 適用場景
    Helm Charts（本文） 標準化、版本控制、可重用 學習曲線 多服務微服務架構
    純 YAML 簡單直接 重複多、難維護 單一服務
    Kustomize 原生支援 複雜覆寫較難 簡單環境差異
    Docker Compose 開發方便 不適合生產環境 本地開發

    前言：微服務部署的挑戰

    多通路 OMS 系統包含：

    服務類型 數量 說明
    Consumer Job 17+ 個 每個通路一個
    API 服務 10+ 個 訂單、商品、物流等
    Web 前端 3 個 商戶、管理、OpenAPI
    問題：如何有效管理這麼多服務的部署？

    解決方案：Helm Charts

    Chart 目錄結構

    helm/
    └── oms-consumer-shopee/
    ├── Chart.yaml # Chart 基本資訊
    ├── values.yaml # 預設變數
    ├── values-dev.yaml # 開發環境
    ├── values-prod.yaml # 正式環境
    ├── config/ # 應用程式配置
    │ ├── application.yml
    │ └── logback.xml
    └── templates/ # K8s 資源模板
    ├── deployment.yaml
    ├── service.yaml
    └── configmap.yaml

    Deployment 設定

    # templates/deployment.yaml
    apiVersion: apps/v1
    kind: Deployment
    metadata:
    name: {{ .Chart.Name }}
    namespace: oms
    labels:
    app: {{ .Chart.Name }}

    spec:
    replicas: {{ .Values.replicas }}
    selector:
    matchLabels:
    app: {{ .Chart.Name }}

    template:
    metadata:
    annotations:
    # ConfigMap 變更時自動觸發滾動更新
    checksum/config: {{ include (print $.Template.BasePath “/configmap.yaml”) . | sha256sum }}
    # Prometheus 監控
    prometheus.io/scrape: “true”
    prometheus.io/path: /metrics
    prometheus.io/port: “8080”

    labels:
    app: {{ .Chart.Name }}
    version: {{ .Values.image.version }}

    spec:
    containers:
    – name: {{ .Chart.Name }}
    image: “{{ .Values.image.repository }}:{{ .Values.image.version }}”
    imagePullPolicy: {{ .Values.image.pullPolicy }}

    # 資源限制
    resources:
    requests:
    cpu: {{ .Values.resources.requests.cpu }}
    memory: {{ .Values.resources.requests.memory }}
    limits:
    cpu: {{ .Values.resources.limits.cpu }}
    memory: {{ .Values.resources.limits.memory }}

    # 健康檢查
    livenessProbe:
    httpGet:
    path: /health/liveness
    port: 8080
    initialDelaySeconds: 30
    periodSeconds: 10

    readinessProbe:
    httpGet:
    path: /health/readiness
    port: 8080
    initialDelaySeconds: 20
    periodSeconds: 5

    # 優雅關閉
    lifecycle:
    preStop:
    exec:
    command: [“curl”, “-XPOST”, “http://localhost:8080/shutdown”]

    values.yaml：環境變數化

    # values.yaml（預設值）
    replicas: 2

    image:
    repository: registry.example.com/oms/consumer-shopee
    version: latest
    pullPolicy: Always

    resources:
    requests:
    cpu: 100m
    memory: 256Mi
    limits:
    cpu: 1000m
    memory: 1Gi

    # values-prod.yaml（正式環境覆寫）
    replicas: 5

    image:
    version: v1.2.3
    pullPolicy: IfNotPresent

    resources:
    requests:
    cpu: 500m
    memory: 512Mi
    limits:
    cpu: 2000m
    memory: 2Gi

    部署指令

    # 開發環境
    helm upgrade –install consumer-shopee ./helm/oms-consumer-shopee \
    -f values-dev.yaml

    # 正式環境
    helm upgrade –install consumer-shopee ./helm/oms-consumer-shopee \
    -f values-prod.yaml \
    –set image.version=v1.2.3

    Secret 管理

    # 敏感資訊不放在 values.yaml
    env:
    – name: DB_USERNAME
    valueFrom:
    secretKeyRef:
    name: db-credentials
    key: username

    – name: DB_PASSWORD
    valueFrom:
    secretKeyRef:
    name: db-credentials
    key: password

    # 建立 Secret
    kubectl create secret generic db-credentials \
    –namespace oms \
    –from-literal=username=admin \
    –from-literal=password=secret123

    ConfigMap 管理

    # templates/configmap.yaml
    apiVersion: v1
    kind: ConfigMap
    metadata:
    name: {{ .Chart.Name }}-config
    data:
    {{ (.Files.Glob “config/*”).AsConfig | indent 2 }}
    效果：config/ 目錄下的檔案會自動打包成 ConfigMap

    健康檢查整合

    Probe 類型 端點 失敗行為
    liveness /health/liveness 重啟 Pod
    readiness /health/readiness 從 Service 移除
    # 分離 liveness 和 readiness
    livenessProbe:
    httpGet:
    path: /health/liveness
    port: 8080
    initialDelaySeconds: 30 # 啟動後等待時間
    periodSeconds: 10 # 檢查間隔
    timeoutSeconds: 5 # 超時時間
    failureThreshold: 3 # 失敗幾次後重啟

    readinessProbe:
    httpGet:
    path: /health/readiness
    port: 8080
    initialDelaySeconds: 20
    periodSeconds: 5
    failureThreshold: 3

    多通路部署策略

    17 個通路，每個都有獨立的 Helm Chart：

    helm/
    ├── oms-consumer-shopee/
    ├── oms-consumer-momo/
    ├── oms-consumer-yahoo/
    ├── oms-consumer-pchome/
    ├── oms-consumer-rakuten/
    ├── oms-consumer-shopify/
    ├── oms-consumer-shopline/
    └── … (共 17 個)

    批次部署腳本

    #!/bin/bash

    CHANNELS=(
    “shopee”
    “momo”
    “yahoo”
    “pchome”
    “rakuten”
    “shopify”
    “shopline”
    )

    VERSION=$1

    for channel in “${CHANNELS[@]}”; do
    echo “Deploying $channel…”

    helm upgrade –install “consumer-${channel}” \
    “./helm/oms-consumer-${channel}” \
    –set image.version=$VERSION \
    –namespace oms

    done

    echo “All channels deployed!”

    Service 與 Ingress

    # templates/service.yaml
    apiVersion: v1
    kind: Service
    metadata:
    name: {{ .Chart.Name }}
    namespace: oms
    spec:
    type: ClusterIP
    ports:
    – port: 80
    targetPort: 8080
    name: http
    selector:
    app: {{ .Chart.Name }}
    # Ingress 設定（API Gateway）
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
    name: oms-api-gateway
    annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    spec:
    rules:
    – host: api.example.com
    http:
    paths:
    – path: /orders
    pathType: Prefix
    backend:
    service:
    name: order-service
    port:
    number: 80

    CI/CD 整合

    # .gitlab-ci.yml
    stages:
    – build
    – deploy

    build:
    stage: build
    script:
    – docker build -t registry.example.com/oms/consumer-shopee:$CI_COMMIT_SHA .
    – docker push registry.example.com/oms/consumer-shopee:$CI_COMMIT_SHA

    deploy-dev:
    stage: deploy
    script:
    – helm upgrade –install consumer-shopee ./helm/oms-consumer-shopee
    –set image.version=$CI_COMMIT_SHA
    -f values-dev.yaml
    only:
    – develop

    deploy-prod:
    stage: deploy
    script:
    – helm upgrade –install consumer-shopee ./helm/oms-consumer-shopee
    –set image.version=$CI_COMMIT_TAG
    -f values-prod.yaml
    only:
    – tags
    when: manual

    實戰踩坑

    踩坑 1：ConfigMap 改了但 Pod 沒更新
    情境：改了 application.yml 但服務行為沒變
    原因：K8s 不會自動重啟 Pod，舊的 ConfigMap 還在記憶體中
    解法：在 Deployment 加 checksum annotation，ConfigMap 變化時觸發滾動更新
    踩坑 2：OOM Killed 但沒收到告警
    情境：服務突然重啟，查了半天才發現是記憶體不足
    原因：JVM heap 設定超過 container limits，被 K8s 強制 kill
    解法：JVM heap 設為 limits 的 70%，並設定 Prometheus 告警監控 OOM 事件
    踩坑 3：滾動更新時服務中斷
    情境：部署新版本時用戶收到 502 錯誤
    原因：新 Pod 還沒 ready 就把舊 Pod 砍掉，或 preStop 沒有 graceful shutdown
    解法：設好 readinessProbe + preStop hook，確保流量先切換再關閉

    總結

    設計 效果
    Helm Chart 標準化 每個服務結構一致，易於維護
    values 分環境 同一 Chart 部署不同環境
    ConfigMap 動態載入 配置與程式碼分離
    Secret 管理 敏感資訊安全儲存
    健康檢查整合 K8s 自動管理故障
    多通路獨立部署 故障隔離，獨立升級
    上一篇 系列目錄 完結
    OpenTracing分散式追蹤 系列導讀 本篇為系列最終篇

    這是「多通路電商 OMS 系統實戰」系列的最終篇。感謝閱讀，希望對你的系統設計有所幫助！

  • 分散式追蹤：OpenTracing 整合實戰

    商業價值：分散式追蹤讓「問題定位從小時變分鐘」，直接支援 導讀篇提到的「系統穩定性」——當訂單卡在某個環節時，能快速找到是哪個服務出問題。

    為什麼不用其他方案？

    方案 優點 缺點 適用場景
    B3 + Jaeger（本文） 業界標準、視覺化強 需要額外部署 微服務架構
    Log 關聯查詢 簡單 跨服務追蹤困難 單體應用
    Zipkin 輕量 功能較少 小型微服務
    商業 APM 功能完整 費用高 預算充足團隊

    前言：微服務的可觀測性挑戰

    在多通路系統中，一個訂單請求的流程可能是：

    使用者 → API Gateway → Order Service → Kafka → Consumer Job → 蝦皮 API
    ↓
    資料庫更新
    ↓
    回呼通知
    問題：當某個環節出問題時，如何追蹤請求在各服務之間的流向？

    這就是分散式追蹤（Distributed Tracing）要解決的問題。

    追蹤標準：B3 Propagation

    我們採用 B3 標準，定義一組 HTTP Header 來傳遞追蹤資訊：

    Header 說明 範例
    x-request-id 請求唯一識別碼 uuid-xxxx
    x-b3-traceid 追蹤 ID（整個請求鏈共用） abc123
    x-b3-spanid 當前操作 ID def456
    x-b3-parentspanid 父操作 ID abc123
    x-b3-sampled 是否取樣 1

    實作：傳遞追蹤 Header

    定義追蹤 Header 清單

    public class TracingHeaders {

    public static final List<String> HEADERS = List.of(
    “x-request-id”,
    “x-b3-traceid”,
    “x-b3-spanid”,
    “x-b3-parentspanid”,
    “x-b3-sampled”,
    “x-b3-flags”
    );
    }

    從 Request 提取追蹤 Header

    @Component
    public class TracingExtractor {

    /**
    * 從 HTTP Request 提取追蹤 Header
    */
    public Map<String, String> extract(HttpServletRequest request) {
    Map<String, String> tracingHeaders = new HashMap<>();

    for (String headerName : TracingHeaders.HEADERS) {
    String value = request.getHeader(headerName);
    if (value != null && !value.isEmpty()) {
    tracingHeaders.put(headerName, value);
    }
    }

    return tracingHeaders;
    }
    }

    使用情境

    情境 1：API 呼叫外部服務

    @RestController
    public class OrderController {

    @Autowired private TracingExtractor tracingExtractor;
    @Autowired private HttpClientService httpClient;

    @GetMapping(“/api/orders/{orderId}”)
    public Order getOrder(
    @PathVariable String orderId,
    HttpServletRequest request) {

    // 1. 提取追蹤 Header
    Map<String, String> tracingHeaders = tracingExtractor.extract(request);

    // 2. 呼叫外部 API，傳遞追蹤 Header
    HttpResult result = httpClient.get(
    “https://api.platform.com/orders/” + orderId,
    tracingHeaders
    );

    return parseOrder(result);
    }
    }

    情境 2：Kafka 訊息傳遞

    // Producer：將追蹤資訊放入訊息
    public String buildMessage(Object body, Map<String, String> tracingHeaders) {
    Map<String, Object> message = new HashMap<>();

    // Header 包含追蹤資訊
    Map<String, Object> header = new HashMap<>();
    header.put(“version”, 1);
    header.put(“tracing”, tracingHeaders);

    message.put(“header”, header);
    message.put(“body”, body);

    return JsonUtil.toJson(message);
    }

    // Consumer：從訊息取出追蹤資訊
    public void processMessage(String message) {
    Map<String, Object> data = JsonUtil.toMap(message);
    Map<String, Object> header = (Map) data.get(“header”);

    // 取出追蹤 Header
    Map<String, String> tracingHeaders = (Map) header.get(“tracing”);

    // 呼叫外部 API 時繼續傳遞
    HttpResult result = httpClient.get(platformApiUrl, tracingHeaders);
    }

    自動傳遞：Filter + ThreadLocal

    @Component
    public class TracingFilter implements Filter {

    @Autowired
    private TracingExtractor extractor;

    @Override
    public void doFilter(
    ServletRequest request,
    ServletResponse response,
    FilterChain chain) throws IOException, ServletException {

    HttpServletRequest httpRequest = (HttpServletRequest) request;

    // 提取追蹤 Header 放入 ThreadLocal
    Map<String, String> tracingHeaders = extractor.extract(httpRequest);
    TracingContext.set(tracingHeaders);

    try {
    chain.doFilter(request, response);
    } finally {
    TracingContext.clear();
    }
    }
    }

    // ThreadLocal 儲存
    public class TracingContext {

    private static final ThreadLocal<Map<String, String>> CONTEXT =
    new ThreadLocal<>();

    public static void set(Map<String, String> headers) {
    CONTEXT.set(headers);
    }

    public static Map<String, String> get() {
    Map<String, String> headers = CONTEXT.get();
    return headers != null ? headers : Collections.emptyMap();
    }

    public static void clear() {
    CONTEXT.remove();
    }
    }

    效果：HTTP 客戶端自動帶入追蹤 Header，開發者不用手動處理。

    整合 Jaeger

    Jaeger 是常用的分散式追蹤系統，可以視覺化追蹤鏈。

    Spring Boot 設定

    # application.yml
    opentracing:
    jaeger:
    enabled: true
    udp-sender:
    host: jaeger-agent
    port: 6831
    log-spans: true
    probabilistic-sampler:
    sampling-rate: 1.0 # 100% 取樣（生產環境調低）

    追蹤視覺化

    ┌─────────────────────────────────────────────────────────────────┐
    │ Trace: abc123 │
    ├─────────────────────────────────────────────────────────────────┤
    │ ▼ api-gateway [45ms] │
    │ ├─ order-service [30ms] │
    │ │ ├─ kafka-produce [5ms] │
    │ │ └─ db-query [10ms] │
    │ └─ consumer-job [25ms] │
    │ └─ platform-api [20ms] │
    └─────────────────────────────────────────────────────────────────┘

    錯誤追蹤

    @Aspect
    @Component
    public class TracingAspect {

    @Autowired
    private Tracer tracer;

    @Around(“execution(* com.example..*Service.*(..))”)
    public Object trace(ProceedingJoinPoint joinPoint) throws Throwable {
    Span span = tracer.buildSpan(joinPoint.getSignature().getName()).start();

    try {
    return joinPoint.proceed();

    } catch (Exception e) {
    // 記錄錯誤到追蹤系統
    span.setTag(“error”, true);
    span.log(Map.of(
    “event”, “error”,
    “error.message”, e.getMessage(),
    “error.class”, e.getClass().getName()
    ));
    throw e;

    } finally {
    span.finish();
    }
    }
    }

    實戰踩坑

    踩坑 1：ThreadLocal 洩漏到其他請求
    情境：偶發看到 traceId 對不上，追蹤鏈混亂
    原因：Filter 的 finally 沒有正確清理 ThreadLocal，執行緒池重用導致污染
    解法：確保 TracingContext.clear() 一定會執行，可用 try-finally 或 Spring 的 RequestContextHolder
    踩坑 2：Kafka Consumer 追蹤斷裂
    情境：Producer 到 Consumer 的追蹤連不起來
    原因：只在 HTTP 層傳遞 Header，忘了在 Kafka 訊息中嵌入追蹤資訊
    解法：Producer 把 tracingHeaders 放進訊息 header，Consumer 取出後設回 ThreadLocal
    踩坑 3：取樣率設 100% 撐爆 Jaeger
    情境：Jaeger 儲存空間暴增，查詢變慢
    原因：生產環境忘了調低 sampling-rate，每個請求都記錄
    解法：生產環境設 0.1（10%）或更低，搭配動態取樣根據錯誤率調整

    總結

    設計 效果
    B3 標準 Header 相容主流追蹤系統
    Filter 自動提取 開發者不需手動處理
    ThreadLocal 儲存 任何地方都能取得追蹤資訊
    Kafka 嵌入 異步訊息也能追蹤
    Jaeger 整合 視覺化追蹤鏈
    上一篇 系列目錄 下一篇
    JSON處理與時區管理 系列導讀 Kubernetes Helm Charts 部署

    這是「多通路電商 OMS 系統實戰」系列的第九篇。下一篇會介紹 Kubernetes 部署。

  • Jackson JSON 序列化：時區與日期處理

    商業價值：正確的時區處理讓「跨平台訂單時間一致」，避免 導讀篇提到的「超賣損失」——如果訂單時間錯誤，先後順序就會亂，庫存扣減就會出問題。

    為什麼不用其他方案？

    方案 優點 缺點 適用場景
    統一 ObjectMapper（本文） 全系統一致、自動時區轉換 需要初期設定 多平台整合系統
    各處自行處理 彈性高 格式不一致、時區 bug 頻發 單一平台小專案
    字串直接儲存 簡單 無法比較、排序困難 純展示用途
    Gson 輕量 時區支援較弱、擴展性差 簡單 JSON 處理

    前言：跨時區系統的日期處理

    多通路系統需要處理各種日期格式：

    平台 日期格式 範例
    蝦皮 Unix timestamp 1710748800
    Yahoo ISO 8601 2024-03-18T15:30:00+08:00
    Momo 台灣時間字串 2024/03/18 15:30:00
    資料庫 UTC 2024-03-18T07:30:00Z
    問題：如果沒有統一處理，時區 bug 會在各種轉換中出現

    解決方案：統一 JSON 處理

    ObjectMapper 設定

    @Configuration
    public class JsonConfig {

    @Bean
    public ObjectMapper objectMapper() {
    ObjectMapper mapper = new ObjectMapper();

    // 1. 允許序列化私有欄位
    mapper.setVisibility(PropertyAccessor.FIELD, Visibility.ANY);

    // 2. 日期格式設定
    mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
    mapper.setDateFormat(new SimpleDateFormat(“yyyy-MM-dd’T’HH:mm:ss.SSS’Z’”));

    // 3. 設定 UTC 時區
    mapper.setTimeZone(TimeZone.getTimeZone(“UTC”));

    // 4. 支援 Java 8 時間 API
    mapper.registerModule(new JavaTimeModule());

    // 5. 自定義序列化器
    SimpleModule module = new SimpleModule();
    module.addSerializer(ZonedDateTime.class, new ZonedDateTimeSerializer());
    mapper.registerModule(module);

    // 6. 忽略未知欄位（平台加新欄位不會報錯）
    mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);

    return mapper;
    }
    }

    設定 效果
    FIELD visibility 不需要 getter 也能序列化
    UTC 時區 系統內部統一用 UTC
    JavaTimeModule 支援 LocalDate、ZonedDateTime 等
    忽略未知欄位 API 加新欄位不會報錯

    自定義日期序列化器

    public class ZonedDateTimeSerializer extends JsonSerializer<ZonedDateTime> {

    private static final DateTimeFormatter FORMATTER =
    DateTimeFormatter.ofPattern(“yyyy-MM-dd’T’HH:mm:ss.SSS’Z’”);

    @Override
    public void serialize(
    ZonedDateTime value,
    JsonGenerator gen,
    SerializerProvider provider) throws IOException {

    // 無論輸入什麼時區，都轉成 UTC 輸出
    ZonedDateTime utc = value.withZoneSameInstant(ZoneId.of(“UTC”));
    gen.writeString(FORMATTER.format(utc));
    }
    }

    效果展示

    // 輸入：台灣時間
    ZonedDateTime taiwanTime = ZonedDateTime.now(ZoneId.of(“Asia/Taipei”));
    // 2024-03-18T15:30:00+08:00[Asia/Taipei]

    // 輸出：自動轉成 UTC
    String json = objectMapper.writeValueAsString(Map.of(“time”, taiwanTime));
    // {“time”:”2024-03-18T07:30:00.000Z”}

    JSON 工具類

    @Component
    public class JsonUtil {

    private static ObjectMapper mapper;

    @Autowired
    public void setMapper(ObjectMapper mapper) {
    JsonUtil.mapper = mapper;
    }

    /**
    * 物件轉 JSON
    */
    public static String toJson(Object obj) {
    try {
    return mapper.writeValueAsString(obj);
    } catch (JsonProcessingException e) {
    throw new JsonException(“序列化失敗”, e);
    }
    }

    /**
    * JSON 轉物件
    */
    public static <T> T fromJson(String json, Class<T> clazz) {
    try {
    return mapper.readValue(json, clazz);
    } catch (JsonProcessingException e) {
    throw new JsonException(“反序列化失敗”, e);
    }
    }

    /**
    * JSON 轉泛型物件
    */
    public static <T> T fromJson(String json, TypeReference<T> type) {
    try {
    return mapper.readValue(json, type);
    } catch (JsonProcessingException e) {
    throw new JsonException(“反序列化失敗”, e);
    }
    }

    /**
    * JSON 轉 List
    */
    public static <T> List<T> fromJsonList(String json, Class<T> clazz) {
    try {
    JavaType type = mapper.getTypeFactory()
    .constructCollectionType(List.class, clazz);
    return mapper.readValue(json, type);
    } catch (JsonProcessingException e) {
    throw new JsonException(“反序列化失敗”, e);
    }
    }

    /**
    * JSON 轉 Map
    */
    public static Map<String, Object> toMap(String json) {
    return fromJson(json, new TypeReference<>() {});
    }
    }

    平台日期轉換

    public class DateConverter {

    /**
    * Unix timestamp → ZonedDateTime（蝦皮）
    */
    public static ZonedDateTime fromUnixTimestamp(long timestamp) {
    return Instant.ofEpochSecond(timestamp)
    .atZone(ZoneId.of(“UTC”));
    }

    /**
    * ISO 8601 → ZonedDateTime（Yahoo）
    */
    public static ZonedDateTime fromISO(String isoString) {
    return ZonedDateTime.parse(isoString);
    }

    /**
    * 台灣時間字串 → ZonedDateTime（Momo）
    */
    public static ZonedDateTime fromTaiwanTime(String timeStr) {
    DateTimeFormatter formatter =
    DateTimeFormatter.ofPattern(“yyyy/MM/dd HH:mm:ss”);

    LocalDateTime ldt = LocalDateTime.parse(timeStr, formatter);
    return ldt.atZone(ZoneId.of(“Asia/Taipei”));
    }

    /**
    * 轉成台灣時間顯示
    */
    public static String toTaiwanDisplay(ZonedDateTime time) {
    ZonedDateTime taiwanTime = time.withZoneSameInstant(
    ZoneId.of(“Asia/Taipei”)
    );
    return taiwanTime.format(
    DateTimeFormatter.ofPattern(“yyyy/MM/dd HH:mm:ss”)
    );
    }
    }

    使用範例

    // 從蝦皮 API 取得資料
    long shopeeTimestamp = 1710748800;
    ZonedDateTime orderTime = DateConverter.fromUnixTimestamp(shopeeTimestamp);

    // 存入資料庫（UTC）
    order.setCreatedAt(orderTime);
    orderRepository.save(order);

    // 回傳 API（自動轉成 UTC JSON）
    return JsonUtil.toJson(order);
    // {“createdAt”:”2024-03-18T08:00:00.000Z”}

    // 前端顯示（轉成台灣時間）
    String display = DateConverter.toTaiwanDisplay(order.getCreatedAt());
    // 2024/03/18 16:00:00

    實戰踩坑

    踩坑 1：時區雙重轉換
    情境：前端顯示時間比實際晚 8 小時
    原因：資料庫已經是 UTC，但讀取時又被當成本地時間再轉一次 UTC
    解法：確保 JDBC 連線設定 serverTimezone=UTC，並且 Entity 用 ZonedDateTime 而非 Date
    踩坑 2：蝦皮 timestamp 單位搞錯
    情境：訂單時間顯示成 1970 年
    原因：蝦皮回傳秒級 timestamp，但程式用 Instant.ofEpochMilli() 處理
    解法：確認平台 API 文件的時間單位，秒用 ofEpochSecond，毫秒用 ofEpochMilli
    踩坑 3：SimpleDateFormat 執行緒不安全
    情境：高併發時偶發日期解析錯誤或 NumberFormatException
    原因：把 SimpleDateFormat 設成 static 共用
    解法：改用 DateTimeFormatter（執行緒安全），或每次 new 新的 SimpleDateFormat

    總結

    設計 效果
    統一 ObjectMapper 全系統一致的 JSON 處理
    UTC 儲存 避免時區混亂
    自定義序列化 控制輸出格式
    平台轉換器 各平台格式統一處理
    上一篇 系列目錄 下一篇
    PDF生成與Builder Pattern 系列導讀 OpenTracing分散式追蹤

    這是「多通路電商 OMS 系統實戰」系列的第八篇。下一篇會介紹分散式追蹤。

  • PDF 生成最佳實踐：Builder 模式的優雅 API

    商業價值：統一的 PDF 生成讓「出貨單、撿貨單一鍵產生」，直接支撐 導讀篇提到「處理速度提升 10 倍」——從每單 3 分鐘縮短到批次 1 秒。

    前言：電商系統的 PDF 需求

    OMS 系統需要產生各種 PDF 文件：

    文件類型 用途 特殊需求
    出貨標籤 貼在包裹上 條碼、收件人資訊
    訂單明細 放在包裹內 商品清單、金額
    撿貨單 倉庫作業 商品位置、數量
    對帳單 商戶結算 表格、統計
    挑戰：傳統 PDF 產生程式碼冗長、難以維護

    解決方案：Builder 模式

    使用範例（先看效果）

    // 產生出貨單 PDF
    byte[] pdf = PdfBuilder.create()
    .title(“出貨單”)
    .separator()
    .text(“訂單編號：ORD-2024-001234”)
    .text(“出貨日期：2024-03-18”)
    .newLine()
    .subtitle(“商品明細”)
    .table(orderItems)
    .newLine()
    .subtitle(“收件資訊”)
    .text(“收件人：王小明”)
    .text(“電話：0912-345-678”)
    .text(“地址：台北市信義區信義路五段7號”)
    .newPage()
    .image(barcodeBytes)
    .build();
    效果：程式碼像文件結構一樣直覺，易讀易維護

    PdfBuilder 實作

    核心結構

    public class PdfBuilder {

    private List<Element> elements = new ArrayList<>();
    private FontConfig fontConfig;

    // 工廠方法
    public static PdfBuilder create() {
    return new PdfBuilder(FontConfig.defaultConfig());
    }

    public static PdfBuilder create(FontConfig config) {
    return new PdfBuilder(config);
    }

    private PdfBuilder(FontConfig config) {
    this.fontConfig = config;
    }
    }

    文字方法

    /**
    * 標題（最大字體）
    */
    public PdfBuilder title(String text) {
    elements.add(new TextElement(text, fontConfig.getTitleFont()));
    return this; // 回傳 this 支援鏈式呼叫
    }

    /**
    * 副標題
    */
    public PdfBuilder subtitle(String text) {
    elements.add(new TextElement(text, fontConfig.getSubtitleFont()));
    return this;
    }

    /**
    * 一般文字
    */
    public PdfBuilder text(String text) {
    elements.add(new TextElement(text, fontConfig.getBodyFont()));
    return this;
    }

    /**
    * 粗體文字
    */
    public PdfBuilder boldText(String text) {
    elements.add(new TextElement(text, fontConfig.getBoldFont()));
    return this;
    }

    版面控制

    /**
    * 換行
    */
    public PdfBuilder newLine() {
    elements.add(new NewLineElement());
    return this;
    }

    /**
    * 分隔線
    */
    public PdfBuilder separator() {
    elements.add(new SeparatorElement());
    return this;
    }

    /**
    * 換頁
    */
    public PdfBuilder newPage() {
    elements.add(new NewPageElement());
    return this;
    }

    表格支援

    /**
    * 新增表格
    * @param data 二維資料，第一列為標題
    */
    public PdfBuilder table(List<List<String>> data) {
    elements.add(new TableElement(data, TableStyle.BORDERED));
    return this;
    }

    /**
    * 新增表格（指定樣式）
    */
    public PdfBuilder table(List<List<String>> data, TableStyle style) {
    elements.add(new TableElement(data, style));
    return this;
    }

    圖片與條碼

    /**
    * 新增圖片
    */
    public PdfBuilder image(byte[] imageBytes) {
    elements.add(new ImageElement(imageBytes));
    return this;
    }

    /**
    * 新增條碼（自動產生）
    */
    public PdfBuilder barcode(String content) {
    byte[] barcodeImage = BarcodeGenerator.generate(content);
    elements.add(new ImageElement(barcodeImage));
    return this;
    }

    輸出 PDF

    /**
    * 產生 PDF byte 陣列
    */
    public byte[] build() {
    ByteArrayOutputStream output = new ByteArrayOutputStream();
    Document document = new Document(PageSize.A4);

    try {
    PdfWriter.getInstance(document, output);
    document.open();

    for (Element element : elements) {
    if (element instanceof NewPageElement) {
    document.newPage();
    } else {
    document.add(element.render());
    }
    }

    document.close();

    } catch (DocumentException e) {
    throw new PdfGenerationException(“PDF 產生失敗”, e);
    }

    return output.toByteArray();
    }

    /**
    * 直接寫入檔案
    */
    public void toFile(String filename) {
    byte[] pdf = build();
    try (FileOutputStream fos = new FileOutputStream(filename)) {
    fos.write(pdf);
    } catch (IOException e) {
    throw new PdfGenerationException(“檔案寫入失敗”, e);
    }
    }

    中文字型支援

    public class FontConfig {

    private static final String FONT_PATH = “/fonts/NotoSansTC-Regular.ttf”;
    private BaseFont baseFont;

    public static FontConfig defaultConfig() {
    return new FontConfig();
    }

    private FontConfig() {
    try {
    // 載入支援中文的字型
    baseFont = BaseFont.createFont(
    FONT_PATH,
    BaseFont.IDENTITY_H, // Unicode 支援
    BaseFont.EMBEDDED // 嵌入字型
    );
    } catch (Exception e) {
    throw new RuntimeException(“字型載入失敗”, e);
    }
    }

    public Font getTitleFont() {
    return new Font(baseFont, 24, Font.BOLD);
    }

    public Font getSubtitleFont() {
    return new Font(baseFont, 18, Font.BOLD);
    }

    public Font getBodyFont() {
    return new Font(baseFont, 12, Font.NORMAL);
    }

    public Font getBoldFont() {
    return new Font(baseFont, 12, Font.BOLD);
    }
    }

    完整範例：出貨單

    public byte[] generateShippingLabel(Order order) {
    // 準備商品明細表格
    List<List<String>> items = new ArrayList<>();
    items.add(List.of(“商品”, “數量”, “單價”, “小計”));

    for (OrderItem item : order.getItems()) {
    items.add(List.of(
    item.getName(),
    String.valueOf(item.getQuantity()),
    formatPrice(item.getPrice()),
    formatPrice(item.getSubtotal())
    ));
    }

    items.add(List.of(“合計”, “”, “”, formatPrice(order.getTotal())));

    // 產生 PDF
    return PdfBuilder.create()
    // 標題區
    .title(“出貨單”)
    .separator()
    .text(“訂單編號：” + order.getOrderId())
    .text(“出貨日期：” + LocalDate.now())
    .newLine()

    // 條碼
    .barcode(order.getOrderId())
    .newLine()

    // 商品明細
    .subtitle(“商品明細”)
    .table(items)
    .newLine()

    // 收件資訊
    .subtitle(“收件資訊”)
    .text(“收件人：” + order.getReceiverName())
    .text(“電話：” + order.getReceiverPhone())
    .text(“地址：” + order.getReceiverAddress())

    .build();
    }

    總結

    設計 效果
    Builder 模式 鏈式呼叫，程式碼簡潔
    流式 API 像寫 HTML 一樣直覺
    字型抽象 換字型只改一處
    元件化 表格、圖片、條碼都是元件

    為什麼不用其他方案？

    方案 優點 缺點 結論
    HTML 轉 PDF 會 HTML 就會用 排版難控制、分頁問題 簡單報表可用
    Word 範本 業務人員能改 需要額外軟體、格式問題 不推薦
    JasperReports 功能強大 學習曲線陡、設計器難用 複雜報表可考慮
    iText + Builder 程式碼控制、可測試 要寫程式碼 工程師友好

    實戰踩坑

    坑 1：中文字型問題

    預設字型不支援中文，產出的 PDF 全是方框。要嵌入支援中文的字型（如 Noto Sans TC）。第一次載入字型要 2-3 秒，後來改成應用程式啟動時預載。

    坑 2：出貨單格式每平台不同

    蝦皮、Momo、Yahoo 的出貨單長得不一樣。最初想做成一模一樣，後來發現不可能（平台會檢查格式）。解法：只統一「我們自己的出貨單」，平台的標籤用平台 API 下載。

    坑 3：大量 PDF 記憶體爆炸

    一次產生 500 張出貨單，記憶體直接爆。解法：改成串流處理，產一張輸出一張，不要全部放在記憶體。

    系列導航

    ◀ 上一篇
    HTTP 客戶端    		 📚 返回目錄 下一篇 ▶
    JSON 序列化