測試本身需要被驗證。 一個從沒看過 RED 的測試 = 未驗證的訊號、不是「會抓回歸的測試」。

驗證一個測試真的有用、需要看到兩個訊號：

1. RED：測試在「該失敗的版本」上失敗（buggy code → 紅）
2. GREEN：測試在「該通過的版本」上通過（fixed code → 綠）

只看過 GREEN = 不知道測試有沒有 catch 能力；只看過 RED = 不知道修復有沒有真的解問題。兩個都看到 = 測試 + 修復都被驗證。

跳過 RED 把驗收標準降到「測試跑得通」、漏掉「測試自己有沒有 bug」這層。

為什麼測試需要被驗證

測試是程式 about 程式、會有 bug

測試本身是程式碼、跟其他程式碼一樣會有 bug：

這五種都會讓「跑測試一次就 GREEN」是個假訊號 — 測試 pass 不代表測試 catch 到該 catch 的東西。

RED 是測試的「使用者驗收」

對使用者代碼、我們會用「驗收訊號」（功能跑得對）證明它有用。測試也需要驗收訊號。

「測試 catch 到 bug」這個能力的驗收訊號 = 「在有 bug 的代碼上失敗」。沒看過這個訊號就相信測試 = 跳過驗收。

對應 #42 2 次門檻：一次 GREEN 是低資訊量訊號、RED → GREEN 是 2 次跑（一次 fail 一次 pass）的高資訊量訊號。

多面向：四種情境的 RED-GREEN 應用

情境 1：修 bug

11. 先寫一個 test 重現 bug 為失敗 — 例：「filter 後 0 筆但 source 還有未載入時、應該顯示 explicit empty 而非 silent」
22. 跑測試 → RED（證明測試抓到 bug、bug 真的存在）
33. 修 code
44. 跑測試 → GREEN（證明修對了 + 測試會抓回歸）

跳過第 2 步 = 不知道測試會不會抓到、不知道 bug 真的有沒有。

情境 2：加 feature

11. 寫 acceptance test 描述新 feature 該有的行為
22. 跑測試 → RED（feature 還沒實作、應該 fail；如果 GREEN 就表示 feature 已經存在或測試太寬）
33. 實作 feature
44. 跑測試 → GREEN

加 feature 時跳過 RED 風險：feature 被誤以為實作但實際是 stub、或測試根本沒驗到 feature。

情境 3：Refactor

11. 確認當前測試 GREEN（baseline）
22. Refactor（不改 behavior）
33. 跑測試 → 仍 GREEN

Refactor 不需要 RED — 因為 behavior 沒變。如果 refactor 後變 RED、表示 refactor 改到了 behavior（變成隱性 bug）、要回頭看。

情境 4：偵錯（不確定 bug 是什麼）

11. 寫一個 test 嘗試重現問題
22. 跑測試 → 看是 RED 還是 GREEN：
3   - RED → 重現成功、現在可以著手修
4   - GREEN → 沒重現到 / 測試寫錯 / bug 在別處 → 重新理解 bug
53. 修
64. 跑測試 → GREEN

「看是 RED 還是 GREEN」這個動作本身是 debug 訊號 — 比單純猜根因有用。

「只看 GREEN 不看 RED」是反模式

反模式 1：修完才補測試（Test-after）

11. 修 bug code
22. 寫測試
33. 跑測試 → GREEN
44. ship

問題：測試從沒跑過 buggy code、不知道它能不能抓到 bug。未來 regression 進來、測試可能仍然 GREEN（測試本身有 bug）。

反模式 2：「快速跑一下測試」沒看訊號

11. 寫測試
22. 跑「應該 pass 吧」、不仔細看輸出
33. 看到 PASS → 安心

問題：可能測試 skip 了、可能測試 zero assertions、可能環境錯了。需要看「具體 catch 到什麼」、不只是「是否 PASS」。

反模式 3：測試 PASS 但 coverage 是 0

11. 寫測試 file
22. CI 跑、看到「all green」
33. 沒看 coverage report

問題：測試文件存在但實際沒 import / 沒執行、CI 報告 GREEN 是因為「沒 fail」不是「有 catch」。

不該套用本原則的情境

「先看 RED 再看 GREEN」原則在大多數情境成立、但有合理例外：

四類共同特徵：沒有「行為差異」可被測試 catch — 本原則建立在「測試該 catch 的事」上、沒事可 catch 時自然不適用。

跟其他抽象層原則的關係

本卡是把「測試這個動作本身」放進驗收體系：寫測試是動作、跑測試的訊號才是驗收。動作完成 ≠ 驗收完成。

對應的實作篇

把測試固化的實作 case 都該套用本卡：

• #11 playwright-early-in-loop — 第 2 次推理失敗切 playwright；切過去後寫的 evaluate query 跑 RED-GREEN 才驗證
• #15 layout-tests-with-playwright — 版型 debug 兩次以上寫測試固化；測試該先在「未修版型」跑 RED 才相信
• #23 verification-method-timing — 驗證方法選對之後、實際驗證需要 RED-GREEN

Retrospective 補驗證的協議

如果已經修完才寫測試（test-after）、可以 retrospectively 補 RED-GREEN 驗證：

 1# 1. Stash 現有變動 / 切到修前 commit
 2git stash
 3git checkout <pre-fix-commit>
 4
 5# 2. Cherry-pick 測試 commit（或手動複製 test files）
 6git cherry-pick <test-commit>
 7# 或：cp ../tests/foo.spec.ts tests/  # 複製測試檔過來
 8
 9# 3. Build + 跑測試
10make site && npm test
11# 預期：RED（測試抓到 bug）
12
13# 4. 切回 main / 修後版本
14git checkout main
15git stash pop
16
17# 5. 跑測試
18npm test
19# 預期：GREEN

兩次跑 + 兩個訊號（RED + GREEN）都對、測試才被驗證。Retrospective 補驗證 ≠ 不能補 — 比完全跳過 RED 好、比 test-first 弱。

