知識寫入框架前，依「受眾 x 形態」二軸決定載體。載體錯置有兩種代價：寫進自動載入層 → token 污染（attention 稀釋 + 45k 預算耗盡）；困在專案 memory → 跨專案失傳。本方法論是頂層地圖；各載體的細部規範（如有）路由至 Reference 所列文件。

Scope：本地圖涵蓋 LLM context 載體（人與 AI 閱讀的知識）；專案產物層（docs/ / src/）不屬本地圖，劃分見 framework-asset-separation.md；機器讀取層（config/*.yaml、hook 引用的凍結錨點）另計。memory 行由受眾軸「僅本專案」唯一決定，不需形態軸。

代理人定義 vs skill 的歸屬判準：一段知識可能落在代理人定義或 skill、不易區分時，以「該知識是否隨執行者改變」為判準，不憑直覺擇一。

• 屬代理人定義的知識回答「你是誰、你能做什麼、你偏好怎麼做」——身份定位、授權邊界、設計偏好。識別測試：換一個代理人來執行，這段內容就應該不同。本質是人格與授權。
• 屬 skill 的知識回答「這件事怎麼做」——可重複執行的流程步驟。識別測試：任何角色觸發都應得到同一份流程，與執行者是誰無關。本質是可重複流程。

兩者衝突時，對該知識套用識別測試「換一個代理人，內容會不會變」：會變則歸代理人定義；不會變、任何角色執行都應一致則歸 skill。

載體地圖（受眾 x 載入時機 x 形態）

執行步驟

1. 受眾是誰？（所有角色 / 僅 PM / 全體代理人 / 單一代理人 / 動作觸發者 / 僅本專案）→ 縮小候選載體。「動作觸發者」統括地圖表受眾欄的按需情境詞（觸發者 / 主動查閱者 / 執行特定動作者 / 任務前查詢者）
2. 形態是什麼？（行為禁令 / 調度流程 / 身份偏好 / 工作流方法 / 理念清單 / 技術參考 / 失敗案例 / 專案設定）→ 確定載體
3. 候選屬自動載入層（CLAUDE.md / rules/ / MEMORY.md）？→ 過預算閘門；規範類知識的閘門是必要性否決（「這是否每回合都需要？」否則外移按需層）+ 形態降為「禁令 + 路由」，專案設定 / 指令等事實類的閘門是體積與專案特定性約束（精簡陳述、不含框架通用知識），不適用必要性否決
4. skill / methodology / rule 三選一拿不準 → framework-meta-methodology.md 決策樹
5. 寫完 grep 概念詞，盤點與既有規範的指令方向矛盾，並對齊執法強度（PC-V1-006）

代理人定義內容規範

檢查清單

• 受眾 x 形態二軸定位完成，不是「順手寫在開啟中的檔案」？
• 自動載入層寫入已過預算閘門；規範類形態已降為禁令 + 路由（事實類過閘門即可）？
• 代理人定義新增內容屬「偏好 / 邊界」而非「流程 / 方法」？
• 重複內容用路由取代複製（單一來源）？
• 概念詞 grep 矛盾盤點 + 執法強度對齊完成（PC-V1-006）？

Reference

• .claude/methodologies/framework-meta-methodology.md — skill / methodology / rule 三分決策樹 + 30 秒標準（形態軸的細分）
• .claude/references/framework-asset-separation.md — 框架資產 vs 專案產物、專案設定 vs 代理人知識、Skill Hook 雙層
• .claude/references/auto-load-stub-conventions.md — 自動載入層 stub 構成 + 外移 SOP + 預算驗證
• .claude/rules/core/agent-definition-standard.md — 代理人三區塊結構標準
• .claude/rules/README.md — 自動載入預算原則（每回合必要性自問）
• .claude/pm-rules/pm-quality-baseline.md 規則 7 — memory 升級四問 + 升級目的地預算閘門 + 升級即搬家
• .claude/README.md「同步機制」章 — 寫作類 skill（compositional-writing / multi-round-review）內容 SSOT 在 blog repo，框架端為回流副本；依地圖判定「寫作方法 → skills/」後，內容修改應到上游 repo 執行
• .claude/skills/skill-design-guide/SKILL.md — skills 載體的細部規範（官方規格、frontmatter、漸進揭露結構）

Last Updated: 2026-06-15 Version: 1.8.0 — 「代理人定義 vs skill 歸屬判準」改寫：去除「一句話判定」總結框架，改為含明確識別測試（換一個執行者內容是否改變）的判準段落。方法論作為框架核心規則供 AI 開發時判斷，內容須明確而可套用，不採壓縮式總結（避免單句總結遮蔽判準細節導致 AI 判斷失準） Version: 1.7.0 — root 錯置檔重分配（1.0.0-W8-023.2，第 2/4 批）：4 檔（agent-collaboration.md 794 / decision-workflows.md 116 / quick-ref-agent-dispatch-recovery.md 202 / thinking-process.md 271）逐檔讀內容後全數 flag superseded/obsolete（campaign 規則 3，零搬移零連結手術）：agent-collaboration 與 analyses/archived/ 同名 794 行副本 near-identical 且內容已被 methodologies/tdd-collaboration-flow.md + agent 定義覆蓋；decision-workflows 五情境已被 pm-rules/skip-gate+incident-response+decision-tree 覆蓋；quick-ref-agent-dispatch-recovery 所述 agent_dispatch_recovery.py hook 已不存在；thinking-process 為 2025-12-01 一次性 session 快照非知識載體。本批 0 檔搬移，故不加 map 行，留 PM follow-up 清理（inbound 連結多在 .3/.4 批檔群） Version: 1.6.0 — root 錯置檔重分配（1.0.0-W8-023.1，第 1/4 批）：hook-system-reference.md（Hook 事件索引 / 技術參考）、code-smell-checklist.md（Code Smell 檢測清單 / 技術參考）依二軸（受眾＝動作觸發者、形態＝技術參考）歸入既有 references/ 載體列（line 22），故不另加 map 行；superseded 副本 code-quality-examples.md（已遷 docs/，DOC-010 W10-102）與 document-responsibilities.md（DEPRECATED，已被 five-document-system-methodology.md + doc-flow/references/document-responsibilities.md 取代）flag 不併入，留 PM follow-up Version: 1.5.0 — 載體地圖補列 4 個 legit root 資產各一行歸屬（README 框架導覽 / CHANGELOG 變更記錄 / README-subtree-sync 同步機制 / terminology-dictionary 用語規範表，後者經 language-constraints @ 引用實質載入）（1.0.0-W8-022） Version: 1.4.0 — multi-round-review Round 4（實例分配演練）修正：步驟 1 補受眾詞彙映射橋（六選項 vs 地圖表受眾欄斷層）、步驟 3 事實類閘門判準明文化（體積與專案特定性約束，非必要性否決）。8 條盲跑 6 條乾淨落點，停止訊號達成收斂 Version: 1.3.0 — multi-round-review Round 3 修正：Scope 句（LLM context 載體限定 + 機器讀取層另計 + memory 受眾軸唯一決定）、rules/core 列量測集合精確化（MEMORY.md 不在 guardian 集合）、規範表補「多方案技術知識庫」劃界列（與 framework-asset-separation「框架寫法」段對齊）、地圖補 templates / root 遺留行、Reference 補 skill-design-guide Version: 1.2.0 — multi-round-review Round 2 修正：檢查清單與步驟 3/5 的 R1 劃界同步（清單漂移）、步驟 5 拆動作解歧義、地圖欄名補形態軸、定位句「（如有）」、Reference 補寫作 skill SSOT 例外路由 Version: 1.1.0 — multi-round-review Round 1 修正：步驟 3 形態約束劃界（規範類 vs 事實類）、步驟 5 補執法強度對齊、章名對齊 methodology 標準結構、rules/core 列預算範圍精確化、agents 列改路由至專節 Version: 1.0.0 — 初始建立：框架知識載體的頂層責任地圖（受眾 x 形態二軸），整合 W7 token 收斂三層防護與既有分離原則；代理人定義內容規範首次權威化（人格與授權 vs 可重複流程）

內容大致分六類：

自察與認知方法論 — 工作前 / 工作中的自我檢視框架。例：

• 5W1H 自察方法論
• AI 任務迴避偵測方法論
• 大規模重構方法論

設計判斷與選型 — 技術決策框架，避免過度設計與設計瑕疵的判斷標準（如 YAGNI 的真實適用條件、成本不對稱性下的選擇邏輯）。例：

• YAGNI 的真實適用條件
• SaaS 選型訪談方法論

敏捷 / 工程流程 — 敏捷實作、重構流程、文件分層。例：

• 敏捷編程方法論
• 敏捷重構方法論
• 5 層文件系統

寫作 / 溝通標準 — 驗收條件、寫作規範。例：

• 驗收條件方法論
• 經驗分享文章的寫作準則

文件與 API 設計 — function 文件分層、測試命名作為 spec、commit message vs source code doc 的職責邊界、型別取代 doc 等表達設計議題。例：

• 函式文件分層設計
• 型別取代 doc 的收益曲線
• 測試命名作為文件
• Commit message vs source code doc

AI 協作工具評估 — Claude Code / Codex / MCP server 等 AI 協作工具的設計拆解、能力邊界、選型對照。包含個別工具的 deep-dive 跟「同題不同工具」的實測。例：

• 三 MCP 工作流與 Dart 實測：cbm / codegraph / serena 的職責分工與三刀流（附三個工具各自的 deep-dive：cbm / codegraph / serena）
• LSP-first 開發方法論：LSP 路線跟其他 code intelligence 路線的取捨
• Background agent 並行研究：用 Claude Code background agent 平行做研究的工作流

跟其他資料夾的邊界

跟 report/ 的區別：record 是「方法論本身怎麼用」（教學 / 中性說明）、report 是「從某個 case 抽出來的原則」（事後檢討 / case-driven）。同一個議題若先有方法論再有 case、方法論寫 record、case 抽出的原則寫 report；若是先出問題再抽原則、直接寫 report。

底下自動列出本資料夾的所有文章、依日期排序。

方法論要解的問題

這套方法論的核心命題是成本不對稱：設計問題拖到開發中途才浮現，修正的代價遠高於在訪談階段多問十題。沒想清楚的操作、沒切清楚的領域邊界、沒被告知的防護缺口，最後都會在開發中途以重工的形式收費。訪談協議的責任是逼這些設計問題在寫第一行程式之前、於已知需求的範圍內浮現——因此訪談問題的數量刻意不設上限，問漏才是成本；節奏上每輪三到五題讓受訪者好消化，輪數跟著覆蓋率走。

協議同時內建「產品名攔截」：受訪者開口指定產品（「我要用 MongoDB」「直接上 k8s」）時，先回到需求確認背後動機（schema 變動頻繁？團隊熟悉度？），需求成立後產品可以直接採納。產品名是選型的輸出，由需求與領域模型推導出來，而非訪談的輸入。

推導鏈：從定錨到決策記錄

整條推導鏈的設計邏輯是：每一站的產出都是下一站的輸入，技術問題永遠錨在前面站點的具體產物上，避免「對空氣選型」。

1定錨 → 交付形態 gate → 操作盤點（BDD）→ domain / event 切分（DDD）
2    → 核心問題與維度展開（每個維度就地過防護底線）→ 決策記錄 + scaffold

定錨。訪談從建立規模假設開始，定錨問題覆蓋七個面向：

• 產品形態（B2B / B2C / 內部工具）——決定合規壓力與流量不確定性的預設方向
• 動機（營收、學習、解決自己的營運問題）——決策記錄理由欄的錨點，「自建換學習」「託管換速度」的權重都從這裡來
• 租戶模型——多租戶把租戶隔離升級成儲存與安全維度的第一級問題
• 預期規模（首年用戶與資料量級）——決定容量維度是否展開
• 團隊能力（人數、production on-call 經驗）——維運經驗低時預設 managed 服務，每個自管元件都要回答「誰半夜處理它」
• 每週可投入時數——一週十小時跟全職的選型分母不同
• 上線時程與迭代節奏——時程緊時選型偏保守，團隊熟悉度的權重高於技術新穎度

定錨答案是後續每個推薦的合法依據——「因為團隊兩人且無維運經驗，推薦 managed 資料庫」這類理由都要能回指到定錨。

交付形態 gate。定錨之後、進入任何技術討論之前，先誠實回答「這個產品現在值得自建嗎」。需求落在現成平台的標準域時，訪談走縮減流程：完整推導跳過，但仍產出託管縮減記錄——平台選擇與理由、可遷出保險狀態、升級自建的 tripwire、防護底線總表的適用項，託管結論同樣留下可追溯的決策記錄。這一站的判讀邏輯單獨成節，見「交付形態 gate」。

操作盤點（BDD）。自建成立後，枚舉所有操作主體（含管理者、客服、訪客、機器角色）與其全部操作，每個操作寫行為情境——Given / When / Then 至少一條主情境加一條失敗情境。誤操作風險成對設計：前端引導（確認對話框、預設值、防呆）與後端防護（驗證、權限、idempotency）一一對應，從介面一路串到伺服器側。行為情境寫不出來，代表那個操作的需求還沒成形——在盤點階段攔下，比開發中途才發現便宜得多。

Domain / event 切分（DDD）。操作清單沿固定方向轉成領域骨架：operation → command → 唯一歸屬 domain → event。推導從操作出發而非資料表出發——從資料表出發會切出 CRUD 式的偽領域（UserManager、OrderManager），從操作出發才會浮現真正的業務領域與領域間需要交換的事實。切分只用兩個原則：

• SRP：一個 domain 一個變更理由、一個 event 一個事實。判讀問題包括「這兩個概念會因為同一個業務原因一起改嗎」「這個規則改變時誰說了算」——組織的決策邊界是領域邊界最誠實的線索。
• OCP：每個 domain 區分公開面（別的 domain 需要知道的：event schema、查詢介面）與內部面（表結構、狀態機、內部規則）。公開面是 contract、變更要盤點訂閱者；內部面可自由改。判讀問題是「Order domain 的表加一個欄位，要通知誰」——理想答案是「不用通知任何人」。

LSP / ISP / DIP（里氏替換、介面隔離、依賴反轉）三個原則刻意留給實作階段：初始化階段還沒有 class 階層、沒有 interface 簇、沒有依賴注入結構，提前套用會把訪談拖進實作細節，模糊掉「邊界在哪」這個此階段的核心問題。

核心問題與維度展開。領域骨架立好後，依序確認需求類型、流量形狀、資料生命週期、失敗代價、成本模型、定位與備援、安全邊界。每題附答案路由：訊號決定哪些技術維度要展開（快取、非同步佇列、容量），哪些維度任何 production 服務都逃不掉（儲存、部署、安全、觀測、可靠性）。

展開時問題錨在領域骨架上——「Order domain 的不可丟 event 用什麼機制送」，而非抽象的「要不要 queue」。每站也帶反向問，因為受訪者描述的是想要的功能，沒想到的東西藏在失敗面：「使用者做完馬上後悔怎麼辦」「凌晨三點服務掛了誰會知道」。

防護底線。每個維度附一份防護底線清單——底線的定義是「缺了它、第一次事故的代價會遠超過 day one 建立它的成本」的項目，例如 secret 管理、備份加至少一次還原驗證、物件層級授權、部署可回滾。底線跟選型的差別在答案空間：選型問題容許多個合理答案並存，底線項目只有「已納入」「已告知後延後」「不適用」三種合法狀態，每一項的狀態都要寫進決策記錄。延後必須轉成記錄：告知代價、記下延後理由、附具體的重評條件（「上線前」「第一個付費客戶前」），「之後再說」這種無期限的口頭妥協會被協議擋下。目的是讓六個月後接手的人能回答「當初為什麼沒做」，把口頭妥協變成可追溯的決策。底線在訪談中經過兩次——維度展開時就地逐項過，決策記錄的總表再核對一次；雙重核對是刻意設計，防止任何一條在長流程中被沉默跳過。

決策記錄。訪談收斂成一份決策記錄：操作風險表、domain map、event catalog、每項技術選型的理由 / 防護狀態 / tripwire 三欄齊備、防護底線總表、規模成長 tripwire 總表。被淘汰的次選項留名字——淘汰原因消失（例如團隊長出維運能力）就是重評入口。scaffold 建議是決策記錄的下游：先確認決策、再產生檔案，決策改了 scaffold 跟著重生。

交付形態 gate：先勸退不必要的自建

一套為自建選型而生的訪談協議，第一個正式任務是勸退不必要的自建。自建的前提是差異化在軟體本身；差異化在商品、內容或服務品質的業務，託管平台、BaaS、垂直 SaaS 可能是成本上更誠實的起點。跳過這個判斷，等於用整套自建流程回答一個本來就該用現成平台解的需求。交付形態光譜的完整論述（各形態的能力邊界、遷出代價、可遷出保險）見 交付形態選型：託管平台、BaaS 與自建的邊界，訪談協議把它操作化成 gate。

gate 的第一個澄清問是身分問題：這個軟體是要賣的產品，還是經營業務的工具？「給健身教練用的課表系統」有兩種身分——要賣給眾多教練的產品（市場上的垂直 SaaS 是競爭對手，走自建），或教練管理自己學員的工具（同一批垂直 SaaS 正是該優先評估的託管候選）。同一句需求描述，兩種身分的結論相反。

回答「先自用、之後想賣」的雙重身分，用時間判準裁決：付費外部用戶離現在多遠。協議把裁決寫成兩條規則：外部買家已有承諾或近期有交付時程的，按「要賣的產品」走完整訪談，自家使用記為首租戶（dogfooding）；外部用戶還停在想像、目前唯一用戶是自己的，託管先行，平台野心轉成升級自建的 tripwire——協議給的觸發例是第一個付費外部用戶出現，或客製需求超出託管平台 API 的承載範圍。

gate 的收尾原則是尊重知情決定：受訪者聽完託管對照後仍選自建時，訪談照常繼續，勸退只做一次；選自建的動機（練手、控制權、長期成本）原樣記進決策記錄，讓未來重評者能還原當時的權重。

用合成 dry-run 驗證協議

方法論本身也需要驗證。這套協議以一組結構化文件存在——訪談流程、各站的判讀表、決策記錄模板都是 agent 可直接執行的文件，驗證因此可以採用合成 dry-run：讓 agent 同時扮演訪談者與 persona 受訪者，從定錨到決策記錄完整走一遍協議，過程中記錄機械性斷點。斷點分五類：

• 路由斷裂：協議指向的段落不存在，或前後站接不上
• gate 矛盾：兩條判讀規則同時命中且結論相反，協議沒給裁決方式
• 重複提問：同一風險在不同階段被當成新問題重新開放問
• 資訊斷流：前站的產出（操作清單、event catalog）沒被後站引用
• 判準缺席：協議要求做判讀，但沒給可操作的判讀條件

dry-run 收尾時實際試填決策記錄模板，量測每個欄位填得出來的比例——填不出來的欄位就是協議在某一站漏問了。

第一輪驗證跑了兩個 persona：一個雙重身分的健身房管理 SaaS（自用兼想賣），一個 solo 開發者的付費電子報（最該被勸退自建的案例）。合計記錄 13 個斷點，在兩個 persona 覆蓋的路徑上路由斷裂為零——協議的檔案結構與觸發路由都接得起來；決策記錄試填率約 85-90%，缺口集中在交付形態相關欄位：gate 判讀依據寫不出來、混合形態的記錄格式沒有規格、自建動機沒有欄位可放。影響最大的斷點是兩個 persona 從不同方向撞上同一個 gate 矛盾：判讀表兩列規則同時命中且方向相反——健身房的「都是」讓垂直 SaaS 列與自建列並立，付費電子報既符合「託管平台標準域」也符合「產品本身是軟體」——協議當時沒有 tie-breaker，在最該被勸退的案例上這個斷點被評為阻斷級；前文的時間判準正是這次修復補上的。矛盾發生在協議最核心的判斷上，且在真實使用者撞到之前被攔下。兩場 dry-run 最終收斂出 8 項修復回寫協議，包括雙重身分的時間判準、混合形態的決策記錄規格、訪談問句去重、跨 domain 寫入的一致性判讀條件。

合成 dry-run 的邊界也要誠實：它抓得到機械性斷點，抓不到真實受訪者的不耐與理解斷層。agent 扮演的 persona 永遠有耐心答完所有問題、永遠聽得懂術語；真實使用者在第四輪提問時的疲乏、對「event catalog」一詞的困惑，要等真人訪談才會浮現。另一層盲點是同源：persona 由產生協議的同一個模型扮演，回答分布偏向協議作者想像得到的案例，超出這個想像的需求形態，結構上不會出現在合成驗證裡。合成驗證的定位是上線前的結構檢查，取代不了真實使用回饋。

適用邊界與下一步

完整協議的固定成本是數輪訪談加一份決策記錄，值得跑的情境有明確輪廓：

• 產品會進 production，有真實使用者與失敗代價——失敗代價是核心問題階段的主要輸入，沒有它整條推導鏈失去分水嶺
• 團隊規模或交接需求讓「當初為什麼這樣選」值得被記錄——決策記錄的三種讀者（確認結論的現在使用者、回溯理由的未來維護者、等訊號的重評者）至少存在兩種
• 領域邊界有切分價值——操作主體超過一種、跨領域協作存在，domain / event 切分的產出才有承載對象

反過來，快速原型與純內部腳本跑完整協議是過度設計——原型的目的是丟棄式驗證假設，設計決策活不過原型本身；這類情境取協議的最小子集就夠：定錨（確認規模假設）加防護底線裡的 secret 管理一條。另一類邊界是需求不可知：產品會進 production、但要提供哪些操作得靠市場驗證才知道的探索型產品，協議能整理的只有已知部分——它解「已知需求沒想清楚」的成本，解不了「需求本身未知」；這類情境先走薄切片迭代，需求穩定後再回來補完整訪談。

判讀方式可以收成一個問題：這個專案的設計決策，六個月後有人需要回答「當初為什麼這樣選」嗎？需要，完整協議的固定成本就划算；無此需求，取子集。

下一步路由：

• 交付形態光譜與各形態的遷出代價：交付形態選型
• 判定自建後的服務選型順序：後端需求分類地圖
• 不可丟 event 的執行層機制：idempotency 與 outbox pattern 知識卡

Statusline 相容設計的核心責任是把「資料輸入契約」和「畫面渲染邏輯」分開。Claude Code 已經提供 command-backed statusline，會把 session JSON 丟進命令的 stdin；Codex 目前公開的設定則是 tui.status_line 字串項目陣列，契約停在內建 footer item 的排列與選擇。

這個差異讓「同一個 statusline 工具同時支援兩邊」要從輸入契約對齊開始。真正要做的是先建立一層輸入正規化：Claude JSON、Codex 既有或未來 JSON、手動測試 JSON 都先轉成同一個內部狀態，再交給同一套 renderer。

Case-first 觀察

Case-first 查詢的目的，是先看社群實際卡在哪裡，再決定要改工具還是改使用方式。本次查詢到的案例集中在 OpenAI Codex repo issue 與官方文件，顯示需求已經存在，但 Codex 的 command-backed statusline 仍屬提案或缺口。

WRAP 判讀

Anchor Check：目標是讓 cc-statusline 的核心能力可被兩種工具共用。使用者真正需要的是少維護一套 statusline 邏輯，並在 Codex 具備 command-backed 入口時保留既有 renderer。

Step 0 資料充足度：足以做工具內部改造，尚不足以宣稱 Codex TUI 目前能直接執行 cc-statusline。官方文件只保證 tui.status_line 是字串陣列；社群 issue 裡的 command JSON 仍是提案階段。

Widen Options：可選方案有三種。

Reality Test：目前 Codex 的公開設定停在內建 item 排列，所以 B 的立即價值是讓工具「具備 Codex 相容輸入能力」。反向驗證是：若未來 Codex 最終採用完全不同的 command JSON，B 的 normalization 層仍只需新增一個 mapper，renderer 可維持同一套。

Attain Distance：B 的長期成本最低，因為 statusline 最容易變動的是輸入欄位名稱，最穩定的是使用者想看的資訊：專案、環境、輸入法、模型、context、rate limit、git worktree。把欄位差異收斂在 normalization 層，能避免每加入一個工具就複製一次畫面邏輯。

Prepare to be Wrong：若 Codex 不採納外部 command statusline，這次改造仍可用於手動測試、tmux status、其他 wrapper，且不影響 Claude Code 原始入口。若 Codex 採納但欄位名稱不同，新增 mapper 即可。

Tripwire：當 OpenAI Codex 文件把 tui.status_line 從 array<string> 擴充為 command 或 table schema 時，重新檢查 cc-statusline 的 Codex mapper。若 Codex issue #17827 關閉並附帶實作 PR，也應重新校準欄位名稱。

實作策略

相容設計的正確切點是輸入正規化層。cc-statusline 應維持一個內部狀態模型，並接受多種外部 payload：

這個切點保留了 Claude Code 既有功能，因為原本的欄位不需要改名，也不需要改設定檔。新增行為只在非 Claude payload 進來時啟動，屬於向後相容的讀取能力。

操作路由

現在可立即使用的路由是 Claude Code 原設定：在 ~/.claude/settings.json 裡設定 statusLine.command 指向 cc-statusline。這條路由使用官方支援的 stdin JSON，適合日常使用。

Codex 目前可立即使用的路由是內建 footer item：在 ~/.codex/config.toml 設定 tui.status_line = [...]。這條路由使用 Codex 內建 renderer，能顯示 Codex 已支援的內建狀態。

未來 Codex 若支援 command-backed statusline，路由應該指向同一個 cc-statusline binary。工具端已經能接受 Codex / generic JSON 時，設定層只要補 command 指向，不需要重寫 renderer。

實測記錄（2026-05-14）

這次排查的核心責任是先確認「工具本身可用」還是「接入路由不對」。先把 binary 行為跟 TUI 設定拆開檢查，才能避免把路由問題誤判成程式 bug。

觀察

• cc-statusline 程式已支援 generic/Codex-style payload，手動餵 JSON 可正確輸出模型與 context 資訊。
• ~/.claude/settings.json 使用 statusLine.command 指向 /Users/mac-eric/go/bin/cc-statusline，Claude Code 路由成立。
• ~/.codex/config.toml 的 tui.status_line 是內建 item 陣列，這條路由不會執行外部 binary。
• Codex 內建 footer 的實際輸出已觀察到：gpt-5.3-codex medium · Context 100% left · ~/project/blog。

判讀

Codex 端「沒有生效」的主因是契約邊界：tui.status_line 只負責排列內建欄位，不負責執行 command。cc-statusline 的 renderer 相容能力屬於預留未來入口，不會在現有 Codex 內建 footer 流程自動觸發。

操作

為了讓 Codex 內建 footer 至少顯示模型與 context 資訊，已調整：

1[tui]
2status_line = ["model-with-reasoning", "context-remaining", "current-dir"]
3status_line_use_colors = true

這個設定可讓 Codex 使用內建項目顯示 model-with-reasoning 與 context remaining；格式由 Codex 內建 renderer 決定，不等同 cc-statusline 的自訂輸出字串。

驗證指令

1printf '%s\n' '{"model":"gpt-5.3-codex","reasoning_effort":"medium","project_root":"~/project/blog","context":{"remaining_percent":100}}' | /Users/mac-eric/go/bin/cc-statusline

預期結果是主行包含 gpt-5.3-codex medium，context 顯示為 Context 100% left。這一步驗證的是 binary 能力，不是 Codex 內建 footer contract。

檢查清單

• Claude Code 原本的 JSON payload 仍能輸出相同欄位。
• Codex / generic payload 不造成 parse error。
• model 同時支援 object 與 string。
• context 同時支援 used percentage 與 remaining percentage。
• rate limit 缺席時只省略對應 segment，不影響專案、模型、git worktree。
• README 明確標示 Codex 目前限制，避免讀者以為 Codex 已能直接執行外部 statusline command。

2026-03，開發線上點單多廚房印表機列印功能。 寫了 28 個測試，全部通過，上實機後陸續發現四個 Bug。

發生了什麼事

功能的核心流程：

1收到追加點單
2  → 把品項分派到對應的廚房印表機
3  → 組裝收據內容（標題、品名+數量、備註等）
4  → 逐行列印
5    → 單行文字（標題、桌號）
6    → 多欄表格（品名 + 數量）

上實機後，四個 Bug 依序出現——因為它們在同一條執行路徑的不同深度，每修一個，程式才能走到下一個：

1Bug 1（印表機內部元件未初始化）
2  ↓ 修好，程式碼走得更遠
3Bug 2（品項分派邏輯錯誤，全部送到同一台）
4  ↓ 修好，兩台印表機都有被呼叫
5Bug 3（多欄表格的欄位寬度不符合規定）
6  ↓ 修好，表格列印通過驗證，繼續往下
7Bug 4（空行觸發第三方 library 的越界錯誤）

為什麼一次只能發現一個 Bug

四個 Bug 都在同一條執行路徑上，只是深度不同。程式走到第一個錯誤就中斷了，後面的都被遮蔽。

而測試沒有發現這些問題，是因為測試沒有走過這條完整路徑。

1真實路徑：  接收訂單 → 組裝收據 → 列印中心 → 表格列印/文字列印 → 印表機底層
2測試路徑：  接收訂單 → 中斷（手動構造結果，後面都沒跑）
3
4後來補了模擬元件：接收訂單 → 模擬收據產生器 → 列印中心 → 模擬印表機 → 底層
5                                  ↑
6                           但模擬的收據只有純文字行
7                           → 文字列印有被覆蓋，表格列印沒有
8                           → Bug 3, 4 仍然隱藏

這次的問題在測試覆蓋的路徑深度。

回顧：這次遇到的五個事故

1. 測試的是「手動構造的結果」，不是「程式的行為」

怎麼發現的： 實機上兩台廚房印表機只有一台收到品項，另一台完全沒動。但測試裡「品項分派邏輯」的測試案例是通過的。

怎麼找到原因的： 回頭看測試程式碼，發現測試裡的分派結果是手動寫死的，不是由分派邏輯算出來的：

1test('品名長度奇數分配到第一台', () {
2  final result = OnlineOrderPrintResult(
3    itemPrinterMapping: {'item-1': 'kitchen-2'}, // 寫死的值
4  );
5  record.applyPrintResult(result);
6  expect(record.kitchenItemPrintJobs['item-1']!.printerId, 'kitchen-2');
7});

這個測試驗證的是「把結果存進去再讀出來，資料有沒有一致」，但品項分派的程式碼從頭到尾沒有被執行過。測試名稱寫的是分派邏輯，實際測的是資料儲存。

怎麼修的： 改成從入口方法開始呼叫，讓品項分派的邏輯實際跑一遍。跑完之後 Bug 2 就出現了——分派邏輯的 fallback 條件寫錯，所有品項都被送到同一台。

2. 只測了子類別自己的方法，沒測從父類別繼承的方法

怎麼發現的： 實機上廚房印表機列印全部失敗，log 顯示內部元件未初始化的錯誤，但測試裡模擬印表機的初始化和列印測試都是通過的。

怎麼找到原因的： 比對測試和實際程式碼的呼叫路徑。測試裡呼叫的是模擬印表機自己覆寫的「送出資料」方法（改成什麼都不做），但實際列印時上層呼叫的是從父類別繼承的「組裝列印指令」方法，這個方法內部依賴一個需要初始化的元件。測試覆蓋到的方法，和實際執行路徑走到的方法不是同一個。

怎麼修的： 在測試中加入對繼承方法的測試——初始化後呼叫「組裝列印指令」確認不報錯，以及未初始化時呼叫確認會拋出錯誤。同時修正模擬印表機的初始化方法，補上內部元件的建立。

3. 斷言只檢查「有沒有」，沒檢查「對不對」

怎麼發現的： 修完 Bug 1 和 2 之後重跑測試，整合測試通過了。但看 log 發現廚房 1 和廚房 2 的列印結果都是 false（失敗），和測試通過的結果矛盾。

怎麼找到原因的： 回頭看斷言，發現寫的是 containsKey：

1expect(result.kitchenResults.containsKey('kitchen-1'), isTrue);

這個斷言只檢查「有沒有這台印表機的結果」，不管結果是成功還是失敗。列印在 try-catch 裡失敗後回傳 false，但 key 存在，所以斷言通過。

怎麼修的： 改成直接檢查值 expect(result.kitchenResults['kitchen-1'], isTrue)。改完之後測試立刻失敗，顯示列印結果確實是 false。這才發現測試環境缺少收據產生器的依賴，列印路徑在組裝收據的步驟就斷了，被 try-catch 吞掉回傳 false。

4. 模擬元件的回傳資料只覆蓋了部分分支

怎麼發現的： 修完 Bug 1、2，也修正了斷言（坑 3）之後，測試全過，列印結果也都是 true。但上實機測試時，廚房印表機仍然全部失敗，log 顯示「欄位寬度總和必須等於 12」。

怎麼找到原因的： 測試環境和實機的差異在於收據的內容。實機用的是真實的廚房收據模板，包含多欄表格（品名+數量）。測試用的是模擬的收據產生器，只回傳一行純文字：

1class FakeReceiptBuilderService extends ReceiptBuilderService {
2  Future<List<ReceiptLine>> buildReceiptLines(...) async {
3    return [ReceiptLine.singleLine(data.title)]; // 只有標題
4  }
5}

純文字走的是「文字列印」，多欄表格走的是「表格列印」——這是兩條不同的分支。模擬的資料只觸發了文字列印，表格列印從未被測試執行過。

• 純文字列印有被覆蓋 → 沒問題
• 多欄表格列印沒有被觸發 → Bug 3 仍然隱藏
• 空行列印沒有被觸發 → Bug 4 仍然隱藏

怎麼修的： 在印表機的表格列印方法中加入自動正規化，將欄位比例換算為符合 library 要求的總和 12。這是適配層的修復，所有收據模板都不需要修改。

5. 第三方 library 的地雷——前面都做對了才踩到

怎麼發現的： 修完 Bug 3 之後再上實機，廚房印表機仍然失敗，但錯誤訊息不同了——從「欄位寬度總和必須等於 12」變成「RangeError: Valid value range is empty: 0」。

怎麼找到原因的： 從 log 看到列印標題和桌號成功（兩次資料送出），在第三行（空行）就失敗了。追蹤到第三方 library 的原始碼，發現它在解析文字時會取第一個字元來判斷是否為中文字，但沒有處理空字串的情況，直接對空字串取 text[0] 導致越界。

這個問題一直存在，但之前 Bug 3 擋在前面（程式在表格列印就失敗了，走不到後面的空行列印），前三個 Bug 都修好之後，執行路徑才真正打通，觸發了這個潛在問題。

從另一個角度看，能走到 Bug 4 代表前面的修復都是有效的。

怎麼修的： 在呼叫 library 之前加了空字串的前置檢查，遇到空字串時改用換行指令代替，繞過 library 的問題。

6. try-catch 的範圍太大，把程式碼 bug 和硬體故障混在一起處理

怎麼發現的： 回顧整個除錯過程，Bug 1、3、4 都有一個共同特徵——錯誤被 try-catch 吞掉，回傳 false，沒有任何明顯的異常。在測試中，缺少依賴的情況也被同樣的 try-catch 吞掉，測試照樣通過。

怎麼找到原因的： 看列印方法的 catch 區塊：

 1Future<bool> _printKitchenReceipt(...) async {
 2  try {
 3    // 組裝收據資料
 4    // 組裝收據行
 5    // 呼叫印表機列印
 6    return true;
 7  } catch (e) {
 8    debugPrint('failed: $e');
 9    return false;
10  }
11}

catch (e) 攔截了所有錯誤，不區分類型。但這裡面混了兩種性質不同的錯誤：

• 印表機故障（連線逾時、無紙、裝置離線）→ 執行期的預期狀況，應該攔截，回傳失敗讓 UI 顯示重印按鈕
• 程式碼 bug（未初始化的元件、欄位寬度不合法、空字串越界）→ 開發階段就該被發現的問題，不應該被靜默吞掉

四個 Bug 裡有三個屬於後者，全部被同一個 catch (e) 攔住，在開發和測試階段都沒有任何異常跡象。

怎麼修的： 做了三件事：

1. 定義 PrinterException，專門代表印表機硬體/連線錯誤
2. 在列印中心（IO 邊界）把印表機拋出的 Exception 包成 PrinterException，但不攔截 Error（程式碼 bug）
3. 列印方法改為 on PrinterException catch，只處理印表機故障

改動前後的對比：

 1// 改動前：所有錯誤都被吞掉
 2try {
 3  final lines = await receiptBuilder.buildReceiptLines(data, template);  // ← 出錯也被吞
 4  await printCenter.printReceiptLines(lines: lines, printer: printer);   // ← 出錯也被吞
 5  return true;
 6} catch (e) {
 7  return false;
 8}
 9
10// 改動後：資料準備不在 try 裡，只攔截印表機錯誤
11final lines = await receiptBuilder.buildReceiptLines(data, template);  // ← 出錯直接拋出
12
13try {
14  await printCenter.printReceiptLines(lines: lines, printer: printer);
15  return true;
16} on PrinterException catch (e) {  // ← 只攔截印表機故障
17  return false;
18}

改完之後，測試裡缺少依賴的情況不再被吞掉——之前有一組測試預期列印結果是 false（因為缺收據產生器被 catch 吞掉），現在補上依賴後預期改為 true，測試驗證的是真正的列印行為。

從這次經驗歸納的測試方法

一、從呼叫路徑出發，而非從程式碼結構出發

這次犯的最大錯誤是按照「這個 class 有哪些方法」來分配測試，結果每個方法各自通過，但串在一起就出問題。後來改成按「使用者操作觸發了什麼路徑」來規劃：

 1使用者操作                    要測試的完整路徑
 2─────────                    ──────────────
 3追加點餐送出     →  handler.printAppendedOrder
 4                      → _buildItemPrinterMapping  ← 分派邏輯
 5                      → buildReceiptLines          ← 收據組裝
 6                      → printReceiptLines           ← 實際列印
 7                      → printText / printRow        ← 印表機操作
 8
 9點擊重印按鈕     →  retryItemKitchenPrint
10                      → printAppendedOrder(kitchenItemIds: {itemId})

按路徑規劃之後，每個測試案例都會走過完整的鏈路，中間環節的問題自然會被觸發。

二、整合測試與單元測試的分工

這次的六個坑裡，有四個（坑 1、3、4、6）屬於「元件之間銜接」的問題，單元測試各自通過但串接失敗。回頭看分工：

 1                    單元測試                     整合測試
 2─────────────────────────────────────────────────────────
 3測什麼？          單一方法的輸入輸出             多個元件串接的結果
 4假設什麼？        其他元件是正確的               驗證元件之間的銜接
 5能抓到什麼 Bug？  演算法邏輯錯誤                 初始化遺漏、依賴缺失、
 6                                                介面不匹配、狀態傳遞錯誤
 7本案例中          KitchenPrinterConfig           printAppendedOrder +
 8                  .handlesProduct                PrintCenter + FakePrinter +
 9                  → 匹配邏輯正確                 ReceiptBuilderService
10                                                → 端到端路徑正確

這次的經驗是：功能涉及多個元件協作時，只有單元測試是不夠的。整合測試才能抓到元件之間的銜接問題。

三、替 try-catch 設計專門的測試

try-catch 在這次經驗裡反覆出現——Bug 1、3、4 被它吞掉，坑 3 的斷言因為它而失效，坑 6 則是根本性的設計問題。

回顧後歸納的三個對策：

• 斷言成功路徑的值：不只檢查「沒拋錯」，要檢查回傳值是 true。坑 3 就是因為只檢查 key 存在，沒檢查值
• 提供完整的依賴：讓 try 區塊能完整執行，而非依賴 catch 來「通過」測試。坑 3 的根因就是缺少收據產生器
• 寫專門的失敗測試：故意製造失敗條件（如模擬印表機拋出 PrinterException），驗證錯誤處理行為符合預期

四、Fake / Mock 的設計原則

1                    Fake（假實作）               Mock（模擬物件）
2─────────────────────────────────────────────────────────
3適用場景          需要跑通完整路徑               只需驗證互動次數/參數
4本案例            FakeReceiptBuilderService      不適用（需要驗證端到端結果）
5                  FakePrinterAdapter

這次 FakePrinterAdapter 的設計漏掉了父類別繼承方法依賴的內部狀態（坑 2），FakeReceiptBuilderService 的回傳資料只覆蓋了部分分支（坑 4）。後來整理出設計 Fake 時的確認項目：

• 繼承/實作的方法中，有哪些是上層呼叫者實際會用到的？
• 這些方法依賴哪些內部狀態（如 late 變數）？
• Fake 的初始化是否正確建立了這些內部狀態？
• Fake 回傳的資料是否足以讓下游所有分支都被觸發？

之後可以改善的地方

寫測試時

• 測試應從入口方法開始驅動，讓中間的邏輯實際執行，避免手動構造中間結果
• 使用模擬子類別時，確認上層實際呼叫到的繼承方法也有被測試覆蓋
• 斷言驗證值本身，而非只驗證存在性（containsKey → 直接檢查值）
• 設計模擬元件的回傳資料時，先確認下游有哪些分支，確認回傳資料能觸發這些分支
• 回傳資料中加入邊界值——空字串、空列表等

修 Bug 時

• 修完後確認有測試會實際走到修改的程式碼，否則測試通過不代表修改生效
• 沿著執行路徑往下看——之前被擋住的程式碼現在可以執行了，那些區段可能存在未發現的問題
• 如果修改讓新的資料流入第三方 library，檢查那些資料是否有 edge case

設計 try-catch 時

• 區分「預期的執行期錯誤」和「程式碼 bug」，只攔截前者
• 定義專用的 exception 類型（如 PrinterException），在 IO 邊界包裝，上層只 catch 這個類型
• 資料準備、邏輯運算等步驟不要放在 try-catch 裡面，讓錯誤直接拋出

自我檢查清單

寫完測試後可以對照的問題：

1. 這個測試有走過真實的呼叫路徑嗎？還是只測了資料搬運？
2. 斷言是驗證「值」還是只驗證「存在」？
3. 所有依賴都有提供嗎？缺少的依賴會不會被 try-catch 吞掉？
4. 模擬子類別覆寫的方法之外，繼承的方法有被測到嗎？
5. 模擬元件回傳的資料有觸發下游的所有分支嗎？
6. 邊界值（空字串、空列表、null）有出現在測試資料中嗎？
7. try-catch 的範圍是否只包含 IO 操作？資料準備和邏輯運算是否在 try 外面？
8. 有寫反向測試（故意觸發錯誤）來確認理解了 Bug 的根因嗎？

本案例的最終測試結構

 128 tests
 2
 3無廚房印表機時的基本行為（4 tests）
 4  └── 基本的 handler 行為，不需要廚房印表機
 5
 6OnlineOrderRecord 模型（7 tests）
 7  └── 單元測試：狀態管理、applyPrintResult
 8
 9FakePrinterAdapter（6 tests）
10  ├── init / sendBytes — 基本功能
11  ├── printText after init — 驗證內部元件初始化（抓 Bug 1）
12  └── printText without init — 反向驗證
13
14KitchenPrinterConfig（2 tests）
15  └── 單元測試：品名匹配邏輯
16
17品項分派邏輯 — 整合測試（4 tests）     ← 全部重寫
18  ├── 2 台空 mapping → odd/even 分配     抓 Bug 2
19  ├── 1 台空 mapping → fallback
20  ├── 明確 mapping 優先匹配
21  └── kitchenItemIds 篩選
22  （全部透過 printAppendedOrder 驅動，有 FakeReceiptBuilderService）
23
24PrintCenter 廚房印表機管理（5 tests）
25  └── 註冊、移除、初始化、向後兼容

最終的修復

1. 語氣：經驗分享，不是教人

不要用「你應該」「要記得」這種由上往下的口氣。這是在記錄自己的經歷，不是在寫教材。

2. 語氣：陳述事實，不帶情緒

避免用強調語氣、反問、或帶有自責/誇張的措辭。平鋪直敘地描述發生了什麼。

3. 用功能描述，不要用函式名稱

文章的讀者不一定看過這份程式碼。如果只寫函式名稱，只有自己看得懂。函式名稱可以出現在程式碼範例裡，但前後的解說要用功能語言。

程式碼區塊裡的函式名稱不需要替換——那是具體的範例，讀者看到程式碼會理解。要替換的是程式碼區塊外的描述文字。

4. 敘事角度：不是每件事都是「犯錯」

有些問題不是自己造成的，不需要用自責的角度來寫。例如第三方 library 的 bug 本來就存在，能觸發它代表前面的工作都做對了。

5. 每個案例要有脈絡：發現 → 找因 → 修復

只說「問題是 X，改成 Y」不夠。讀者需要知道完整的脈絡：是怎麼意識到有問題的、怎麼一步步定位原因的、最後怎麼修的。

修改前

測試名稱是「品項分派邏輯」，但分派邏輯沒有被執行。後來改成從入口方法開始呼叫，Bug 隨即被發現。

修改後

怎麼發現的： 實機上兩台廚房印表機只有一台收到品項，另一台完全沒動。但測試裡的分派測試是通過的。

怎麼找到原因的： 回頭看測試程式碼，發現測試裡的分派結果是手動寫死的，不是由分派邏輯算出來的。測試驗證的是「把結果存進去再讀出來」，但品項分派的程式碼從頭到尾沒有被執行過。

怎麼修的： 改成從入口方法開始呼叫，讓品項分派的邏輯實際跑一遍。跑完之後 Bug 就出現了——分派邏輯的 fallback 條件寫錯，所有品項都被送到同一台。

6. 不要用特定產品/SDK 名稱

具體的產品名稱（如某個 SDK 的名字）讓文章變成只適用於特定情境。著重描述問題的結構，而非特定技術。

例外：第三方 library 的名稱可以出現在「最終修復」等技術細節區段，因為那是給自己未來查閱用的。

檢查清單

寫完經驗分享文章後，對照這些問題：

1. 有沒有「你應該」「要記得」「教訓是」這類由上往下的用語？→ 改成描述自己做了什麼、發現了什麼
2. 有沒有情緒化的措辭（搞砸、偷懶、炸了、根本沒）？→ 改成陳述事實
3. 程式碼區塊外的函式名稱，不看程式碼的人能理解嗎？→ 用功能描述替代
4. 每個案例有完整的脈絡嗎？（怎麼發現 → 怎麼找因 → 怎麼修）
5. 有沒有把不是自己造成的問題寫成自己的錯？→ 用適當的角度描述
6. 有沒有出現特定產品/SDK 名稱？→ 除了技術細節區段外，用功能描述替代

這才建立了 5W1H 自覺決策方法論：在建立任何任務之前，必須強制回答六個問題。不是「可以回答」，而是「必須回答」，任何一個缺失都阻止任務建立。

為什麼直覺判斷不夠用

直覺判斷的門檻太低。任何模糊的想法都可能直接變成任務被付諸實作，等發現重複了或架構位置錯了，才知道白花了時間。

5W1H 框架在任務建立的那一刻設置強制思考關卡。只有通過六個問題，任務才能被建立。

六個問題，六個層次的自覺

Who：責任歸屬，防止重複實作

Who 問的不只是「誰來做」，更重要的是「有沒有人已經做過了」。在我們的協作模式中，Who 必須明確標記執行者和分派者兩個角色，格式如：「parsley-flutter-developer（執行者）由 rosemary-project-manager（分派者）分派」。

這個格式強制一個邊界：主線程不應自己寫程式碼，職責是設計任務、分派任務、驗收結果。如果任務標記為主線程執行但類型是程式碼實作，系統直接阻止。

執行 Who 前要先做四步檢查：搜尋現有 Domain 是否有相同功能，確認既有 Service 是否已實作，查看測試覆蓋是否涵蓋，最後才決定是重用還是新建。Domain 中已有相同功能就禁止新建，責任不明就禁止執行。這兩條規則消滅了大部分重複實作。

What：功能定義，單一職責的守門員

What 要求明確說出具體的輸入輸出、業務行為和異常處理。合格的 What 必須能一句話描述完且無法再拆分。

「書籍處理——包含驗證、儲存、查詢等」不合格。「驗證輸入字串是否符合 ISBN-10 或 ISBN-13 格式，輸入 String isbn，輸出 ValidationResult，空字串拋出 ValidationError」才是。

職責不清就禁止執行，與既有功能重疊就整合，包含多個不相關職責就拆分。

When：觸發時機，副作用要完整識別

When 要求明確說出觸發事件，不是「書籍資料需要驗證的時候」，而是「使用者完成 ISBN 條碼掃描，觸發 ISBNScannedEvent，副作用包含觸發書籍資訊查詢和更新 UI 狀態，整合到 ScanTask 聚合根的事件系統」。

副作用未識別是 When 的紅線。連鎖反應沒有提前想清楚，後來就是難以追蹤的 bug。

Where：架構位置，確保層級正確

Where 決定功能在 Clean Architecture 中的位置。不是「在需要的地方執行」，而是「Domain Layer，BookValidator 位於 Book Aggregate，由 AddBookUseCase 呼叫，呼叫路徑是 UI → UseCase → Domain → Validator」。

位置錯誤就重新定位，不能為了方便就地執行。跨層級混亂就重新架構，不妥協。

Why：動機驗證，識別逃避性開發

Why 是六個問題中最重要的，因為它直接對抗最常見的開發陷阱——逃避。

合格的 Why 必須有需求文件編號，能說明具體的使用者價值和場景。「系統需要更多驗證」不合格，它沒有需求依據，而且可能只是為了逃避更難的問題。

遇到這些語言會立即阻止：「先做簡單的」（逃避複雜問題）、「順便加個功能」（缺乏需求）、「優化一下效能」（可能在迴避功能問題）。

How：實作策略，任務類型的強制標記

How 要求明確實作策略，並強制標記任務類型，格式是 [Task Type: XXX]。六種類型：Implementation（程式碼實作，必須由執行代理人執行）、Dispatch（任務分派，主線程執行）、Review（驗收，主線程執行）、Documentation、Analysis、Planning。

這個標記讓 Who 和 How 的合規性可以被自動檢查：How 標記為 Implementation 但執行者是主線程，系統直接阻止；Dispatch 類型的任務執行者是代理人，同樣阻止。

「先建立基本功能之後再加測試」是直接違規，任何臨時解法都禁止。

Who 和 How 的聯動檢查

正確組合：Implementation 搭配執行代理人，Dispatch/Review 搭配主線程。違規組合：Implementation 搭配主線程（主線程不應寫程式碼），Dispatch 搭配代理人，缺少執行者/分派者標記。

這個機制解決了一個真實痛點：主線程在時間壓力下直接修改程式碼，繞過代理人執行的設計。有了 How 的任務類型標記和 Who 的格式要求，這種行為在任務建立階段就被攔截。

逃避語言清單

框架持續更新一份逃避語言清單，分五類：

• 品質妥協：「太複雜」「先將就」「暫時性修正」「症狀緩解」、“workaround”、“hack”、“quick fix”
• 簡化妥協：「更簡單的方法」「簡化處理」——通常意味著在迴避真正的設計問題
• 擱置問題：「架構問題先不管」「技術債務之後處理」——發現了卻不解決，最危險
• 測試妥協：「簡化測試」「基本測試即可」
• 模糊詞彙：沒有具體指標的「優化」「自動」

偵測到任何逃避語言，系統立即阻止並要求修正。

Hook 系統：讓規則有牙齒

框架的執行依賴 Hook 系統。TodoWrite 工具使用前，Hook 檢查 5W1H 完整性；任何一個 W 或 H 缺失，操作立即阻止；發現逃避語言，進入修復模式。

修復機制：阻止操作 → 明確說明缺失哪個項目 → 要求補充 → 再次驗證。

這個框架改變了什麼

最明顯的感受是對話品質變了。以前任務可能只有「實作書籍驗證功能」；現在必須帶著完整的 Who（誰來做、是否已存在）、What（具體輸入輸出）、When（何時觸發、有哪些副作用）、Where（架構層）、Why（需求來源）、How（任務類型和策略）才能被建立。

很多模糊的想法在回答六個問題的過程中就自然消失了——它們根本過不了關。

這不是測試該有的樣子。問題根源在於測試耦合了實作細節，而非行為。

BDD 的核心定位

BDD 是 TDD 的演進，它要求測試描述系統的「行為」而非「實作」。

行為是使用者視角觀察到的系統反應；實作是程式內部的技術細節。這個區別看起來簡單，實際撰寫測試時卻很容易模糊。

BDD 解決三個問題：

測試維護成本高。傳統單元測試緊密耦合實作細節，重構時即使行為沒變，測試仍需大量修改。BDD 讓重構時測試保持穩定。

需求追溯困難。測試充滿技術細節，無法對應業務需求。Given-When-Then 場景即是需求文件，測試即規格。

溝通成本高。開發、測試和業務人員用不同語言描述系統行為。BDD 統一使用業務語言，建立共通溝通基礎。

我們的分工是：Clean Architecture 定義架構分層，TDD 四階段流程定義開發節奏，BDD 定義測試內容和撰寫規範。

Given-When-Then 結構

Given 描述系統的初始狀態，必須明確完整，只包含與此場景相關的資料。常見錯誤是前置條件模糊，或包含大量無關測試資料。

When 描述使用者執行的操作，必須是單一動作，使用業務語言。「呼叫 Repository 的 save 方法」是技術術語；「使用者提交訂單」是業務語言。一個 When 不能包含多個動作。

Then 描述執行後的狀態變化或結果，必須是可觀察的行為。「Repository 的 save 方法被呼叫一次」是實作細節；「訂單成功儲存並回傳訂單編號」是可觀察的行為。

判斷行為還是實作的方法很簡單：使用者能否觀察到？改變實作會影響這個結果嗎？產品經理需要關心嗎？都是「能觀察、不影響、需要關心」就是行為，反之是實作細節。

行為測試和實作測試的差異

測試實作：

1test('OrderRepository.save should call database.insert', () {
2  repository.save(order);
3  verify(database.insert('orders', order.toJson()));
4});

這個測試關注「如何儲存」，替換資料庫或重構儲存邏輯就會失敗。

測試行為：

 1test('使用者提交訂單 - 訂單成功儲存', () async {
 2  // Given: 使用者已選擇商品並填寫完整資訊
 3  final order = validOrder;
 4
 5  // When: 使用者提交訂單
 6  final result = await submitOrderUseCase.execute(order);
 7
 8  // Then: 系統確認訂單已儲存
 9  expect(result.isSuccess, true);
10  expect(result.orderId, isNotEmpty);
11});

這個測試關注「訂單是否成功儲存」，重構儲存機制不會影響結果。

測試描述的視角同樣重要。從技術元件角度：

1test('當 Repository 回傳 null 時 UseCase 拋出例外', () { ... });

從使用者視角：

1test('使用者提交訂單失敗 - 商品庫存不足', () {
2  // Given: 商品庫存為 0
3  // When: 使用者嘗試提交訂單
4  // Then: 系統回應「庫存不足」錯誤
5});

分層測試策略

BDD 不適用所有架構層級，每層特性不同，測試策略也不同。

UseCase 層是 BDD 的核心應用層，代表完整的使用者操作流程，必須使用 Given-When-Then 結構，涵蓋所有業務場景。

Domain 層包含核心業務規則、值物件驗證和實體不變量，需要細緻的邊界條件測試，單元測試更適合。

Behavior 層負責 ViewModel 轉換和事件處理，只有複雜轉換邏輯需要獨立測試，簡單轉換由 UseCase 層覆蓋即可。

UI 層測試成本高，只測試關鍵互動路徑，使用整合測試。

Interface 層只定義契約，沒有實作邏輯，不需要測試。

Mock 策略

核心原則：只 Mock 外層依賴，不 Mock 內層邏輯。

外層依賴（Repository、Service、Event Publisher）透過 Interface 進行 Mock，隔離外部系統。內層邏輯（Domain Entity、Value Object）必須使用真實物件，確保測試涵蓋真實業務邏輯。

正確寫法：

 1test('使用者提交訂單成功', () async {
 2  // Mock Repository（外層依賴）
 3  final mockRepository = MockOrderRepository();
 4  when(mockRepository.save(any))
 5      .thenAnswer((_) async => SaveResult.success('order-123'));
 6
 7  // 使用真實的 Domain Entity（內層邏輯）
 8  final order = Order(
 9    amount: OrderAmount(100),
10    userId: UserId('user-001'),
11  );
12
13  final useCase = SubmitOrderUseCase(repository: mockRepository);
14  final result = await useCase.execute(order);
15
16  expect(result.isSuccess, true);
17  expect(result.orderId, 'order-123');
18});

錯誤寫法是 Mock Domain Entity：

1test('使用者提交訂單成功', () {
2  final mockOrder = MockOrder();
3  when(mockOrder.validate()).thenReturn(true);
4  // 沒有測試到任何真實業務邏輯
5});

與 TDD 階段整合

階段一（功能設計）：從需求識別使用者行為場景。「使用者可以提交訂單」需要提取多個場景：成功提交、庫存不足失敗、金額無效失敗等，每個場景涵蓋正常流程、異常流程和邊界條件。

階段二（測試設計）：將行為場景轉換為可執行的測試程式碼，先建立結構，設置 Mock，再依 Given-When-Then 填入邏輯。

階段三（實作策略）：測試先行。先完成所有測試場景並確認失敗（Red），才開始實作 UseCase 讓測試通過（Green）。

階段四（重構優化）：重構時，行為測試必須保持穩定。重構導致測試需要修改，代表測試耦合了實作。

判斷重構品質的標準很清楚：替換 Repository 實作、改變演算法，不應讓測試失敗；改變業務規則、調整可觀察的錯誤訊息，才應讓測試失敗。

常見挑戰

測試覆蓋率盲點

BDD 強調測試「重要行為」，可能讓某些程式碼未被覆蓋。混合策略解決這個問題：UseCase 層 100% BDD 測試，Domain 層複雜邏輯 100% 單元測試，整體維持 80% 程式碼覆蓋率目標。

學習曲線

從「測試實作」轉向「測試行為」需要思維轉換，初期容易寫出「假行為測試」（實際上還是在測試實作）。建立範例庫和測試模板很有幫助：

 1test('[業務場景描述] - 成功', () async {
 2  // Given: [前置條件]
 3  final input = [準備測試資料];
 4  [設置 Mock 行為];
 5
 6  // When: [觸發動作]
 7  final result = await useCase.execute(input);
 8
 9  // Then: [預期結果]
10  expect(result.isSuccess, true);
11  expect([驗證業務結果]);
12});

邊界條件容易被忽略

業務場景描述容易遺漏技術性的邊界條件（null、異常、極端值）。每個 UseCase 最少需要：一個正常流程、兩個異常流程、三個邊界條件。建立技術性測試檢查清單並在 Code Review 重點確認。

測試設置複雜度

UseCase 層的 BDD 測試需要 Mock 多個依賴，建立 Test Helper 和 Builder Pattern 減少重複：

 1class UseCaseTestHelper {
 2  static MockOrderRepository createMockRepository({
 3    required SaveResult saveResult,
 4  }) {
 5    final mock = MockOrderRepository();
 6    when(mock.save(any)).thenAnswer((_) async => saveResult);
 7    return mock;
 8  }
 9}
10
11class OrderBuilder {
12  int _amount = 100;
13  String _userId = 'user-001';
14
15  OrderBuilder withAmount(int amount) {
16    _amount = amount;
17    return this;
18  }
19
20  Order build() => Order(
21    amount: OrderAmount(_amount),
22    userId: UserId(_userId),
23  );
24}

行為粒度

粒度太粗，失敗時難以定位；太細則接近單元測試，失去 BDD 優勢。採用「一個 UseCase 等於一個核心行為」的原則：UseCase 代表完整業務流程，名稱以動詞開頭（Submit, Cancel, Query），所有測試場景屬於同一個業務流程。

業務需求變更

需求變更時測試場景仍需更新。集中管理業務規則常數減少影響範圍：

1class OrderBusinessRules {
2  static const int freeShippingThreshold = 1000;
3  static const int maxOrderAmount = 100000;
4  static const int minOrderAmount = 1;
5}

完整範例

以「使用者提交訂單」為例：

  1group('SubmitOrderUseCase', () {
  2  late MockOrderRepository mockRepository;
  3  late MockInventoryService mockInventoryService;
  4  late MockEventPublisher mockEventPublisher;
  5  late SubmitOrderUseCase useCase;
  6
  7  setUp(() {
  8    mockRepository = MockOrderRepository();
  9    mockInventoryService = MockInventoryService();
 10    mockEventPublisher = MockEventPublisher();
 11    useCase = SubmitOrderUseCase(
 12      repository: mockRepository,
 13      inventoryService: mockInventoryService,
 14      eventPublisher: mockEventPublisher,
 15    );
 16  });
 17
 18  group('正常流程', () {
 19    test('使用者提交訂單成功', () async {
 20      // Given: 使用者已選擇商品且填寫完整資訊
 21      final order = Order(
 22        amount: OrderAmount(100),
 23        userId: UserId('user-001'),
 24        items: [OrderItem(productId: 'prod-001', quantity: 2)],
 25        shippingAddress: Address(city: '台北市', district: '信義區'),
 26      );
 27      when(mockInventoryService.checkStock('prod-001'))
 28          .thenAnswer((_) async => StockStatus.available);
 29      when(mockRepository.save(any))
 30          .thenAnswer((_) async => SaveResult.success('order-123'));
 31
 32      // When: 使用者點擊「提交訂單」
 33      final result = await useCase.execute(order);
 34
 35      // Then: 系統確認訂單已儲存並回傳訂單編號
 36      expect(result.isSuccess, true);
 37      expect(result.orderId, 'order-123');
 38      verify(mockEventPublisher.publish(any.having(
 39        (e) => e.type, 'event type', EventType.orderCreated,
 40      ))).called(1);
 41    });
 42  });
 43
 44  group('異常流程', () {
 45    test('使用者提交訂單失敗 - 商品庫存不足', () async {
 46      // Given: 選擇的商品庫存為 0
 47      final order = Order(
 48        amount: OrderAmount(100),
 49        userId: UserId('user-001'),
 50        items: [OrderItem(productId: 'prod-001', quantity: 2)],
 51      );
 52      when(mockInventoryService.checkStock('prod-001'))
 53          .thenAnswer((_) async => StockStatus.outOfStock);
 54
 55      // When: 使用者點擊「提交訂單」
 56      final result = await useCase.execute(order);
 57
 58      // Then: 系統回應庫存不足錯誤，不儲存訂單
 59      expect(result.isSuccess, false);
 60      expect(result.error, ErrorType.outOfStock);
 61      verifyNever(mockRepository.save(any));
 62    });
 63
 64    test('使用者提交訂單失敗 - Repository 儲存失敗', () async {
 65      // Given: Repository 無法儲存（網路錯誤）
 66      final order = Order(
 67        amount: OrderAmount(100),
 68        userId: UserId('user-001'),
 69        items: [OrderItem(productId: 'prod-001', quantity: 1)],
 70      );
 71      when(mockInventoryService.checkStock(any))
 72          .thenAnswer((_) async => StockStatus.available);
 73      when(mockRepository.save(any))
 74          .thenAnswer((_) async => SaveResult.failure('網路連線失敗'));
 75
 76      // When: 使用者點擊「提交訂單」
 77      final result = await useCase.execute(order);
 78
 79      // Then: 系統回應訂單提交失敗
 80      expect(result.isSuccess, false);
 81      expect(result.error, ErrorType.saveFailed);
 82    });
 83  });
 84
 85  group('邊界條件', () {
 86    test('使用者提交訂單失敗 - 訂單金額為 0', () async {
 87      final order = Order(
 88        amount: OrderAmount(0),
 89        userId: UserId('user-001'),
 90        items: [],
 91      );
 92      final result = await useCase.execute(order);
 93      expect(result.isSuccess, false);
 94      expect(result.error, ErrorType.invalidAmount);
 95    });
 96
 97    test('建立負數金額訂單拋出例外', () {
 98      expect(
 99        () => Order(amount: OrderAmount(-100), userId: UserId('user-001')),
100        throwsA(isA<InvalidAmountException>()),
101      );
102    });
103
104    test('使用者提交訂單失敗 - 訂單金額超過上限', () async {
105      final order = Order(
106        amount: OrderAmount(1000001),
107        userId: UserId('user-001'),
108        items: [OrderItem(productId: 'prod-001', quantity: 10000)],
109      );
110      final result = await useCase.execute(order);
111      expect(result.isSuccess, false);
112      expect(result.error, ErrorType.amountExceedsLimit);
113    });
114  });
115});

結論

回頭看最初那個重構週期，二十幾個因為替換 Repository 實作而失敗的測試，問題很清楚：測試在監視實作細節，而不是守護業務行為。

切換到 BDD 之後，同樣的重構只需確認業務行為沒有改變，測試套件就能保持穩定。

但 BDD 不是萬靈丹。它需要思維轉換，需要建立明確規範，需要持續 Code Review 維持品質。混合策略（UseCase 層 BDD、Domain 層單元測試、UI 層整合測試）才能真正發揮效果。

我們選擇了 Clean Architecture。它不只是架構模式，更是一套「責任分層」語言，讓我們和 AI 代理人都能用同一套詞彙討論誰該負責哪個部分、什麼時候可以動手。

核心原則：依賴只能由外向內

Clean Architecture 最核心的一句話是「依賴只能由外向內」。內層不知道外層的存在，外層依賴內層定義的介面。業務邏輯因此得以獨立，換資料庫、換 UI 框架都不需要動到核心規則。

架構由內到外分為四層：

Entities（核心業務規則） 封裝核心業務概念，例如書籍、訂單、使用者。定義實體屬性和業務不變量的驗證，不依賴任何框架或資料庫。

Use Cases（應用業務邏輯） 協調 Entities 之間的互動，定義系統功能。同時定義 Input Port、Output Port、Repository Port，只依賴 Entities 和這些自己定義的介面。

Interface Adapters（介面轉接層） 橋接業務邏輯和外部技術。Controller 接收外部請求並轉換為 Use Case 輸入，Presenter 格式化 Use Case 輸出，Repository 實作在這一層開始成形。

Frameworks & Drivers（框架與外部系統） 包含所有技術細節——資料庫、UI 框架、第三方服務。可以隨時替換，完全不影響內層。

依賴反轉原則（DIP）讓這一切成立

Use Case 需要存取資料，但不能直接依賴 SQLite。正確做法是：在 Use Cases 層定義 Repository Port（抽象介面），Use Case 只依賴這個介面。真正的資料庫實作在最外層，它去實作這個介面。

依賴方向因此被反轉：資料庫實作依賴 Use Case 定義的介面，而非 Use Case 依賴資料庫。最後在 Composition Root 把具體實作注入進去，這就是依賴注入的本質。

設計從內到外，實作從外到內

這是我們在 AI 協作中最重要的一個認知。

設計階段由內到外

1. 設計 Entities：識別業務實體、定義 Value Objects（ISBN、Title 這類有驗證規則的值物件），在建構子中驗證業務不變量。
2. 設計 Use Cases：定義 Input Port、Output Port、Repository Port。確定業務邏輯需要什麼，但不決定如何實作。
3. 設計 Interface Adapters：Controller 如何轉換外部請求、Presenter 如何格式化輸出。
4. 設計 Frameworks：選擇資料庫方案，實作 Repository。到這步才碰具體技術。

實作階段由外到內

1. 先定義所有 Ports。在寫任何實作之前，確立 Use Case 介面和 Repository 介面，這是系統的骨架。
2. 外層用 Mock 介面開發和測試。Controller 在 Use Case 還沒真正實作前就能測試，因為它依賴的是抽象介面。
3. 補完內層實作：Interactor 實作業務邏輯，Repository 存取真正的資料庫。
4. Composition Root 組裝依賴注入，系統就能真正執行。

設計階段確保業務邏輯不被技術細節污染，實作階段讓每一層都能獨立開發和測試。

驗證架構是否正確

每個 Phase 完成後，我們對照以下幾個方向確認。

依賴方向

• Entities 沒有任何外層的 import
• Use Cases 只 import Entities 和自己定義的介面
• Frameworks 層實作的是 Interface Adapters 定義的介面

介面契約

• Repository Port 定義在 Use Cases 層（不是 Frameworks 層）
• Repository 回傳的是 Entity 而不是資料庫 DTO
• Input/Output Port 沒有洩漏框架的型別（例如 HTTP Request、SQLite Row）

業務邏輯位置

• 業務不變量的驗證在 Entity 建構子
• 應用層邏輯在 Use Case Interactor
• Controller 只負責轉換和呼叫，不包含業務判斷

Interface-Driven Development

• 所有 Ports 在設計階段就定義完成
• 外層真的用 Mock 介面在開發測試
• 組裝注入在 Composition Root 統一處理

為什麼這對 AI 協作特別有價值

傳統開發中，架構邊界的維護依賴工程師的經驗，容易在壓力下妥協。AI 代理人則非常適合執行有明確規則的框架——規則夠清楚，它就能持續一致地遵守。

分層邊界就是這樣的規則。告訴代理人「這個 class 屬於 Use Cases 層，所以不能 import 任何 Framework 層的東西」，代理人就能機械性地驗證和維護這個邊界。

這套語言也讓任務拆分有了清楚的依據。「這個功能需要修改 Entity 和 Use Case，但不涉及 Repository 實作」是一個清楚的任務描述，對應到具體的修改範圍，不會模糊。

從實際經驗來看，引入 Clean Architecture 之後，AI 的實作結果更容易預測，測試覆蓋率更容易維持，架構審查也更有效率。代價是設計階段需要更多前置思考，但這個投資通常值得。

我們在專案中建立了一套設計階段品質閘門：在 Ticket 進入 Phase 2 之前強制執行 C1/C2/C3 三項檢測。 問題在文字階段就抓出來，修正只需幾分鐘；等到程式碼都寫好了，才是幾個小時起跳的代價。

三層檢測標準

C1 God Ticket：超過 10 個檔案、跨越超過 2 個架構層、或預估超過 16 小時，判定過大，必須拆分。

C2 Incomplete Ticket：驗收條件少於 3 個可量化項目、缺少測試規劃、未定義工作日誌名稱、無參考文件連結——任一缺失，Ticket 不完整。

C3 Ambiguous Responsibility：標題缺少層級標示（如 [Layer 5]）、目標含複合職責（出現「和」或「或」）、步驟用「相關檔案」而非具體路徑、驗收條件跨層——任一模糊，需重新定義。

檢測順序的設計邏輯

固定執行順序：C1 → C3 → C2。

C1 最先，因為一旦判定 God Ticket，拆分後產生多個新 Ticket，C2/C3 的分析全部作廢要重來。C3 排第二，職責不清的 Ticket，補充驗收條件也會是模糊的。C2 最後，在範圍合理、職責明確的基礎上，確認必要元素齊全。

執行流程

Step 1：C1 God Ticket 檢測

從 Ticket 的步驟章節提取所有檔案路徑，計算檔案數量。接著使用檔案路徑分析法判斷每個檔案所屬的架構層：

• lib/presentation/widgets/、lib/presentation/pages/ 屬於 Layer 1（UI 層）
• lib/presentation/controllers/、lib/presentation/view_models/ 屬於 Layer 2（行為層）
• lib/application/use_cases/、lib/application/services/ 屬於 Layer 3（UseCase 層）
• lib/domain/repositories/（介面）、lib/domain/events/ 屬於 Layer 4（Domain 介面層）
• lib/domain/entities/、lib/domain/value_objects/、lib/infrastructure/ 屬於 Layer 5（Domain 實作層）

層級跨度 = 最高層 - 最低層。如果有檔案分佈在 Layer 1 到 Layer 5，層級跨度就是 4，遠超過 2 的上限。

預估工時根據步驟數量與複雜度係數評估：步驟數 × 平均每步時間 × 複雜度係數（1.0 到 2.0）。

檢測失敗時，依序嘗試三種拆分策略：

1. 按層級拆分（優先）：將跨層的 Ticket 按架構層拆成多個
2. 按職責拆分（次要）：將工時過長的 Ticket 按職責邊界拆分
3. 按功能模組拆分（最終）：將職責過多的 Ticket 按功能模組拆分

拆分後的每個子 Ticket 都需要重新執行 C1 檢測。

Step 2：C3 Ambiguous Responsibility 檢測

確認四個要素：

• 層級標示：標題包含 [Layer X] 標籤
• 職責描述：目標章節無「和」或「或」的複合描述
• 檔案範圍：步驟列出具體路徑，而非「相關檔案」
• 驗收限定：驗收條件不出現跨層項目

任一不符，依序修正：明確層級 → 重寫職責 → 列出具體檔案 → 限定驗收範圍。

Step 3：C2 Incomplete Ticket 檢測

確認四個必要元素都存在：

• 驗收條件：3 個以上可量化、可驗證的項目（「程式碼品質提升」這種描述不算）
• 測試規劃：明確的測試檔案路徑和對應的測試項目
• 工作日誌：定義好工作日誌的檔案名稱（而非「待填寫」）
• 參考文件：至少 1 個有效的文件連結

缺少哪個就補哪個，沒有例外。

Step 4：提交審查

所有 Ticket 通過 C1/C2/C3 之後，生成品質閘門檢測報告，提交 PM 審查。PM 批准後才能進入 Phase 2。

阻斷機制與執行時機

任何 Ticket 未通過 C1/C2/C3，禁止進入 Phase 2。不是建議，是硬性規定。問題立即修正，所有過程寫入工作日誌。

執行時機有三個：設計完成後立即檢測、PM 分派前確認報告、PM 審查時以報告作依據。三個時機缺一不可——缺了任何一個，閘門就會有漏網之魚。

實際效益

最直接的改變是：開發者接到 Ticket 時就已經有明確範圍、清楚職責、具體驗收標準，不需要反覆確認。

更重要的是，因為修正成本真的很低，團隊才會認真對待每一次品質閘門，而不是當作走形式。一旦修正成本高，就會開始討價還價、局部修正、累積技術債——品質閘門也就形同虛設。

這讓我們認真思考：Ticket 不只是一張便利貼，它是任務的完整生命週期。

四個狀態，一條主線

待執行（Pending）：Ticket 準備好但還沒人開始。進入條件是標題格式正確、五個核心欄位填寫完整、前置依賴都已完成。

進行中（In Progress）：核心紀律是即時記錄，遇到問題就寫進日誌，不要等到最後才回憶。我們設的建議上限是 8 小時——超過通常代表 Ticket 太大，需要拆分。

Review 中（In Review）：第三方驗證。重點聚焦在驗收條件：逐項打勾，要麼通過要麼不通過。建議 1-2 小時內完成，避免卡住流程。

已完成（Completed）：不可逆的終態。進入條件：所有驗收條件打勾、Review 通過、測試 100% 通過、靜態分析 0 錯誤、工作日誌更新。缺一不可。

Ticket 標題：動詞加目標

標準格式是「動詞 + 目標」。動詞選擇反映任務類型：「定義」用於介面或規範，「撰寫」用於測試文件，「實作」用於具體功能，「修復」用於 Bug，「重構」用於改善結構。

對比：「做 Repository」和「實作 SQLiteBookRepository」——後者讓人在領取前就知道工作規模。

五個核心欄位

每張 Ticket 必須有這五個欄位：

背景說明為什麼需要這個任務，讓三個月後的自己也能理解來龍去脈，不用去問當初的人。

目標一句話說清楚要達成什麼，建議不超過 30 字。可驗證的目標：「實作 SQLiteBookRepository，符合 IBookRepository 介面，通過所有單元測試」。不可驗證的：「優化資料儲存」。

步驟列 3-5 個具體動作，每個指明操作對象和預期結果。目的是讓人一領取就知道從哪裡開始。

驗收條件是任務的契約，必須客觀可勾選。不是「程式碼品質良好」，而是「dart analyze 0 錯誤」；不是「測試通過」，而是「覆蓋率 100%，通過率 100%」。

參考文件連結設計文件、需求規格、相關 Ticket，讓執行者有完整上下文。

執行的七個步驟

領取前先確認依賴都完成，工作量合理再標記進行中。

閱讀背景和目標，把參考文件看完再動手。

執行時遇到問題即時記進日誌。

自檢時逐項勾選驗收條件，全過才進下一步。

提交時標記為 Review，附上自我檢查結果。

處理 Review 結果，通過則關閉，未通過根據反饋修正再提交。

記錄經驗——這一步最容易省略，也最有長期價值。Ticket 完成時回答：學到了什麼？有什麼可改進的地方？是否需要建立 error-pattern 防止重複？知識沉澱進系統，才不會只留在某個人腦子裡。

阻塞狀態的積極處理

Blocked 最容易被誤用：標記了就等著。我們的原則是阻塞不超過 24 小時，必須採取行動。

行動方式取決於原因：缺前置條件就派發前置任務；技術問題不清楚就建調查任務；需要決策就建評估任務。把「被動等待」轉成「積極解除」，每個阻塞都變成一個有人負責的子任務。

結語

從「修復那個問題」到「修復書籍搜尋在 ISBN 格式不一致時回傳空結果的問題」，這個距離比看起來近。只需要一點紀律，和對「完成」這件事更認真的態度。

我們的解法是建立一套 Ticket 設計派工方法論。這篇文章記錄實踐方式和核心概念，以及後來加入的積極派發原則。

為什麼需要 Ticket？

工作日誌已經記錄了一切，為什麼還需要 Ticket？

兩者定位不同。工作日誌是「記錄層」，給未來的開發者看，記錄決策脈絡。Ticket 是「執行層」，給正在做事的人看，代表一個可以獨立完成、驗收、追蹤的最小任務單位。

一個 Ticket 有幾個核心特徵：獨立性（可以獨立執行和驗收）、原子性（不可再分割）、可驗證性（有明確的完成標準），以及單一職責（一個動詞加上一個目標）。

單一職責是拆分 Ticket 的唯一標準

方法論早期我們用量化指標判斷是否需要拆分：職責數量、檔案數量、測試案例數、行數。直觀，但實際用起來有問題：一個 100 行的 Ticket 可能職責非常清楚，完全不需要拆；一個 30 行的如果混了兩個不相關的目標，就應該拆。數字不能反映語義。

後來改為四個語義檢查：

語義檢查：能用「動詞加單一目標」描述嗎？描述時出現「並且」或「以及」，通常需要拆。

修改原因檢查：只有一個原因會觸發修改嗎？兩個不同的業務規則各自可能觸發修改，就是兩個 Ticket。

驗收一致性：所有驗收條件都指向同一個目標嗎？

依賴獨立性：拆分後不會產生循環依賴嗎？

這四個問題比任何量化指標都更接近本質。

驗收條件的標準也要說清楚：「功能正常」不夠，「所有單元測試通過且 dart analyze 輸出 0 個問題」才算。

Ticket 與 Clean Architecture 的對應

我們的專案用 Clean Architecture，Ticket 設計也遵循同樣的分層邏輯。

Interface 定義優先於具體實作。每個功能模組先建 Interface 定義的 Ticket，再建具體實作的 Ticket。這樣外層可以依賴 Interface 先行開發，不被內層實作進度卡住。

分層拆分讓每個 Ticket 待在自己的架構層，Domain、Application、Infrastructure、Presentation 層的 Ticket 不互相混合，也更容易並行執行。

即時 Review：在問題發生當下就解決

傳統 code review 在整個版本完成後進行，此時修正成本很高，問題可能已經影響了許多後續實作。

我們改為每個 Ticket 完成時立即觸發 Review。因為範圍只有單一 Ticket 的相關程式碼，Review 者不需要理解整個版本的脈絡，反饋在數小時內完成，修正成本極低。

Review 涵蓋四個面向：功能正確性（功能實現、驗收條件、邊界情況、錯誤處理）、架構合規性（Clean Architecture、依賴方向、Interface-Driven、架構債務）、測試通過率（單元測試、整合測試、覆蓋率、跳過測試）、文件同步性（Ticket 日誌、設計決策、API 文件、README），共 16 項。

三層文件結構：讓 6000 行問題消失

解決臃腫工作日誌的方式是拆層：

• 主版本日誌：500–1000 行，說明版本目標，提供所有 Ticket 的索引
• Ticket 工作日誌：每個 Ticket 一份，100–200 行，記錄執行過程、Review 結果和完成標記
• 設計決策日誌：300–500 行，記錄設計決策演進，包含廢棄決策的原因

原本 6000 行的文件拆分後變成一份 800 行主日誌加上 12 個 Ticket 日誌加上一份 400 行設計決策日誌，總量降到約 2000 行，資訊查找時間減少大約 80%。

積極派發：發現問題就建 Ticket

這是後來加入的原則，也是這套方法論最核心的轉變。

執行一個 Ticket 時，經常會發現超出原本範圍的情況。以前的做法是「繼續在這個 Ticket 裡處理」或「先記著等有空再說」。前者讓 Ticket 失去單一職責，後者讓問題消失在記憶裡。

積極派發的做法：只要發現超出範圍的新情況，立刻評估性質，建立對應的新 Ticket。阻塞了當前 Ticket 就建子 Ticket 標記依賴；獨立於當前 Ticket 就建新 Ticket 讓兩者並行；是未來的改進就建技術債務 Ticket 記錄起來。

好處是：每個決策都有獨立記錄，保持可追溯性；任務粒度更細，更容易估算；學習點不會淹沒在大 Ticket 裡；一次只專注一件事。

要注意的反模式是「為派發而派發」。積極派發不是讓每件事都變成獨立 Ticket，判斷標準始終是單一職責：情況是否真的超出原 Ticket 範圍？

這套方法論從單一大文件演進到精簡主文加引用網絡，量化指標被單一職責取代，是因為語義比數字更能反映 Ticket 是否設計得好。積極派發的加入，是因為 Ticket 可以成為持續改善的工具，不只是任務追蹤。

如果你的工作日誌越來越長、協作衝突越來越多，從三個問題開始：Ticket 能用「動詞加單一目標」描述嗎？驗收條件是客觀可檢查的嗎？跟其他 Ticket 的依賴關係清楚嗎？

我們花了很長時間，把方法論文件寫得越來越完整——完整的定義、詳細的範例、細緻的流程說明，直到有一天發現，這樣的文件根本沒有人在用。

問題出在誤解了方法論的讀者是誰。

方法論的讀者是專家。他們已經知道這些內容，只是需要時忘記了細節。他們不需要被教導，只需要一個快速的提醒，幫他們找回記憶。

30 秒電梯理論

我們現在用一個簡單標準評估方法論：能在 30 秒內讀完嗎？如果不能，就太長了。

讀者打開方法論通常是在任務中途，需要確認某個原則或步驟。超出 30 秒的內容搬移到獨立的 SKILL 文件，由方法論引用。

方法論與 SKILL 的分工

方法論是複習清單：告訴你「有哪些原則」「判斷方向是什麼」，讓你快速確認沒有遺漏重要考量。

SKILL 是實作指南：包含範例、錯誤處理、邊界情況，回答「具體怎麼做」。

過去把兩者混在一起，結果兩頭不討好——方法論太長難以快速查閱，又因試圖簡潔而省略了真正需要的操作細節。

撰寫方法論的核查

每次撰寫或改寫方法論，問三個問題：

有完整的操作流程嗎？建立對應 SKILL，方法論只保留原則和引用。

有程式碼範例或錯誤處理細節嗎？屬於 SKILL，不屬於方法論。

精簡後會流失關鍵資訊嗎？如果是，那些資訊本來就不屬於方法論。

消除歧義仍然是核心要求

精簡不代表模糊。「應該」改為「必須」，「建議」改為「要求」，「適當時機」改為具體時間點。每個判斷只有兩種結果：接受或拒絕、必須或禁止。

簡短但模糊的方法論比詳細但模糊的更糟糕——它讓讀者覺得已經複習完了，卻什麼都沒想清楚。

結果就是：Review 的時候發現第一個 Ticket 的架構方向有問題，接下來五個都是建在那個錯誤上面。這時候修正成本已經是即時發現的六到十倍，開發者剛花了三天卻要整個打掉，士氣很難不崩。

後來我們設計了「即時 Review 機制」，核心就一句話：Ticket 完成就 Review，不累積。

三個原則

即時觸發。Ticket 完成的當下就觸發，不是等 Wave 結束，不是等今天收工。錯誤的架構決策會在下一個 Ticket 開始前就污染後續設計，等不起。

30 分鐘完成。這個時間限制是設計訊號：如果一個 Ticket 的 Review 超過一小時，代表那個 Ticket 太大，應該在規劃時就拆。

標準清單。16 項固定檢查項，分功能正確性、架構合規性、測試通過率、文件同步性四類。不管誰 Review、什麼時間點，標準都一樣。

怎麼跑

觸發：完成實作、驗收條件全滿足、測試 100% 通過、靜態分析零錯誤，狀態標為「Review 中」。

執行：30 分鐘內跑完 16 項。功能正確性（10 分鐘）、架構合規性（8 分鐘）、測試通過率（5 分鐘）、文件同步性（2 分鐘），最後 5 分鐘記錄結果。

偏差糾正：發現問題就照固定流程走——暫停、記錄根因、建修正 Ticket、執行、再 Review。流程結構化是關鍵，「發現問題不知怎麼辦」是問題被忽略的主因。

問題分三級

P0（阻塞）：功能錯誤、架構偏差、測試失敗。必須在 Review 通過前修正。

P1（重要）：邊界處理缺失、文件不完整。建 Ticket 追蹤，當前 Ticket 可先通過。

P2（建議）：命名改善、程式風格。記錄即可。

分級的目的：Review 保持快速，重要問題不被跳過。

超時是訊號

Ticket 完成後 2 小時內開始 Review，目標 30 分鐘，最長 1 小時。超時代表 Ticket 範圍太大，不是 Reviewer 的問題。這個標準幫助我們持續校正 Ticket 的粒度。

最明顯的變化

導入前，「Review」這件事是模糊的——知道應該做，但時機不固定、標準不一、出了問題也不清楚怎麼處理。

導入後，偏差被控制在單一 Ticket 的範圍內，沒機會擴散。另一個意外收穫是，16 項清單讓我們對「品質」有了共同語言，Review 結果可以比較、可以追蹤，不再靠個人感覺。

即時 Review 的目的是把修正成本壓到最低。問題在最小範圍被抓到，代價才會真的小。

認知負擔：一切的出發點

人類工作記憶有限，大約一次只能處理七個項目（Miller’s Law）。看到縮寫要在腦中展開、看到模糊詞要猜測含義、看到長函式要分段記憶——這些都是認知負擔。

自然語言化的目標很簡單：讓程式碼像讀文章一樣自然，把讀者的認知資源留給理解業務邏輯，而不是解碼程式碼本身。

第一原則：命名要能直接讀懂

函式命名

1// 錯誤：不知道在做什麼
2void process(data) {}
3void handle(item) {}
4
5// 正確：一眼看懂
6void calculateBookReadingProgress(Book book) {}
7void validateUserRegistrationData(User user) {}
8void enrichBookMetadataFromExternalSource(Book book) {}

變數命名

1// 錯誤：縮寫和多用途
2var usr = getCurrentUser();
3var data = loadUserData();
4data = processBookData(); // 100行後同一變數換了意思
5
6// 正確：明確且專用
7final authenticatedUser = getCurrentUser();
8final userProfileData = loadUserData();
9final enrichedBookMetadata = processBookData();

類別命名

1// 錯誤：說不清在做什麼
2class Manager {}
3class Handler {}
4class BookDAO {}
5
6// 正確：業務職責一目了然
7class BookMetadataEnrichmentService {}
8class UserRegistrationValidator {}
9class LibraryBookSearchEngine {}

布林命名

布林變數應該能讀成問句，在 if 裡就能自然被理解：

1bool isValid;      // "Is valid?"
2bool hasPermission; // "Has permission?"
3bool canEdit;       // "Can edit?"
4
5// 不好：語意不清
6bool permission;

常見命名反模式

• 匈牙利命名法：strName, intCount — 型別系統自己會提供型別資訊，名稱不用重複
• 無意義前綴：theUser, aBook — 沒帶來任何資訊，直接刪掉
• 過度縮寫：usrMgr — 迫使讀者展開，userManager 更自然
• 數字後綴：user1, user2 — 改成 primaryUser, secondaryUser 才說明關係

第二原則：函式控制在五到十行

超過十行通常表示函式承擔了多重職責。判斷是否需要拆分的最快方法：函式名稱裡有「和」或「或」的話，一定要拆。

 1// 錯誤：15行，三種職責混在一起
 2Book processBook(String isbn) {
 3  if (isbn.length != 13) throw ArgumentError('Invalid ISBN');
 4  if (!isValidISBNChecksum(isbn)) throw ArgumentError('ISBN checksum failed');
 5  final apiResponse = httpClient.get('/books/$isbn');
 6  if (apiResponse.statusCode != 200) throw Exception('API failed');
 7  final bookData = json.decode(apiResponse.body);
 8  return Book.create(
 9    id: BookId(generateUniqueId()),
10    title: BookTitle(bookData['title']),
11    source: BookSource.external(),
12  );
13}
14
15// 正確：拆成三個單一職責函式
16Book createBookFromISBN(String isbn) {
17  validateISBNFormat(isbn);
18  final bookData = fetchBookDataFromExternalAPI(isbn);
19  return buildBookFromExternalData(bookData);
20}
21
22void validateISBNFormat(String isbn) {
23  if (isbn.length != 13) throw ArgumentError('ISBN must be 13 digits');
24  if (!isValidISBNChecksum(isbn)) throw ArgumentError('ISBN checksum validation failed');
25}
26
27Map<String, dynamic> fetchBookDataFromExternalAPI(String isbn) {
28  final apiResponse = httpClient.get('/books/$isbn');
29  if (apiResponse.statusCode != 200) throw Exception('Failed to fetch book data');
30  return json.decode(apiResponse.body);
31}
32
33Book buildBookFromExternalData(Map<String, dynamic> bookData) {
34  return Book.create(
35    id: BookId(generateUniqueId()),
36    title: BookTitle(bookData['title']),
37    source: BookSource.external(),
38  );
39}

第三原則：一個變數只做一件事

同一個變數在不同地方承載不同意義，是我見過最難追蹤的 bug 來源之一。

 1// 錯誤：同一變數三種身分
 2var result = validateUser(userData);
 3if (result.isValid) {
 4  result = processPayment(paymentData);
 5  if (result.success) {
 6    result = updateDatabase(result.data);
 7  }
 8}
 9
10// 正確：每個變數都有自己的名字
11final userValidationResult = validateUser(userData);
12if (userValidationResult.isValid) {
13  final paymentProcessingResult = processPayment(paymentData);
14  if (paymentProcessingResult.success) {
15    final databaseUpdateResult = updateDatabase(paymentProcessingResult.data);
16  }
17}

變數生命週期也要管：

 1// 錯誤：books 在100行間一直換狀態
 2void processLibraryBooks() {
 3  var books = getAllBooks();
 4  books = filterAvailableBooks(books);
 5  books = sortBooksByTitle(books);
 6}
 7
 8// 正確：每個階段的狀態都有名字
 9void processLibraryBooks() {
10  final allLibraryBooks = getAllBooks();
11  final availableBooks = filterAvailableBooks(allLibraryBooks);
12  final sortedAvailableBooks = sortBooksByTitle(availableBooks);
13}

第四原則：用事件驅動表達業務流程

複雜的業務流程往往會寫成一個大函式，裡面塞滿 if/else。問題不在於 if/else 本身，而是把不同職責的邏輯混在一起。

 1// 錯誤：驗證、API呼叫、結果處理全混在一起
 2void submitForm(FormData formData) {
 3  if (formData.name.isEmpty) { showErrorMessage('姓名不能為空'); return; }
 4  if (formData.email.isEmpty) { showErrorMessage('Email不能為空'); return; }
 5  if (!isValidEmail(formData.email)) { showErrorMessage('Email格式不正確'); return; }
 6  final apiResult = submitToAPI(formData);
 7  if (apiResult.success) {
 8    showSuccessMessage('提交成功');
 9    navigateToSuccessPage();
10    clearForm();
11  } else {
12    showErrorMessage('提交失敗：' + apiResult.error);
13    highlightErrorFields(apiResult.errorFields);
14  }
15}
16
17// 正確：每個事件有自己的函式
18void submitUserRegistrationForm(UserRegistrationFormData formData) {
19  final validationResult = validateUserRegistrationData(formData);
20  if (validationResult.isValid) {
21    handleSuccessfulValidation(formData);
22  } else {
23    handleValidationFailure(validationResult.errors);
24  }
25}
26
27ValidationResult validateUserRegistrationData(UserRegistrationFormData formData) {
28  final errors = <ValidationError>[];
29  if (!isValidUserName(formData.name)) errors.add(ValidationError.invalidUserName());
30  if (!isValidUserEmail(formData.email)) errors.add(ValidationError.invalidEmail());
31  return ValidationResult.fromErrors(errors);
32}
33
34void handleSuccessfulValidation(UserRegistrationFormData formData) {
35  submitUserRegistrationToAPI(formData)
36    .then(handleSuccessfulAPIResponse)
37    .catchError(handleAPIFailure);
38}
39
40void handleValidationFailure(List<ValidationError> errors) {
41  displayValidationErrors(errors);
42  highlightInvalidFormFields(errors);
43}

狀態機也是同樣的道理：

 1// 錯誤：一個函式根據狀態做完全不同的事
 2void updateBookStatus(Book book, String newStatus) {
 3  if (newStatus == 'available') {
 4    book.status = BookStatus.available;
 5    book.borrower = null;
 6    updateSearchIndex(book);
 7    notifyWaitingUsers(book);
 8  } else if (newStatus == 'borrowed') {
 9    book.status = BookStatus.borrowed;
10    book.borrowDate = DateTime.now();
11    sendBorrowConfirmation(book);
12  } else if (newStatus == 'maintenance') {
13    book.status = BookStatus.maintenance;
14    removeFromSearchIndex(book);
15    notifyMaintenanceTeam(book);
16  }
17}
18
19// 正確：每個事件獨立
20void handleBookReturnEvent(Book book) {
21  executeBookReturn(book);
22  notifyBookBecameAvailable(book);
23}
24
25void handleBookBorrowEvent(Book book, User borrower) {
26  executeBookBorrow(book, borrower);
27  confirmBorrowingToUser(book, borrower);
28}
29
30void handleBookMaintenanceEvent(Book book) {
31  markBookForMaintenance(book);
32  notifyMaintenanceRequired(book);
33}

第五原則：可讀性優於簡潔性

程式碼的價值排序：正確性 > 可讀性 > 可維護性 > 簡潔性。

行數從來不是指標，清晰才是：

 1// 錯誤：為了少寫幾行犧牲可讀性
 2books.where((b) => b.s == 'a' && b.p > 100).map((b) => b.t).toList();
 3
 4// 正確：每一步都說清楚在做什麼
 5final availableBooksWithMoreThan100Pages = allBooks
 6    .where((book) => book.status == BookStatus.available)
 7    .where((book) => book.pageCount > 100)
 8    .toList();
 9
10final bookTitlesForDisplay = availableBooksWithMoreThan100Pages
11    .map((book) => book.title.value)
12    .toList();

如何驗證程式碼品質

陌生人測試：讓不熟悉這段程式碼的工程師讀。5分鐘內能理解主要邏輯算合格，需要解釋才能理解就要重寫。

自然語言測試：把程式碼翻譯成中文說出來。翻譯流暢自然算合格，說不清楚就改命名。

六個月後測試：假設半年後的自己要修改這段程式碼，能快速找到位置算合格，不敢動怕壞掉就要重新設計。

每一行程式碼都是一句話，每個函式都是一個段落。好的程式碼是對未來維護者的體貼——不只是風格偏好，而是降低維護成本的工程決策。

這讓我們重新思考：註解到底是為了誰而寫的？

註解的本質

程式碼註解不是程式的解釋員。它的存在是為了保護原始設計意圖，提供無法從程式碼本身推斷出來的訊息。

不應該做的：解釋程式在做什麼（好的程式碼應該自己說話）、描述函式使用方法（那是文件的工作）、充當 TODO 清單。

應該做的：作為需求保護器，防止維護時破壞原始需求；記錄設計意圖，保存業務邏輯的考量；提供維護指引，明確標示約束條件；建立程式碼與需求規格的連結。

第一原則：程式碼本身必須自說明

如果程式碼需要靠註解才能被理解，首先應該改善的是程式碼，不是補更多解釋。

process(Book book) 需要一行「檢查書籍狀態並更新進度」的註解，但如果直接命名為 updateReadingProgressWhenStatusChanges(Book book)，解釋性的註解就不需要了。此時真正值得寫下來的，是這個函式背後的業務需求和約束條件：

1void updateReadingProgressWhenStatusChanges(Book book) {
2  // 需求：UC-005 閱讀進度管理
3  // 當使用者標記書籍為「閱讀中」時，自動設定進度為 0%
4  // 當使用者標記為「已完成」時，自動設定進度為 100%
5  // 約束：不可覆蓋使用者手動設定的進度值
6}

變數也一樣：final data = book.getInfo() 毫無意義，final enrichedBookMetadata = book.getMetadataWithEnrichment() 就完全自說明了。

驗證標準：移除所有註解後，如果仍能理解程式邏輯，程式碼達標。需要猜測變數含義就重新命名，無法確定函式目的就拆分函式。

第二原則：註解記錄的是需求脈絡

程式碼自說明，不代表不需要註解——需要的是不同種類的註解。

每個業務邏輯函式都應該追溯到明確的需求來源：

1/// 需求：UC-003.2 書籍分類管理
2/// 使用者可以為書籍設定多個標籤進行分類
3/// 約束：標籤名稱不可重複，最多 10 個標籤
4void addTagToBook(BookId bookId, Tag tag) {
5  // 實作...
6}

這條註解告訴維護者：這個函式的存在依據是 UC-003.2，不可以被打破的規則是標籤不可重複且最多十個。

書籍狀態的轉換順序是業務規則，不是技術細節，也應該記錄：

1/// 需求：BR-001 書籍狀態轉換規則
2/// 書籍狀態變更順序：初始 → 資訊補充中 → 資訊補充完成 → 可用
3/// 約束：不可跳過中間狀態，不可逆向轉換
4/// 例外：管理員可以直接設定為任何狀態
5BookStatus transitionBookStatus(BookStatus current, BookStatus target) {
6  // 實作...
7}

設計決策也要記錄。為什麼選懶載入加分頁？因為有效能需求：

1/// 需求：NFR-002 效能需求
2/// 書庫載入時間不可超過 2 秒
3/// 設計決策：採用懶載入 + 分頁載入策略
4/// 影響：首次載入只載入 20 本書，滾動時動態載入
5List<Book> loadLibraryWithPagination(int page, int pageSize) {
6  // 實作...
7}

一個完整的業務邏輯註解必須包含：需求來源（UC 或 BR 編號）、業務描述、約束條件、以及修改此邏輯會影響哪些功能。

第三原則：維護指引必須明確

好的維護指引讓維護者修改程式碼之前就知道會影響哪裡。不應該隨意修改的邏輯，要主動發出警告：

1/// 需求：UC-001.3 書籍唯一性檢查
2/// 同一書庫內不可有相同 ISBN 的書籍
3/// 警告：此邏輯關聯到資料一致性，修改前必須檢查：
4/// - 書籍匯入流程 (ImportBookService)
5/// - 書籍合併功能 (BookMergeService)
6/// - 資料庫索引設計 (book_isbn_unique_index)
7bool isDuplicateBook(String isbn, LibraryId libraryId) {
8  // 實作...
9}

預期會被擴展的邏輯，要提供擴展指引：

1/// 需求：UC-004 書籍搜尋功能
2/// 支援書名、作者、標籤的模糊搜尋
3/// 擴展指引：新增搜尋條件時必須：
4/// 1. 更新 SearchCriteria 值物件
5/// 2. 修改索引策略以維持效能
6/// 3. 更新搜尋測試案例涵蓋新條件
7List<Book> searchBooks(SearchCriteria criteria) {
8  // 實作...
9}

模組間的耦合關係也需要標示：

 1/// 需求：UC-006 借閱管理
 2/// 計算書籍歸還到期日
 3/// 相依性警告：此邏輯與以下模組緊密耦合
 4/// - LoanReminderService（提醒計算）
 5/// - OverdueBookDetector（逾期偵測）
 6/// - LibraryStatistics（統計計算）
 7/// 修改歸還期限計算會影響上述所有模組
 8DateTime calculateDueDate(DateTime loanDate, int loanPeriodDays) {
 9  // 實作...
10}

第四原則：結構一致的標準格式

把上面的原則整合成一個標準格式：

1/// 需求：[需求編號] [簡短描述]
2/// [詳細業務描述，說明使用者需求]
3/// 約束：[限制條件和邊界規則]
4/// [維護指引：修改須知、相依性警告、擴展要求]
5[函式簽名]

複雜業務邏輯的範例：

 1/// 需求：UC-007.1 閱讀統計分析
 2/// 計算使用者的閱讀速度和預估剩餘時間
 3/// 約束：只統計狀態為「閱讀中」的書籍，頁數必須大於 0
 4/// 計算邏輯：(已讀頁數 / 實際閱讀時間) = 閱讀速度（頁/小時）
 5/// 維護指引：修改計算公式會影響：
 6/// - 閱讀目標設定功能
 7/// - 個人化推薦系統
 8/// - 學習分析報表
 9/// 相依模組：ReadingProgressTracker, BookMetadata, UserPreferences
10ReadingSpeed calculateReadingSpeed(
11  ReadingProgress progress,
12  BookMetadata metadata,
13  Duration actualReadingTime
14) {
15  // 實作...
16}

禁止的註解模式

最常見的錯誤是重述程式碼行為。「設定書籍標題」對應的程式碼是 book.setTitle(newTitle)，完全多餘。「使用 Map 快速查找避免 O(n) 複雜度」也一樣，有經驗的開發者看程式碼就知道。

UI 層特別容易出現這類問題。以 Widget 選取回饋設計為例，錯誤做法是列出技術細節：

 1/// 反例：重複描述程式碼內容
 2/// BookListItem - 書庫列表項目 Widget
 3///
 4/// 視覺設計：
 5/// - 陰影刻痕變化（凸起→凹陷）
 6/// - AnimatedContainer 200ms 過渡動畫
 7///
 8/// 觸覺回饋：
 9/// - 選擇時：HapticFeedback.selectionClick()
10/// - 取消選擇：HapticFeedback.lightImpact()
11class BookListItem extends StatelessWidget {
12  // ...
13}

這些看程式碼就能看到。真正有價值的是背後的決策依據：

 1/// 【需求來源】UC-05: 雙模式書庫展示切換 - 書籍選擇互動
 2/// 【規格文件】docs/ui_design_specification.md#book-selection-feedback
 3/// 【設計決策】採用方案C-1基礎版 - 極簡視覺回饋設計
 4/// 【為什麼選擇陰影刻痕變化】
 5/// - 不影響文字可讀性：避免背景色干擾閱讀體驗
 6/// - 符合無障礙設計：不依賴顏色作為唯一視覺提示
 7/// 【為什麼選擇差異化觸覺回饋】
 8/// - 選中 vs 取消必須有不同的觸覺回饋類型
 9/// - selectionClick 提供明確的「確認」感受
10/// - lightImpact 提供輕微的「狀態變更」提示
11/// 【修改約束】
12/// - 觸覺回饋時機不可調換（與使用者預期一致）
13/// - 陰影變化動畫時長需保持 < 250ms（符合 Material Design 規範）
14/// 【維護警告】
15/// - 此 Widget 被 3 個書庫頁面使用
16/// - 修改視覺回饋會影響整體使用者體驗一致性
17class BookListItem extends StatelessWidget {
18  // ...
19}

模糊描述也不可取——「處理書籍相關邏輯」等於沒有描述。過時的 TODO 必須清除，否則會讓人以為某個功能還沒實作。

第五原則：事件驅動架構的特殊需求

在 UseCase 或 Domain 層，函式名稱包含 handle*、on*、process*、emit*、dispatch*，或回傳類型為 Future<>、Stream<> 的函式，都需要標示其在事件流中的角色：

 1/// 【需求來源】UC-01: Chrome Extension 匯入書籍資料
 2/// 【規格文件】docs/app-requirements-spec.md#chrome-extension-import
 3/// 【設計方案】方案C-1基礎版 (v0.12.7 Phase 1)
 4/// 【工作日誌】docs/work-logs/v0.12.7.md - 方案研究和設計決策
 5/// 【事件類型】BookAdded 事件處理
 6/// 【修改約束】修改時需確保事件流完整性，避免影響上游訂閱者
 7/// 【維護警告】此函式被 3 個 UseCase 依賴，修改前需檢查影響範圍
 8Future<void> handleBookAdded(BookAddedEvent event) async {
 9  // 實作...
10}

以 _ 開頭的私有輔助函式（_isValid*、_format*、_convert*、_validate* 等）不包含業務邏輯，豁免詳細業務註解。

第六原則：Widget 獨立性的明確標示

非私有命名（不以 _ 開頭）、繼承自 StatefulWidget、ConsumerWidget、StreamBuilder 或 FutureBuilder 的 Widget，具備獨立狀態，需要明確記錄需求來源和修改約束：

 1/// 【需求來源】UC-05: 雙模式書庫展示切換
 2/// 【規格文件】docs/ui_design_specification.md#book-list-item
 3/// 【設計方案】方案C-1基礎版 - 陰影刻痕變化 + 觸覺回饋
 4/// 【工作日誌】docs/work-logs/v0.12.7.md - UI 互動設計
 5/// 【Widget 類型】獨立狀態管理 Widget
 6/// 【修改約束】此 Widget 具備獨立狀態，下層刷新不觸發上層重建
 7/// 【維護警告】修改前需確認子 Widget 依賴關係
 8class BookListItem extends StatefulWidget {
 9  // 實作...
10}

私有的 StatelessWidget（如 _BookTitleText、_ProgressBar）和純展示型組件，只展示上層傳遞的資料，豁免詳細業務邏輯註解。

第七原則：工作日誌與規格文件的追溯鏈

設計決策涉及複雜研究或多方案比較時，幾行註解無法承載所有背景，需要建立追溯鏈：

1/// 【工作日誌】docs/work-logs/v0.12.7.md - 方案C-1基礎版設計

維護者能循著這條鏈找到完整的決策記錄。業務邏輯也可以指向規格文件章節：

1/// 【規格文件】docs/app-requirements-spec.md#section-name
2/// 【規格文件】docs/event-driven-architecture-design.md#event-flow

這讓程式碼成為整個需求、設計、實作文件體系的一部分，而不是孤立的存在。

品質驗證：兩個測試

可執行性測試：維護者看到這條註解後，能理解業務需求嗎？修改約束明確嗎？需求來源可以追溯嗎？

必要性測試：移除這條註解後，是否會遺失業務脈絡？如果移除後仍能理解程式邏輯，就要檢查它是否只是在重述程式碼。如果內容過時，直接刪除，不要保留會誤導維護者的假資訊。

結論

好的程式碼是自說明的，但好的業務系統還需要一個跨越時間的溝通機制，讓六個月後接手的人能理解每個設計決策背後的原因，不會在不了解背景的情況下破壞原始設計。

這就是我們對程式碼註解的重新定位——需求的守護者。

這是需求保護機制，不是文書工作。

問題不在架構，在派工

Clean Architecture 告訴你「怎麼組織程式碼」，但沒告訴你「怎麼拆 Ticket」。每次 Code Review 都像翻地層，從 Widget 翻到 Entity，不知道從哪開始看；Domain 沒穩定，UI 那層就沒辦法測，整個流程互相等待。

這個銜接點，需要一套專門處理 Ticket 拆法的方法論。

核心原則：一張 Ticket，一個層級

一個 Ticket 只應該修改單一架構層級的程式碼，變更的原因單一且明確。

SRP 說一個類別只有一個改變的原因，我們把它升一層：一張 Ticket 也只有一個改變的原因。

聽起來嚴苛，但實際跑起來好處很直接：Code Review 只需要理解一層的邏輯、測試不需要拉起整個系統、PR 影響範圍可預測，壞掉的時候更容易定位。

我們怎麼定義「五層」

傳統 Clean Architecture 四層中，Interface Adapters 同時處理「事件邏輯」和「資料轉換」，職責太雜，我們把它細分成五層：

Layer 1 — UI/Presentation：純視覺呈現，Widget 長什麼樣。變更原因只有一個：設計稿改了。

Layer 2 — Application/Behavior：事件處理和 UI 邏輯。按鈕點擊怎麼處理、Loading 狀態怎麼切換、Domain Entity 怎麼轉成 ViewModel。Flutter 對應 Controller 和 ViewModel。

Layer 3 — UseCase：業務流程編排。協調多個 Repository 和 Domain Service，把業務步驟串起來。不管 UI 怎麼顯示，也不管資料庫怎麼存。

Layer 4 — Domain Events/Interfaces：定義契約。Repository 抽象介面、Domain Event 結構、跨層 DTO。只定義，不實作。

Layer 5 — Domain Implementation：核心業務邏輯。Entity、Value Object、Domain Service、業務規則驗證。整個系統最穩定的部分。

Infrastructure 層（資料庫、外部 API、EventBus）不納入層級隔離，它的變更驅動是技術決策，不是業務需求，Ticket 設計上本來就獨立對待。

從外而內，而不是從內而外

許多教材說「先設計 Domain 再往外做」，但實際開發時，我們發現從外而內更能控制風險。

原因很簡單：Layer 1 UI 壞掉只影響視覺，Layer 5 Domain 邏輯壞掉影響整個系統的業務規則。從影響最小的地方開始，需求偏差時調整成本低；一開始就動 Domain，到了 UI 才發現需求理解有誤，代價就大得多。

實作順序是 Layer 1 → Layer 2 → Layer 3 → Layer 4 → Layer 5，每層完成後立即驗證。

有幾個例外：架構遷移要先定義 Layer 4 介面契約（Interface-First），讓外層修改有穩定依據；安全性修復從 Layer 5 往外；Bug Fix 從問題根源那層開始。

Ticket 拆分的量化標準

幾個判斷指標：修改檔案數 1 到 3 個（最多 5 個）、預估開發時間 2 到 8 小時（超過一天就拆）、修改層級嚴格限制 1 層、新增程式碼測試覆蓋率 100%。

數字可以商議，但有標準就不用靠直覺判斷「感覺差不多」。

反面教材：

1Ticket：實作書籍收藏功能
2
3變更範圍：
4- lib/ui/pages/book_detail_page.dart       (Layer 1)
5- lib/application/controllers/book_detail_controller.dart  (Layer 2)
6- lib/usecases/add_book_to_favorite_usecase.dart  (Layer 3)
7- lib/domain/entities/favorite.dart        (Layer 5)

這張 Ticket 跨了四層，PR 送出來沒人知道從哪開始審，測試也很難設計。正確做法是拆成四張各自獨立的 Ticket，按依賴順序執行。

如何判斷一段程式碼屬於哪一層

最常模糊的是 Layer 2 和 Layer 3 之間的邊界。判斷流程：

1. 在渲染 UI 元素？→ Layer 1
2. 在處理 UI 事件、控制 UI 狀態、或把 Domain 資料轉成 UI 格式？→ Layer 2（把 Domain Exception 轉成 ErrorViewModel 也是這層的事）
3. 在協調多個 Domain Service 或 Repository、編排業務步驟？→ Layer 3
4. 在定義介面契約或事件結構？→ Layer 4
5. 在實作業務規則或定義 Entity？→ Layer 5
6. 以上都不是 → Infrastructure 層

這套方法論的定位

這是 Clean Architecture 的「派工指南」。Clean Architecture 告訴你程式碼怎麼組織，層級隔離告訴你 Ticket 怎麼拆、按什麼順序做。

它和 Atomic Ticket 方法論也不衝突：Atomic Ticket 強調職責維度（一個 Action 加一個 Target），層級隔離強調層級維度（一個 Ticket 只動一層），兩個維度同時符合才是最完整的 Ticket 設計。

緊急 Hotfix、原型開發、一次性腳本不需要強行套用。但在正常功能開發和重構中，跑起來之後的感覺是：每次把一個大需求拆成按層排好的 Ticket 序列，就等於把架構邊界重新確認了一遍。

這個判斷決定了整個修復方向。判斷錯，我們會花時間做出一個「讓測試通過」但實際上破壞需求的修改。

核心原則：程式服務測試，測試服務需求

測試代表需求的具體描述。為了讓測試通過而修改測試本身，等於在需求上妥協。正確的做法是保持測試不變，調整程式實作直到符合期望。

唯一的例外：需求本身發生了變化——架構調整、業務流程重設計。這兩種情況的判斷，就是整個方法論的核心。

第一步：分類

面對測試失敗，先問「為什麼失敗」，不是「怎麼修」。

程式實作錯誤：需求沒變，但程式行為不符預期——錯誤輸出、邏輯判斷有誤、型別處理不當。處理方式直接：保持測試不變，修正程式。

最容易犯的錯誤，是在這種情況下改了測試的期望值，讓測試配合錯誤的程式。這等於讓錯誤行為成為「正確需求」。

架構變更需求：需求文件已更新，業務流程本質性改變，影響多個模組。這類情況確實需要調整測試，但前提是需求文件已反映這個變更。步驟：先確認文件、評估變更範圍、列出需修改的測試，最後才執行。跳過前置確認直接改測試，和無章法地亂改沒有區別。

觀測公開行為，不觀測內部實作

我們只驗證透過公開介面的輸入輸出、公開屬性的狀態變化。不該碰私有方法的調用順序、私有屬性的中間值。

一旦測試觀測內部狀態，它就和具體實作綁定了，任何重構都會讓測試失敗，即使行為沒變。

 1// 錯誤：觀測內部私有屬性
 2test('書籍驗證應該檢查所有欄位', () {
 3  final validator = BookValidator();
 4  validator.validate(invalidBook);
 5
 6  expect(validator._titleValidated, isTrue);   // 內部狀態
 7  expect(validator._isbnValidated, isTrue);    // 私有屬性
 8});
 9
10// 正確：觀測公開行為結果
11test('書籍驗證應該檢查所有欄位', () {
12  final validator = BookValidator();
13  final result = validator.validate(invalidBook);
14
15  expect(result.isValid, isFalse);
16  expect(result.errors, contains('標題不可為空'));
17  expect(result.errors, contains('ISBN 格式錯誤'));
18});

三個常見的反模式

測試遷就程式：程式返回錯誤值，開發者把測試期望值改成那個錯誤值。測試通過了，bug 也永遠存在了。正確做法：保持期望值不動，修正程式邏輯。

內部狀態依賴：測試直接存取 book._internalState 來驗證操作。一旦重構就失敗。改用公開方法 book.isAvailable() 驗證行為結果。

跳過文件檢查：覺得需求「應該」要改，就直接改測試，沒確認需求文件是否更新。正確做法：先查規格書，確認文件已反映變更，再評估影響範圍，最後才動手。

驗收標準

修復前：錯誤類型已判斷、需求文件狀態已確認、受影響測試範圍已識別。

修復後：所有測試 100% 通過、無內部狀態曝露、無行為旁路、每個修改都有測試保護。

100% 通過率是底線。某個測試通過不了，不是跳過它或修改它，是找出真正的問題。

為了提升AI開發前端的穩定性，我想依賴MVVM確實定義前端的狀態跟模型，以及責任分層，這樣可以降低除錯的複雜度

核心概念

ViewModel 定位

ViewModel 是 MVVM 架構的核心層，負責：

1. Domain → UI 轉換：將 Domain 模型轉為 UI 需要的格式
2. UI 狀態管理：管理 Widget 狀態和互動邏輯
3. Provider 定義：定義 Riverpod Provider 供 Widget 使用
4. UI 專用計算邏輯：提供顏色、圖標、格式化文字等 UI 屬性

MVVM 分層原則

 1┌─────────────────────────────────────────┐
 2│ Presentation Layer (UI 層)              │
 3├─────────────────────────────────────────┤
 4│ Widget (Page/Extensions)                │
 5│ - 純 UI 組裝，無業務邏輯                 │
 6│ - 使用 ViewModel Provider 取得資料       │
 7│ - 顯示 ViewModel 提供的 UI 屬性          │
 8├─────────────────────────────────────────┤
 9│ ViewModel                               │
10│ - Domain → UI 轉換                       │
11│ - UI 狀態管理                            │
12│ - UI 專用計算邏輯                        │
13│ - Provider 定義                          │
14├─────────────────────────────────────────┤
15│ Mapper                                  │
16│ - Domain 模型 → ViewModel 轉換邏輯       │
17├─────────────────────────────────────────┤
18│ Domain Layer (領域層)                    │
19│ - 業務邏輯                               │
20│ - Domain 模型                            │
21│ - Domain 服務                            │
22└─────────────────────────────────────────┘

ViewModel 命名規範

命名格式

格式：[Feature]ViewModel

範例：

• EnrichmentProgressViewModel - 補充進度顯示
• ChromeExtensionImportViewModel - Chrome Extension 匯入
• LibraryDisplayViewModel - 書庫展示
• AdvancedSearchViewModel - 進階搜尋

檔案位置

標準路徑：lib/presentation/[feature]/[feature]_viewmodel.dart

範例：

1lib/presentation/
2├── import/
3│   └── chrome_extension_import_viewmodel.dart
4├── library/
5│   ├── library_viewmodel.dart
6│   └── library_display_page.dart
7└── search/
8    └── advanced_search_viewmodel.dart

ViewModel 職責定義

包含的職責

1. Domain → UI 轉換

將 Domain 模型轉換為 UI 需要的格式：

1/// Domain 來源
2final EnrichmentProgress domainProgress;
3
4/// UI 專用欄位（計算屬性）
5String get displayStatus => _mapStatus();
6IconData get statusIcon => _mapIcon();
7Color get progressColor => _mapColor();

2. UI 狀態管理

管理 Widget 需要的狀態：

1class EnrichmentProgressViewModel {
2  // 狀態欄位
3  final EnrichmentProgress domainProgress;
4  final List<Book> failedBooks;
5
6  // UI 控制狀態
7  bool get showFailedBooks => failedBooks.isNotEmpty;
8  bool get canRetry => domainProgress.isComplete && failedBooks.isNotEmpty;
9}

3. Provider 定義

定義 Riverpod Provider 供 Widget 使用：

1final enrichmentProgressViewModelProvider =
2  StreamProvider.family<EnrichmentProgressViewModel, String>(
3    (ref, operationId) {
4      // Provider 邏輯
5    },
6  );

4. UI 專用計算邏輯

提供 UI 需要的格式化資料：

 1/// 格式化的摘要文字
 2String get summaryText =>
 3  '已處理 ${domainProgress.processedBooks}/${domainProgress.totalBooks} 本';
 4
 5/// 進度顏色（根據狀態決定）
 6Color get progressColor {
 7  if (domainProgress.failedEnrichments > 0) return Colors.orange;
 8  if (domainProgress.isComplete) return Colors.green;
 9  return Colors.blue;
10}

不包含的內容

1. Widget 程式碼

 1// 反例：ViewModel 中包含 Widget
 2class EnrichmentProgressViewModel {
 3  Widget buildProgressBar() {  // 違規
 4    return LinearProgressIndicator(...);
 5  }
 6}
 7
 8// 正例：Widget 在 Extension 中
 9extension EnrichmentProgressWidgets on Widget {
10  Widget enrichmentProgressBar(EnrichmentProgressViewModel vm) {
11    return LinearProgressIndicator(
12      value: vm.domainProgress.percentageComplete / 100,
13      color: vm.progressColor,
14    );
15  }
16}

2. 直接依賴 Flutter 框架（除 ChangeNotifier）

 1// 反例：依賴 Flutter Material
 2import 'package:flutter/material.dart';
 3
 4class MyViewModel {
 5  BuildContext? context;  // 違規
 6}
 7
 8// 正例：使用 Dart 原生類型
 9class MyViewModel {
10  Color progressColor;  // 可以使用 Color（來自 dart:ui）
11  IconData statusIcon;  // 可以使用 IconData
12}

3. 業務邏輯

 1// 反例：在 ViewModel 中執行業務邏輯
 2class EnrichmentProgressViewModel {
 3  Future<void> enrichBook(Book book) {
 4    // 呼叫 API、驗證資料、儲存到資料庫
 5    // 這些是 Domain 層的職責
 6  }
 7}
 8
 9// 正例：業務邏輯在 Domain Service
10class IBookInfoEnrichmentService {
11  Future<EnrichedBookInfo> enrichBookInfo(Book book);
12}
13
14// ViewModel 只負責狀態管理
15class EnrichmentProgressViewModel {
16  final EnrichmentProgress domainProgress;
17  // 不包含業務邏輯
18}

ViewModel 結構範本

基本結構

 1/// UI 層專用的 [Feature] 顯示模型
 2///
 3/// 職責：
 4/// - 將 Domain 模型轉換為 UI 需要的格式
 5/// - 提供 UI 專用的計算屬性
 6/// - 管理 UI 狀態
 7///
 8/// 需求：[需求編號]
 9class [Feature]ViewModel {
10  // =============================================================================
11  // Domain 來源（不可變）
12  // =============================================================================
13
14  /// Domain 模型來源
15  final [DomainModel] domainModel;
16
17  /// 額外的 Domain 資料（如失敗清單）
18  final List<[Entity]> additionalData;
19
20  // =============================================================================
21  // UI 專用欄位（計算屬性）
22  // =============================================================================
23
24  /// 狀態顯示文字
25  String get displayStatus => _mapStatus();
26
27  /// 狀態圖標
28  IconData get statusIcon => _mapIcon();
29
30  /// 進度顏色
31  Color get progressColor => _mapColor();
32
33  /// 摘要文字
34  String get summaryText => _formatSummary();
35
36  // =============================================================================
37  // 建構子
38  // =============================================================================
39
40  const [Feature]ViewModel({
41    required this.domainModel,
42    this.additionalData = const [],
43  });
44
45  // =============================================================================
46  // Domain → UI 轉換方法（私有）
47  // =============================================================================
48
49  /// 對應狀態到顯示文字
50  String _mapStatus() {
51    // 轉換邏輯
52  }
53
54  /// 對應狀態到圖標
55  IconData _mapIcon() {
56    // 轉換邏輯
57  }
58
59  /// 對應狀態到顏色
60  Color _mapColor() {
61    // 轉換邏輯
62  }
63
64  /// 格式化摘要文字
65  String _formatSummary() {
66    // 格式化邏輯
67  }
68}

完整範例：EnrichmentProgressViewModel

  1import 'package:flutter/material.dart';
  2import 'package:book_overview_app/domains/import/value_objects/enrichment_progress.dart';
  3import 'package:book_overview_app/domains/library/entities/book.dart';
  4
  5/// UI 層專用的補充進度顯示模型
  6///
  7/// 職責：
  8/// - 將 EnrichmentProgress Domain 模型轉為 UI 格式
  9/// - 提供進度顏色、圖標、文字等 UI 屬性
 10/// - 管理失敗書籍清單的顯示
 11///
 12/// 需求：UC-01.Enrichment.Progress
 13class EnrichmentProgressViewModel {
 14  // =============================================================================
 15  // Domain 來源
 16  // =============================================================================
 17
 18  /// Domain 進度模型
 19  final EnrichmentProgress domainProgress;
 20
 21  /// 失敗補充的書籍清單
 22  final List<Book> failedBooks;
 23
 24  // =============================================================================
 25  // UI 專用欄位（計算屬性）
 26  // =============================================================================
 27
 28  /// 狀態顯示文字
 29  ///
 30  /// 對應規則：
 31  /// - processedBooks == 0 → "準備中"
 32  /// - processedBooks > 0 && !isComplete → "補充中"
 33  /// - isComplete → "已完成"
 34  String get displayStatus {
 35    if (domainProgress.isComplete) return '已完成';
 36    if (domainProgress.processedBooks == 0) return '準備中';
 37    return '補充中';
 38  }
 39
 40  /// 狀態圖標
 41  ///
 42  /// 對應規則：
 43  /// - 準備中 → Icons.pending
 44  /// - 補充中 → Icons.sync
 45  /// - 已完成 → Icons.check_circle
 46  IconData get statusIcon {
 47    if (domainProgress.isComplete) return Icons.check_circle;
 48    if (domainProgress.processedBooks == 0) return Icons.pending;
 49    return Icons.sync;
 50  }
 51
 52  /// 進度顏色
 53  ///
 54  /// 對應規則：
 55  /// - 有失敗 → 橘色警告
 56  /// - 已完成 → 綠色成功
 57  /// - 進行中 → 藍色
 58  Color get progressColor {
 59    if (domainProgress.failedEnrichments > 0) return Colors.orange;
 60    if (domainProgress.isComplete) return Colors.green;
 61    return Colors.blue;
 62  }
 63
 64  /// 摘要文字
 65  ///
 66  /// 格式：「已處理 X/Y 本（成功 A，失敗 B）」
 67  String get summaryText {
 68    final processed = domainProgress.processedBooks;
 69    final total = domainProgress.totalBooks;
 70    final success = domainProgress.successfulEnrichments;
 71    final failed = domainProgress.failedEnrichments;
 72
 73    if (failed > 0) {
 74      return '已處理 $processed/$total 本（成功 $success，失敗 $failed）';
 75    }
 76    return '已處理 $processed/$total 本';
 77  }
 78
 79  /// 失敗書籍摘要清單
 80  ///
 81  /// 提供簡化的書籍資訊供 UI 顯示
 82  List<BookSummary> get failedBooksSummary {
 83    return failedBooks.map((book) => BookSummary.fromBook(book)).toList();
 84  }
 85
 86  /// 進度百分比（直接使用 Domain 計算）
 87  double get progressPercentage => domainProgress.percentageComplete;
 88
 89  /// 當前處理書名（如果有）
 90  String? get currentBookTitle => domainProgress.currentBook?.title.value;
 91
 92  /// 是否顯示失敗清單
 93  bool get showFailedBooks => failedBooks.isNotEmpty;
 94
 95  /// 是否可以重試
 96  bool get canRetry => domainProgress.isComplete && failedBooks.isNotEmpty;
 97
 98  // =============================================================================
 99  // 建構子
100  // =============================================================================
101
102  const EnrichmentProgressViewModel({
103    required this.domainProgress,
104    this.failedBooks = const [],
105  });
106}
107
108/// 書籍摘要（UI 專用簡化資料）
109class BookSummary {
110  final String id;
111  final String title;
112  final String author;
113
114  const BookSummary({
115    required this.id,
116    required this.title,
117    required this.author,
118  });
119
120  factory BookSummary.fromBook(Book book) {
121    return BookSummary(
122      id: book.id.value,
123      title: book.title.value,
124      author: book.author.value,
125    );
126  }
127}