協議已 codify 為 make verify-red-green PRE_FIX=<commit-sha>（見 Makefile）— 五步驟自動化、不需要每次手動 stash / checkout / build / restore。

Self-case：本卡誕生過程的 dogfooding 失敗

本卡是從一次真實的 dogfooding 失敗抽出來的。修 #55 Filter × Source 層錯位 bug 時、流程是：

1. 修 code（multi-index 策略）
2. 寫 4 個 Playwright tests
3. 跑測試 → 4/4 GREEN
4. 看起來完工

User 問「修改之前有先寫測試確保符合預測狀態嗎」— 才意識到沒走 RED。Retrospective 補驗證後發現：4 個測試只有 1 個真的 catch 到 bug、其他 3 個對 buggy code 也 PASS（placebo 測試）。

強化後（用 network-level + structural assertion 替換弱 invariant）：buggy code 上 1/4 PASS、3/4 FAIL。Fixed code 上 4/4 PASS。RED-GREEN 兩個訊號都看到、測試才真的驗證。

如果不做 retrospective、會帶著 3/4 placebo 測試 ship — 表面 4/4 GREEN、實際只有 1 個真的防回歸。「跑得通」≠「會 catch」這個區別、只有走過 RED 才知道。

跳過 RED 是 #72 高 ROI 無外部觸發的工作 在測試協議的展現 — 修法不是「下次記得」（L1 紀律會失敗）、是 make verify-red-green PRE_FIX=<sha>（L3 工具觸發）+ pre-commit hook 提醒（L3 結構觸發）。

判讀徵兆

核心原則：測試不是「跑得通就有用」、是「跑出該有的訊號才有用」。RED 是測試的驗收訊號、跳過 = 接受測試本身可能是壞的。RED → GREEN 兩次跑、才證明「測試真的會 catch + 修復真的解掉 bug」。

57 個 unit test 全綠，但沒有任何機制能回答「這些測試覆蓋了哪些 UseCase 場景」。

monitor 專案 v0.1.0 從需求文件系統（Proposal → Spec → UseCase）一路走到 Collector 實作，中間經過 BDD 測試設計、紅燈測試撰寫、骨架實作讓綠。流程表面上順暢——10 個根 Ticket 全部完成、Collector 可啟動、所有 unit test 通過。但回頭檢視發現：需求→測試的銜接是單向管道，沒有反向追溯，也沒有邊界回補流程。

本文記錄 v0.1.0 的完整流程、發現的五個結構性差異、和落地的解決方案。

實際走過的流程

1saas 選型訪談
2  → Proposal（MVP 範圍界定）
3    → Spec（14 份，涵蓋 schema/ingestion/query/storage/rule-engine/SDK）
4      → UseCase（5 個，UC-01 端到端事件流 ~ UC-05 Web 監控）
5        → BDD 測試設計 ANA（全專案 26 個行為場景 → 整合/單元/協議測試清單）
6          → 紅燈測試（9 個 Ticket 並行，72 個測試 FAIL）
7            → 骨架實作（1 個 Ticket，57 個 unit test GREEN）

每個箭頭都有對應的框架機制：saas→doc 有 Stage 6 銜接、doc→TDD 有 doc-handoff 映射表。但箭頭只往右——沒有任何箭頭往左。

五個結構性差異

差異 1：「全專案 BDD 設計」不在 TDD Phase 模型中

TDD Skill 定義 Phase 0→1→2→3→4 的逐功能流程。v0.1.0 做的是「全專案 UseCase 一次性展開為 BDD 測試設計」，跨越 Phase 1 和 Phase 2 的邊界，粒度是專案級不是功能級。

這不是 Phase 設計的錯——Phase 模型適合增量開發（每次加一個功能）。新專案起手是不同的工作模式：批量設計、模組群組粒度。

解法：在 doc-handoff 新增「新專案起手模式」章節，描述批量 BDD 設計流程、Phase 0 豁免條件、模組群組粒度。

差異 2：紅燈測試需要存根（stub）

Go 是靜態語言，go test 必須編譯通過才能執行。紅燈測試引用的 type/interface 不存在時直接編譯失敗，不是「測試 FAIL」。

TDD Skill 的 Phase 2 說「設計測試」、Phase 3b 說「讓測試綠」，但中間的「建存根讓測試可紅」沒有定義。

實作驗證：v0.1.0 的每個紅燈 Ticket 都自帶建立存根（空 function return nil / 空 struct / 回 501 的 HTTP handler），存根讓 go test 編譯通過，合法測試 PASS、非法測試 FAIL = 紅燈狀態。

解法：Phase 3 rules 新增「存根策略」章節，涵蓋靜態語言（Go/Dart）和動態語言（Python/JS）的不同處理。

差異 3：測試→UseCase 沒有反向追溯

寫完 57 個 unit test 後，問「UC-01 的替代場景 01a（批次部分失敗 → 207）被哪些測試覆蓋？」——沒有任何機制能回答。

doc test-map UC-01 工具存在但回傳 0 個測試——因為它搜尋 UC frontmatter 的 ticket_refs，和測試檔案沒有連結。Spec 的「三方交叉比對」是建 Ticket 時的一次性動作，不是持續追溯。

解法：建立 docs/traceability.yaml 追溯矩陣，三層追溯（UC 場景 → 整合測試 IT-* → 單元測試 UT-* → Spec FR）。每個 entry 標記 covered / gap / deferred。

差異 4：邊界條件發現後沒有回補 UC 的流程

寫 Ingest Handler 測試時發現：「如果 POST body 不是 JSON 怎麼辦？」「如果 Content-Type 是 text/plain（sendBeacon）怎麼辦？」這些邊界在 UC-01 的場景描述中不存在。

測試設計的 BDD ANA 有涵蓋這些邊界場景，但 UC 文件本身沒有更新。邊界條件「住」在測試設計文件而非 UseCase——下次有人讀 UC 不會知道這些邊界存在。

解法：追溯矩陣增加 boundaries: 區段，測試撰寫者發現新邊界時加 gap entry，PM 建 DOC Ticket 回補 UC/Spec。Phase 4d 掃描所有 gap 確認無遺漏。

差異 5：Ticket 拆分邊界未對齊測試變綠驗收點

Collector 實作被拆為 4 個 Ticket：骨架（interface 定義）/ Storage / Ingestion Handler / Query Handler。骨架 Ticket 指派做「main.go + Config + Storage interface」，代理人完成了所有模組實作——57 個 unit test 從紅全部變綠，其餘 3 個 Ticket 的 acceptance 全被涵蓋。

初看像是「代理人超額完成」，回頭用判讀三問檢查骨架 Ticket：完成後有測試變綠嗎？→ 沒有（只定義 interface）。能獨立跑測試嗎？→ 不能（其他模組引用骨架的 type）。共用 type？→ 是。三問全部指向「不應獨立拆」。根因是 Ticket 拆分設計，不是代理人行為——按 Spec FR 拆（輸入驅動）導致骨架 Ticket 完成後 0 個測試狀態改變，不是有意義的驗收點。

判讀規則：實作 Ticket 的拆分邊界必須對齊「測試從紅變綠」的驗收點。一個 Ticket 完成後若沒有任何測試狀態改變，它不應該是獨立 Ticket。

判讀三問：

1. 這個 Ticket 完成後，有測試從 FAIL 變 PASS 嗎？
2. 拆出的各部分能獨立跑測試嗎？
3. 不同部分共用同一組 type/error/constant 嗎？

反模式：按 Spec FR 拆（輸入驅動）。正確做法：按「哪組測試變綠」拆（輸出驅動）。

追溯矩陣的設計

追溯矩陣是三個問題（向上追溯 + 覆蓋驗證 + 邊界回補）的統一解法。

結構

 1UC-01:
 2  title: 端到端事件流
 3  scenarios:
 4    main:
 5      integration_tests: [IT-01-01]
 6      unit_tests: [UT-COL-01-01, UT-COL-02-01, UT-COL-04-01]
 7      spec_frs: [SPEC-002-FR-01, SPEC-003-FR-01]
 8      status: covered
 9    alt-01a:
10      integration_tests: [IT-01-02]
11      unit_tests: [UT-COL-01-03, UT-COL-02-03]
12      spec_frs: [SPEC-002-FR-02]
13      status: covered
14
15boundaries:
16  batch-limit:
17    discovered_during: "ingestion-handler-red-tests"
18    status: gap  # 需回補 UC/Spec

三個問題的對應

整合點

附帶發現：並行派發的 Git 隔離問題

5 個代理人以 worktree 並行派發時，commit 內容交叉混入——A 代理人的 commit 包含 B 代理人的檔案。根因：主 repo 不在 main 分支，多個 worktree 共用同一分支 ref，git add + commit race condition。

防護：派發前確保主 repo 在 main + 已 push。單一代理人和正確條件下的多代理人都驗證通過。

結論

v0.1.0 的流程不是失敗——Collector 可用、57 個 test GREEN。問題在於「走到終點後沒有辦法回頭驗證起點」。需求→測試的管道是單向的：Proposal 說了什麼、Spec 定了什麼 FR、UC 描述了什麼場景，和最終的測試之間沒有結構化連結。

追溯矩陣不增加任何程式碼——它是一個 YAML 檔案，記錄「每個測試為什麼存在」。維護成本是每次寫測試多填一行映射。回報是：任何時候都能回答「這個 UC 場景有沒有被測試保護」。

content/report/ 累積了 70+ 張原子化事後檢討卡片、.claude/skills/ 收錄三個 protocol skill。這些是用來指導下一輪實作、又會被下一輪實作的學習回流修正的活基礎建設。

本文把這套系統實際跑一輪的歷程紀錄下來、當未來「想用這套系統的人」的 onboarding case study。主軸是修一個 search filter bug — 看似一週工作、實際走完八輪迭代、產出 14 張新卡片 + 兩個 skill 的 v0.2 + 4 個 CI test、過程中還抓到自己的 dogfooding 失敗、回頭修一次。

起點：使用者問題

“我們搜尋頁的 標題/內文篩選功能現在雖然做出來了、但是還是有一個很嚴重的 BUG”

具體：Pagefind 分批 load、view 層 post-filter；切到 title-only 後、第二批 load more 的 8 筆全部 title 不含 query → 全 hidden、畫面閃但內容沒變、使用者看到「load more 沒效果」silent 失敗。

User 還明確補了一句：「所以除了用 JS 取巧解決畫面、但是實際功能面上怎麼配合跟實作 我們並沒有解決」— 這已經點到核心：問題不在畫面、在抽象層。

第一輪：拆卡片之前先想清楚

直接修 bug 是可選但不是 user 要的。User 強調：「先思考我的需求、然後思考各種狀況的邊界」。

依當時的兩個 skill — requirement-protocol（對話協議）跟 frontend-with-playwright（前端執行協議）— 把問題分解：

1. Bug 的結構性根因：filter 寫在視覺層、source 在資料層分批、兩層的「一筆」定義不一致 → silent 缺口
2. 解法策略空間：5 個合理選項（推進 query / 自動續抓 / 多 index / 誠實 UX / 明示縮小）— 每個機會成本不同
3. 跨領域通用性：這結構不只前端有 — 後端 middleware filter、map-reduce、SQL view 都同模式

User 的關鍵回應：「這部份可以補充 SKILL 中演算法不足的原因 … 卡片是經過多次迭代、擴充、然後分拆、再擴充、最後做連結」。

明確了協作方式：先建卡片、再灌進 skill、最後才修。卡片本身要走原子化拆解 → 補充 → 反向擴充 → 連結的多輪迭代。

14 張卡片的拆解（第一冷啟）

依 user 對 atomic 的標準（一卡一議題、一個議題多面向 OK、議題太多就拆），列出 10 張卡片提案：

冷啟版本一次寫完不求完美 — 約 1700 行、各卡 self-contained。

七輪迭代

迭代 1：抽 Pattern + 瘦身

寫完 #59 五策略後、發現 A/B/C/D/E 中 C（多 index）、E（明示縮小）沒對應 pattern 卡。抽出 #65 / #66 補完 pattern 卡組。同時瘦身 #59 → 純路由（細節留 pattern 卡）、#55 + #57 移除跟 #63 重複的「四類資料源」段。

迭代 2：補概念深度

回頭讀 #56 / #63 / #64、補抽象層的「為什麼」：

• #56 加「驗收的時間軸：四個 checkpoint」概念
• #63 加「形狀識別 protocol」+「形狀混合」+「形狀的可改造性」
• #64 加「跨領域通用的本質 = 資訊可見範圍」+「上推代價」

迭代 3：跨卡連結

新卡跟 #1-#54 既有卡互相補連結。例如 #55 ↔ #11 playwright、#57 ↔ #38 aria-live、#58 ↔ #21 decide-vs-confirm、#64 ↔ #43 minimum-scope + #44 SSOT。整個 collection 從兩個獨立輪次變一張互連網。

迭代 4：抽更高層原則

重讀新卡發現兩個議題夠 abstract、值得抽獨立卡：

• #67 寫作便利度跟意圖對齊反相關 — 從「為什麼層錯位 bug 容易寫出來」抽出。發現它是 #43 / #44 / #45 / #64 的共同上位原則：便利位置 vs 對齊位置永遠反相關
• #68 驗收的時間軸：四個 checkpoint — 從 #56 抽出獨立成卡

迭代 5：跨輪共骨

系統性掃 #1-#54 找跟新系列共骨的、加連結。例：#6 filter-order ↔ #58 / #59、#10 placeholder ↔ #68、#15 layout-test ↔ #68、#14 selector / #20 failure / #28 class-toggle ↔ #67。

迭代 6：#67/#68 加深

再讀兩張抽象卡、補「為什麼人會違反這條規則」的結構性解釋：

• #67 加「便利度的時間維度：當下便利 vs 未來便利反向」+「我等下會 refactor 是個謊言」
• #68 加「為什麼 Ship 前 checkpoint 最常被跳過」（沒便利路徑）+「瀑布原則：漏一層代價指數放大」

從「規則陳述」進到「結構性解釋」 — 不只說「該怎麼做」、也說「為什麼人會違反」。

迭代 7：compositional-writing 規範稽核

User 提醒「再做一次 compositional-writing 的檢查」。發現兩類違規：

1. Rule 7 違規：26 處「X 才合理的情境：實務上幾乎不存在」假反模式 — 改成「X 是反模式：理由」格式
2. 結構違規：#67/#68 是抽象層原則卡、不該寫設計取捨 ABCD（情境檢討卡的格式）— 改成「不該套用本原則的情境」（適用邊界）

修完 31 張卡片（含既有 #1-#54）。整個 collection 對齊 v0.6 規範。

灌進 Skills

把 #55-#68 系列接進兩個 skill：

• requirement-protocol v0.2：clarifying-ambiguous-instructions 加第 5 類「篩選類」+ 三問模板（呼應 #58）；SKILL.md 加「相關抽象層原則」段路由 #42-45 + #67-68
• frontend-with-playwright v0.2：新增第 7 份 reference data-flow-and-filter-composition（涵蓋 #55-#66 跨領域範例）；強調「不只前端、適用後端 / 演算法 / DB」

Skill 的角色 = 路由器、Reports = 深度內容 — 兩層分工不重述。

實作：策略 C + Phase 1-4

依 #59 + Pagefind 1.5.2 capabilities：

• A 推進 query：不可行（Pagefind 無 native title filter API）
• C 多 index：採用（最對齊意圖）
• B / D / E 是 fallback

Phase 1-4：

1. Makefile 跑 3 輪 pagefind（all / title / content）
2. single.html <content> → <div class="article-body" data-pagefind-body>
3. search.html 移除 view 層 post-filter、改 destroy + new PagefindUI(bundlePath)
4. 4 個 Playwright tests 固化

跑出來：make site 三 index 成功、make test 4/4 PASS、live 驗證 sparse case 顯示 explicit empty。看起來完工。

User 抓到 dogfooding 失敗 — 第 8 輪

User 問：「剛剛的過程我不確定、你開始修改之前有先寫測試確保符合預測狀態、然後才調整嗎？」

沒有。流程是：先修 → 才補測試 → 4/4 GREEN。沒走 RED。

這是 #67「便利驅動」+ #68「Checkpoint 2/3 內部協議」的 dogfooding 失敗。我寫了 #67/#68 教這些原則、自己卻違反。

依 user 規範：先建卡片再修。抽 #69 Test-First：先看到 RED 才相信 GREEN：

• 測試本身是程式、會有 bug（5 種失敗模式）
• 沒看過 RED = 不知道測試有沒有 catch 能力
• RED → GREEN 兩個訊號都看到 = 測試 + 修復都被驗證

retrospective 補驗證流程：checkout pre-fix commit → cherry-pick test → build → run（看 RED）→ restore → run（看 GREEN）。

跑下去 — 結果震撼：4 個測試只有 1 個真的 catch 到 bug、其他 3 個對 buggy code 也 PASS（placebo）。如果不做 retrospective、會帶著 3/4 placebo 測試 ship。

強化測試（network-level + structural assertion 替換弱 invariant）：buggy code 1 PASS / 3 FAIL、fixed code 4 PASS。RED-GREEN 真的 catch 到 bug + 真的解掉。

User 抓到第二個 dogfooding 失敗 — Checkpoint 1

我問 user 還有什麼該迭代。User 列了 7 項、選 1+2：

1. 補 Checkpoint 1（列使用者意圖完整集）
2. 跟 user 確認 known limitations

跑 Checkpoint 1 retrospective — 用 Playwright MCP 系統性測 5 維度（data / interaction / URL / a11y / performance）。發現 3 個 silent 缺口：

依 user 規範：先建卡片再修。抽：

• #70 URL 是 stateful UI 的儲存層 — 5 個儲存層特性對照 + 三問判準
• #71 Tab Order = DOM Order = Mental Model 三者對齊 — DOM 順序 = tab 順序、不對齊時優先重排 DOM
• 更新 #68 加「為什麼 Checkpoint 1 也常被跳過」段、用本次任務當 self-case

然後實作 — 依 #69 RED-GREEN 順序：

1. 寫 4 個 RED tests
2. 跑 → 4 個 fail（confirms RED）
3. 修 search.html（URL persist + DOM reorder + UI hint）
4. 跑 → 8/8 GREEN

CI + 自動化

最後補 CI 防護：

• .github/workflows/playwright.yml — push / PR 自動跑 8 個 tests
• deploy.yml 修 critical bug — production 一直只 build 單 index、現在 build 三份對齊本地
• make test + make verify-red-green PRE_FIX=<sha> — codify retrospective 流程、不需手動 stash / checkout / restore

數字總結

學到什麼

1. Cards-skills 系統是雙向的

不是「先寫卡片、再用卡片」。是「卡片指導實作、實作問題回流卡片」。每一輪迭代都把學到的東西反饋。本次 14 張新卡有 8 張是修過程中實際遇到的問題抽出來的、不是預先想的。

2. User 提問是「外部觸發」

我自己跑 #67 / #68 / Checkpoint 1 的機率低 — 因為這些都是「沒便利路徑」的工作。User 的兩次提問（「有先寫測試嗎」+「需求確認最重要功能」）剛好對應 #69 + Checkpoint 1 的觸發。結構性偏差需要外部觸發來修正、不能靠自我提醒。

3. Test 過 ≠ 對齊使用者意圖

第一輪修完、跑 4/4 GREEN、看起來完工。實際漏了：

• 3 個測試是 placebo（沒做 RED 不知道）
• 3 個 silent 缺口（沒做 Checkpoint 1 不知道）

任何「跑得通就 OK」的訊號都低資訊量。Real 訊號 = 對照「使用者意圖完整集合」逐一驗收。

4. 一個 bug 修完 = 一個 case study 起點

如果停在「bug 修了、test 過了」、這次任務 5 個 commits 結束。User 的兩次提問把它變成 30+ 個 commits 的 case study、產出 17 張新卡 + 兩個 skill 升級 + CI 補強。修 bug 是 trigger、不是終點。

適合 reuse 這個流程的條件

不是每個 bug 都該走這套。適合的訊號：

• Bug 修法不直觀、會碰到多種策略選項（→ 需要 #59 類取捨架構）
• 修法可能影響其他 feature 或產生新案例（→ 需要 Checkpoint 1）
• 需要長期 regression 防護（→ 需要 #69 RED-GREEN 驗證）
• 修的過程中發現新原則（→ 抽卡片）

不適合：純 typo / config / build 失敗 — 直接修。

對未來想用這套系統的人

進入點：

1. 讀 content/skills/_index.md — 三個 skill 的 routing table
2. 從你的問題情境找對應 skill：
   • 不確定怎麼跟 user 溝通 → requirement-protocol
   • 前端 / 資料流實作 → frontend-with-playwright
   • 寫文件 / 註解 / log → compositional-writing
3. Skill 路由你到 specific reference、reference 路由你到 content/report/ 深度卡片
4. 修問題過程中發現新原則 → 抽卡片回流

「卡片不是在實作之前一次寫完、是在實作之中持續累積」 — 這套系統的 leverage 在於「下一個類似問題能直接用、不用重新發明」。

結語

content/report/ 從 54 張長到 71 張、.claude/skills/ 從 v0.1 進到 v0.2、CI 從假 pass 變真防護、search bug 從 silent 失敗變到 8/8 regression test 守護。

過程不是線性。是「先做 → 抓到 dogfooding 失敗 → 抽卡片 → 回頭修 → 再被抓失敗 → 再抽卡片 → 再修」。每一輪都讓系統往對齊使用者意圖的方向多走一點。

User 的角色關鍵：兩次提問都不在「指出 bug」、是在「指出我跳過的 checkpoint」。這是純執行者看不到的盲點 — 自己的 dogfooding 失敗。外部 reviewer 是 cards-skills 系統的必要組件、不是 optional。

下次有類似情境的人 — 不需要把這條路再走一遍、直接用 #55-#71 + 三個 skill 起步。如果發現新 case、抽新卡回流。系統的價值在每次使用都會變強。

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

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 層整合測試）才能真正發揮效果。

TDD 走得好好的：Phase 1 設計介面，Phase 2 寫測試規格，Phase 3 實作，Phase 4 重構評估。Ticket 系統也運作正常：建立、認領、完成、歸檔。但這兩套系統各走各的路。結果是開發者在 Phase 3 開始實作時，才發現手上的任務其實包含三件事。或者更糟：沒發現，就這樣把三件事塞進一個 Ticket 完成了。

問題根源很清楚：Ticket 設計決策沒有固定時間點，也沒有固定標準。有人在需求進來時就設計 Ticket，有人在 Phase 1 結束後，有人在開始實作前隨手建一個。技術債務藏在職責混亂的 Ticket 裡，等到 Phase 4 才浮出水面，代價已經翻了好幾倍。

解決方案不複雜，但需要紀律：把 Ticket 設計決策集中到 Phase 3a，只用一套固定標準來判斷。

Phase 3a 是唯一的決策點

第一條規則：Ticket 設計決策只在 Phase 3a 進行。

Phase 1 專注功能設計，Phase 2 專注測試設計，這時候分心去設計 Ticket 結構反而干擾品質。等到 Phase 3a，手上已經有完整的測試規格，此時問「這個任務需不需要拆分」才有足夠資訊，而且判斷結果會直接影響 Phase 3b 的執行方式——決策和執行緊密相連。

Phase 3b 按 Phase 3a 的評估結果執行，Phase 4 做跨 Ticket 的重構評估，但不新增 Ticket。

丟掉量化指標

用什麼標準判斷要不要拆分？

過去常見做法是量化估計：修改幾個檔案？幾個測試案例？這些數字看起來有根據，用起來卻不可靠。

一個修改 10 個檔案的任務，如果全都是針對同一件事（把某個 API 改名，所有用到它的地方跟著更新），那就是原子任務，不需要拆分。反過來，只改 2 個檔案，如果同時做「驗證邏輯」和「效能最佳化」，就該拆成兩個。

工作量大小和職責數量不是同一件事。

四大檢查：唯一的評估標準

四個問題，確認同一件事：這個任務是不是只做一件事？

語義檢查：能用「動詞 + 單一目標」描述嗎？「實作 startScan() 方法」通過，「實作掃描功能和離線支援」不通過。有時候任務的問題在名字上就看得出來。

修改原因檢查：這個任務只有一個修改原因嗎？來自 SRP 的概念，搬到 Ticket 層次：如果這個 Ticket 將來需要修改，觸發修改的原因只有一個嗎？同時受到「API 規格變更」和「離線儲存格式變更」影響的，就是兩個修改原因，應該拆開。這樣 API 改變時，只需要動一個 Ticket。

驗收一致性檢查：所有驗收條件都指向同一個目標嗎？驗收清單同時包含「startScan() 通過測試」、「stopScan() 通過測試」、「離線快取功能正常」，這個 Ticket 在追求三個目標，需要拆分。

依賴獨立性檢查：拆分後的部分之間會不會產生循環依賴？有時候兩件事看起來應該分開，但 Ticket A 的實作需要 Ticket B 完成，Ticket B 又需要 Ticket A 完成——這種情況保持為同一個 Ticket 才對。

決策邏輯直接：四項全部通過就繼續執行，任何一項未通過就拆分。不確定的預設為未通過。過度拆分的代價，遠低於讓職責混亂的任務進入實作。

不確定時，選擇拆分

這條原則違反一些人的直覺：任務感覺稍微大了一點，但四大檢查又沒有明確說要拆，這時候怎麼辦？

拆。

原因是非對稱性。拆了但其實不需要拆，代價是多幾個 Ticket、多一些追蹤開銷。沒拆但其實應該拆，代價是職責混亂的實作、測試難以隔離、Phase 4 牽一髮動全身。後者的代價明顯更高。

拆分之後

判定需要拆分，Phase 3a 的工作是把任務分解成多個各自通過四大檢查的 Atomic Ticket，並建立它們之間的依賴關係（哪個必須先完成，哪些可以並行）。

規劃結果記錄到工作日誌，PM 審核確認後按 Wave 順序執行——有依賴的先完成，無依賴的並行。每個 Ticket 完成後立即 Review，不等全部完成再回頭看。

一個細節：拆分出來的每個 Ticket 本身也要通過四大檢查。如果某個拆出來的 Ticket 還是不通過，繼續拆。

在實作中發現需要拆分

有時 Phase 3a 評估沒問題，但 Phase 3b 實作途中才發現任務包含多個職責——這表示 Phase 3a 有遺漏。

正確做法：停下來，回到 Phase 3a 重新評估，拆分，從拆分後的第一個 Ticket 重新開始。

這聽起來很傷，但繼續實作一個已知職責混亂的任務，只是在未來製造更大的麻煩。

積極派發子任務

實作中遇到預期外的情況：發現新問題需要調查、範圍比預期大、需要做技術決策——原則是積極建立子任務，不要在一個 Ticket 裡處理所有事情。

目的是保持可追蹤性。每個被處理的問題都有對應的 Ticket，日後審查開發歷程時，能清楚看到每個決策的前因後果。

整合之後

整合後得到的不只是更整齊的任務管理。Phase 3b 的開發者拿到手的每個任務都是職責明確的，不需要在實作途中自己判斷「這個應不應該一起做」。Phase 4 的重構評估也更聚焦，每個 Ticket 邊界清晰，影響範圍好估計。

這套整合需要紀律——Phase 3a 的四大檢查不是走過場，決策如果散落在各個階段，整合就失去意義。

但兩套系統會相互強化：好的 Ticket 設計讓 TDD 執行更流暢，嚴格的 TDD 流程讓 Ticket 的職責判斷更有依據。

深入研究Kent Beck的原著和Valentina Jemuović的演講後，才發現問題出在我們誤解了「測試單元」是什麼。

痛苦的根本原因

許多團隊學TDD時，都被教導「每個class寫一個test class，每個method寫一個test method」。這個看似合理的原則，埋下了長期的痛苦。

問題在於，這樣的測試耦合到了程式的結構，而非行為。只要重構——把一個class拆成兩個、把方法提取到新類別——測試就跟著破裂。維護測試的時間甚至超過寫功能本身。

Kent Beck在《Test Driven Development By Example》第一頁就寫道：

“Programmer tests should be sensitive to behavior changes and insensitive to structure changes.”

測試應該對行為的改變敏感，對結構的改變不敏感。如果重構時測試跟著爆炸，原因就在這裡。

測試是可執行的需求規格

需要先轉換一個根本認知：測試不是「驗證實作正確的工具」，而是用程式碼表達的需求規格書。

需求定義系統「應該做什麼」，實作是「怎麼做」的一種方式。需求應該保持穩定，實作可以隨時改變。Martin Fowler在《Refactoring》中說：

“Refactoring is a way of restructuring an existing body of code, altering its internal structure without changing its external behavior.”

重構改變內部結構，不改變外部行為。耦合到行為的測試，在重構時自然保持穩定。

Sociable Unit Tests：把Module當作測試單元

TDD有兩種截然不同的流派。

Classical TDD（Kent Beck、Martin Fowler的做法）把Unit定義為Module——一個或多個協同工作的類別組合，對外提供清晰的Public API。測試只透過這個Public API互動，不知道Module內部有哪些類別、它們如何協作。唯一需要Mock的是真正的外部依賴：資料庫、檔案系統、外部服務。這種風格稱為Sociable Unit Tests。

Mockist TDD（London School）把Unit定義為單一Class，Mock所有協作者。這種風格稱為Solitary Unit Tests。

核心差異在耦合對象：

1Sociable: Test → [Module API] → Module Implementation（黑盒）
2Solitary: Test → Mock(B) → Class A → Class B
3                 Mock(C)           → Class C

Sociable只有一條耦合線，Solitary有多條。每一條耦合線都是日後的維護成本。

重構安全性的驗證

判斷自己的測試是Sociable還是Solitary，有個簡單的驗證方法：

改變Module的內部邏輯、調整類別結構、重新命名內部方法。如果所有測試依然通過，不需要修改，那你寫的是Sociable（正確）。如果任何測試需要跟著改，那你寫的是Solitary（需要重新設計）。

以一個訂單提交的例子來說，Sociable測試看起來像這樣：

 1test('使用者提交訂單成功', () async {
 2  // Given: Mock外部依賴（只Mock Repository）
 3  when(mockRepository.save(any))
 4      .thenAnswer((_) async => SaveResult.success('order-123'));
 5
 6  // When: 透過Use Case API提交訂單
 7  final result = await submitOrderUseCase.execute(order);
 8
 9  // Then: 驗證可觀察的行為結果
10  expect(result.isSuccess, true);
11  expect(result.orderId, 'order-123');
12  // 測試不知道Order內部如何計算、驗證
13  // 測試使用真實的Domain Entities
14});

而Solitary測試會是：

 1test('OrderService.submitOrder calls Repository.save', () async {
 2  // Given: Mock所有協作者
 3  final mockOrder = MockOrder();          // 連Order也Mock了
 4  final mockValidator = MockOrderValidator();
 5  final mockCalculator = MockPriceCalculator();
 6
 7  when(mockValidator.validate(mockOrder)).thenReturn(true);
 8  when(mockCalculator.calculate(mockOrder)).thenReturn(100);
 9  when(mockRepository.save(mockOrder))
10      .thenAnswer((_) async => SaveResult.success('order-123'));
11
12  // Then: 驗證方法呼叫次數（實作細節）
13  verify(mockRepository.save(mockOrder)).called(1);
14  // 這個測試一旦重構OrderService的內部邏輯就會破裂
15});

Test-First的速度優勢

Test-First（先寫測試）比Test-Last（先寫程式再補測試）快，原因是問題被發現的時間點更早。

Test-First的Red-Green-Refactor循環強迫你在寫實作之前先思考介面：「這個功能怎麼用？」、「測試容不容易寫？」介面設計問題在寫測試時（最早期）就暴露，修復成本最低。

Test-Last則是程式寫完了才發現難以測試，這時通常意味著設計有問題，要改動的範圍更大。Kent Beck說TDD更快，指的正是這個。

BDD不是新方法，是修正命名

Dan North在2006年創造「BDD」，目的是修正TDD命名造成的混淆。

他發現「Test」這個詞讓開發人員誤以為要測試每個類別和方法，於是用「Behavior」取代，讓意圖更清楚：測試的是行為，不是程式結構。這和Kent Beck 2003年說的完全一致，只是換了個能讓人更直覺理解的詞。

Google在《Software Engineering at Google》中也驗證同樣的結論：「Don’t write a test for each method. Write a test for each behavior.」

與Clean Architecture的結合

Sociable Unit Tests和Clean Architecture是天然的組合，因為建立在相同原則上：業務邏輯獨立於外部世界。

在Clean Architecture中，Use Cases層是業務邏輯的進入點，對外提供清晰的API，對內只使用Domain Entities和透過介面隔離的外部依賴（Repository、Gateway等）。這個結構天然對應Sociable的需求：Use Cases的Public API就是測試邊界，Domain Entities用真實物件，只有Repository需要Mock。

更重要的是，對Use Cases的Unit Test同時就是業務驗收測試。一個寫著「使用者提交訂單成功」的案例，不需要啟動UI也不需要真實資料庫，但驗證了完整的業務流程。Alistair Cockburn在提出Hexagonal Architecture時說：「Tests are another user of the system.」

並非所有情況都適合Sociable。數學演算法、加密系統這類需要細粒度驗證的場景，精確定位到具體類別比重構穩定性更重要，用Solitary合理。但大多數商業應用不是這類。

結論

我們曾以為TDD很痛苦，但那是因為我們測試的是程式長什麼樣子，而不是它做什麼。

正確的做法只有一句話：測試透過Module的Public API互動，只Mock真正的外部依賴，使用真實的Domain Entities。

這樣的測試在重構時保持穩定，在功能改變時精準報警。Kent Beck、Dan North、Martin Fowler在不同年代說的是同一件事：測試行為，而非結構。

參考資料：

• Kent Beck，《Test Driven Development By Example》，2003
• Martin Fowler，《Refactoring: Improving the Design of Existing Code》，1999
• Dan North，《Introducing BDD》，2006
• Google，《Software Engineering at Google》，2020
• Valentina (Cupać) Jemuović，TDD and Clean Architecture - Driven by Behaviour

生命週期總覽

 1需求/問題產生
 2    |
 3    v
 4建立 Ticket (/ticket create)
 5    |
 6    v
 7Ticket 狀態: pending
 8    |
 9    v
10認領 Ticket (/ticket track claim)
11    |
12    v
13Ticket 狀態: in_progress
14    |
15    +-- 正常完成 --> /ticket track complete --> 狀態: completed
16    |
17    +-- 無法繼續 --> /ticket track release --> 狀態: blocked
18    |                                              |
19    |                                              v
20    |                                         升級到 PM 處理
21    |
22    v
23完成

這套系統的核心目標是將任務需求有邏輯地拆分拆細。任務進來後先分析，拆分成平行的子任務；子任務若仍太大，可繼續往下切分。執行時從最底層開始，完成後檢查平行任務，再往上驗收父任務，直到整個任務鏈完成。

任務拆小的好處：降低執行時的認知負擔，也讓驗收檢查更容易發現疏失。

Ticket 狀態定義

階段-標準流程對照表

每個生命週期階段都有對應的標準流程和提示，防止關鍵步驟被遺漏。

建立階段

認領階段

執行階段

完成階段

驗收後階段

任務鏈後續步驟建議

當 Ticket 完成時，系統會自動分析任務鏈狀態並建議下一步。

分析優先級

輸出範例

 1============================================================
 2[任務鏈後續步驟建議]
 3============================================================
 4
 5已完成: 0.31.0-W4-007.1
 6        [實作 track P0 功能]
 7
 8任務鏈進度: 1/3 completed
 9   Root: 0.31.0-W4-007
10
11建議下一步:
12   1. 0.31.0-W4-007.2
13      [實作 track P1 功能]
14      原因: 阻塞已解除（blockedBy 0.31.0-W4-007.1 已完成）
15      狀態: pending → 可認領

任務鏈 ID 格式

10.31.0-W3-002              # ticket-handoff 功能（根）
2├── 0.31.0-W3-002.1        # chain_analyzer 模組
3│   ├── 0.31.0-W3-002.1.1  # 問題修復
4│   └── 0.31.0-W3-002.1.2  # 測試補充
5├── 0.31.0-W3-002.2        # handoff_executor 模組
6└── 0.31.0-W3-002.3        # 文件更新

chain 欄位

根任務 0.31.0-W3-002 的 chain：

1chain:
2  root: "0.31.0-W3-002"
3  parent: null
4  depth: 0
5  sequence: [2]

子任務 0.31.0-W3-002.1.1 的 chain：

1chain:
2  root: "0.31.0-W3-002"
3  parent: "0.31.0-W3-002.1"
4  depth: 2
5  sequence: [2, 1, 1]

ID 正則表達式：^(\d+\.\d+\.\d+)-W(\d+)-(\d+(?:\.\d+)*)$

Ticket 建立流程

任務層級判斷

 1任務層級判斷
 2    |
 3    v
 4這個任務是否因為執行現有 Ticket 而產生？
 5    |
 6    +-- 是 → 來源 Ticket 是什麼？
 7    |       |
 8    |       └── 確定來源 Ticket ID → 建立該 Ticket 的子任務
 9    |           ├── 來源: 010.4 → 子任務 ID: 010.4.x
10    |           ├── 來源: 010.4.1 → 子任務 ID: 010.4.1.x
11    |           └── 來源: 010 → 子任務 ID: 010.x
12    |
13    └-- 否 → 建立新任務鏈（新的 Wx-00n）

核心判斷問題：「這個任務是在執行哪個 Ticket 時產生的？」若有明確來源，建立子任務；若無關聯，建立新任務鏈。

建立格式

 1---
 2id: {版本}-W{波次}-{序號}
 3title: {動詞} {目標}
 4type: IMP/RES/ANA/INV/DOC
 5status: pending
 6priority: P0/P1/P2
 7assignee: pending
 8created: {日期}
 9---
10
11# {Ticket ID}: {標題}
12
13## 目標
14
15{目標描述}
16
17## 驗收條件
18
19- [ ] {條件1}
20- [ ] {條件2}

Atomic Ticket 檢查

驗收條件格式要求

驗收條件必須符合 4V 原則：可驗證、可量化、可追溯、可記錄。

標準格式（表格式）：

1## Acceptance Criteria
2
3| #   | 項目       | 來源       | 確認方法   | 狀態 |
4| --- | ---------- | ---------- | ---------- | ---- |
5| 1   | {項目描述} | {來源引用} | {確認方法} | [ ]  |
6| 2   | {項目描述} | {來源引用} | {確認方法} | [ ]  |

Ticket 有效性驗證

有效 Ticket 定義

有效的 Ticket 必須滿足以下條件：

驗證時機

無效 Ticket 處理

無效 Ticket（缺少決策樹欄位）：

• 無法用於 Task 派發（被 Hook 阻止）
• 需要補充決策樹欄位才能使用
• 建議使用 /ticket create 重新建立

補充決策樹欄位

如果 Ticket 缺少決策樹欄位，可手動補充：

1. YAML 格式（在 frontmatter 中）：

   1decision_tree_path:
   2  entry_point: "第X層"
   3  decision_nodes:
   4    - layer: "X"
   5      question: "決策問題"
   6      answer: "答案"
   7      next_action: "下一步"
   8  final_decision: "最終決策"
   9  rationale: "決策理由"

2. Markdown 格式（在內容中）：

   1## 決策樹路徑
   2
   3### 進入點
   4
   5- **層級**: 第X層
   6- **觸發條件**: ...

Ticket 認領流程

認領規則

Ticket 執行流程

 1認領 Ticket
 2    |
 3    v
 4執行對應階段工作
 5    |
 6    v
 7更新工作日誌
 8    |
 9    v
10驗證驗收條件
11    |
12    +-- 全部通過 --> 完成 Ticket
13    +-- 部分通過 --> 繼續處理或升級
14    +-- 無法完成 --> 釋放 Ticket

完成檢查

Ticket 釋放流程

釋放時機

Ticket 類型說明

版本歷史

• v2.8.0 (2026-02-01): 取消驗收豁免機制，改為契約式驗收
• v2.7.0 (2026-02-01): 強化驗收代理人派發要求
• v2.6.0 (2026-01-31): 新增任務層級判斷規則
• v2.5.0 (2026-01-30): 新增階段-標準流程對照表和任務鏈後續步驟建議
• v2.4.0 (2026-01-30): 新增建議追蹤流程整合章節
• v2.3.0 (2026-01-30): 新增驗收條件格式要求章節
• v2.2.0 (2026-01-29): 新增任務鏈 ID 格式章節
• v2.1.0 (2026-01-27): 新增 Ticket 有效性驗證章節
• v2.0.0 (2026-01-23): 重構為 TDD 含 SA 前置審查流程版本