從一個問題出發

試想這樣一張 Ticket：「實作 ISBNScannerService 的 15 個測試」。

15 個不同的測試目標，掃描啟動、停止、ISBN-10 驗證、ISBN-13 驗證、離線快取、批次模式……每一項失敗都讓整張 Ticket 無法完成。負責人要同時記住 15 個目標才能判斷自己有沒有做完。

這不是一張 Ticket，是一份工作清單。

一張 Ticket，最少應該是什麼？

答案：一個動詞 + 一個目標。

什麼是 Atomic Ticket

1Atomic Ticket = 動詞 + 單一目標

核心特徵：

• 單一職責：只有一個修改原因
• 獨立驗收：不需要等待其他任務
• 不可再拆分：硬拆會產生循環依賴，表示這些部分本來就是一體的

四個原子性檢查

語義檢查

「這個 Ticket 能用動詞加單一目標描述嗎？」

符合：「實作 startScan() 方法」、「修復 ISBN 驗證邏輯」。

不符合：描述裡有「和」或「並」——「實作掃描功能和離線支援」通常是兩張 Ticket 擠在一起。

修改原因檢查

「只有一個原因會導致這個 Ticket 需要修改嗎？」

「實作 startScan()」只受掃描 API 規格影響，單一原因。「實作掃描功能和離線支援」則是 API 變更或儲存格式變更都會觸發修改——兩個原因，應拆成兩張。

驗收條件一致性

「所有驗收條件都指向同一個目標嗎？」

如果驗收條件同時涵蓋 startScan()、stopScan() 和離線快取，其實在同時驗收三件事，應該拆開。

依賴獨立性檢查

「如果拆成兩張，它們之間有循環依賴嗎？」

「實作掃描啟動邏輯」和「實作掃描狀態管理」互相依賴，硬拆反而讓兩張都無法獨立完成——這種情況維持為單一 Ticket 才對。

反過來，「實作 startScan()」和「實作 stopScan()」是單向依賴，可以安全拆分。

什麼不是判斷原子性的依據

常見的錯誤標準：時間、程式碼行數、檔案數量、測試數量。

這些都是結果，不是原因。一個單一職責的任務可能只需要 10 行，也可能跨越多個檔案改 200 行。判斷的唯一依據是職責是否單一。

行為分離：開發、測試、調整各自追蹤

1開發 (IMP) → 測試 (TST) → 調整 (ADJ)
2                  |
3               發現問題
4                  |
5           分析 (ANA) → 調整 (ADJ)

開發完成不代表測試通過，測試完成可能衍生調整。把這三種行為混在同一張 Ticket，就失去了「問題在哪個環節發生」的追蹤能力。

完整的追蹤鏈讓我們能回答：「這個修復是從哪一次測試失敗衍生的？那次測試又是為了驗證哪個開發任務？」

Ticket 類型定義

七種類型區分不同性質的任務：

• IMP（Implementation）：開發新功能
• TST（Testing）：執行測試驗證
• ADJ（Adjustment）：調整或修復問題
• RES（Research）：探索未知領域
• ANA（Analysis）：理解現狀和問題
• INV（Investigation）：深入追蹤問題根因
• DOC（Documentation）：記錄和傳承經驗

Ticket 關聯追蹤

每張 Ticket 記錄三個關聯欄位：

• source_ticket：觸發此 Ticket 的來源
• spawned_tickets：此 Ticket 衍生的後續 Ticket
• dispatch_reason：派發原因和交接理由

1開發 Ticket (IMP) 完成
2    |
3    | 衍生
4    v
5測試 Ticket (TST)
6    |
7    | 測試失敗，衍生
8    v
9調整 Ticket (ADJ)，dispatch_reason: "UC-01 測試失敗，需修復 ImportService"

Ticket ID 命名規範

1根任務：{Version}-W{Wave}-{Seq}
2子任務：{根ID}.{n}[.{n}...]

Wave 代表執行批次的依賴層級：W1 無依賴可並行，W2 依賴 W1，以此類推。

0.15.16-W1-001 是 v0.15.16 的 Wave 1 第一個任務。0.31.0-W3-002.1 是 0.31.0-W3-002 的第一個子任務。單看 ID 就能判斷它在版本工作流中的位置。

5W1H 驅動的欄位設計

每張 Ticket 的 YAML 欄位對應 5W1H：

• Who：負責人與各 Phase 的歷史負責人
• What：任務目標（動詞加單一目標）
• When：觸發時機
• Where：架構層級與影響的檔案清單
• Why：需求依據
• How：任務類型與實作策略

欄位設計讓 Ticket 本身就能完整描述任務全貌，交接時不需要額外解釋背景。

拆分範例

把功能清單拆成原子任務

原始需求：「實作 ISBNScannerService 的 15 個測試」

拆分後：

10.15.16-W1-001: 實作 startScan() 方法
20.15.16-W1-002: 實作 stopScan() 方法
30.15.16-W1-003: 實作 validateIsbn10() 驗證邏輯
40.15.16-W1-004: 實作 validateIsbn13() 驗證邏輯
50.15.16-W2-005: 實作離線掃描支援（依賴 W1）
60.15.16-W2-006: 實作批次掃描模式（依賴 W1）

W1 任務可並行，W2 等 W1 完成後進行。

知道什麼時候不該拆

需求：「實作 BookRepository.save() 方法」

有人可能拆成：Ticket A 實作簽名、Ticket B 實作邏輯、Ticket C 實作驗證。

這是錯的。save() 的簽名、邏輯、驗證三者循環依賴，硬拆後每張都無法獨立完成。正確做法是維持為單一 Ticket。

建立 Ticket 前的四個問題

1. 能用「動詞 + 單一目標」描述嗎？
2. 只有一個修改原因嗎？
3. 所有驗收條件都指向同一個目標嗎？
4. 如果拆開，不會產生循環依賴嗎？

常見的違反模式：「實作 X 和 Y」（兩個目標）、「修復所有 X 測試」（多個目標）、「重構 X 並優化 Y」（兩個行動）、「建立 X 的完整功能」（目標模糊）。

這些原則背後共同指向的是什麼？

在推進一個書庫管理 App 的開發過程中，我們開始認真思考這個問題。結論很簡單：所有程式碼設計原則的終極目標，都是降低閱讀者的認知負擔。

一旦確立了這個核心目標，很多過去「規定要這樣做」的事情，開始有了真正的理由。

認知負擔是什麼

認知負擔（Cognitive Load）指閱讀者在理解程式碼時，需要同時記住的資訊量。

認知心理學家米勒在 1956 年提出「Miller’s Law」：人類工作記憶一次只能處理約 7±2 個項目。超過這個數量，大腦就開始掙扎——反覆閱讀、做筆記、或者乾脆猜。程式碼讓人難懂，通常是寫法讓閱讀者同時記住太多東西。

認知心理學把認知負擔分成三種：

內在認知負擔（Intrinsic Load），任務本身的固有複雜度。排序演算法有它的複雜度，業務邏輯有它的業務規則，無法消除。

外在認知負擔（Extraneous Load），由不良設計產生的額外複雜度——糟糕的命名、過長的函式、深層巢狀、隱藏的副作用。這些是可以、也應該主動消除的。

相關認知負擔（Germane Load），用於建立心智模型的有益負擔——理解一個設計模式、學習架構決策背後的原因。值得保留。

設計的目標因此很清楚：最小化外在認知負擔，讓閱讀者的認知資源真正用在理解問題本身和建立更深刻的理解。

認知負擔從哪裡來

變數狀態追蹤

每一個區域變數，都是閱讀者需要「記住並追蹤」的一個項目。看看這段程式碼：

 1void processOrder(Order order) {
 2  var items = order.items;
 3  var total = 0.0;
 4  var discount = 0.0;
 5  var tax = 0.0;
 6  var shipping = 0.0;
 7  var finalPrice = 0.0;
 8  var isValid = true;
 9  var errorMessage = '';
10  // 閱讀者需要同時追蹤 8 個變數狀態
11}

函式還沒開始做什麼，閱讀者已經被迫記住 8 個變數。改成這樣：

1void processOrder(Order order) {
2  final pricing = _calculatePricing(order);
3  final validation = _validateOrder(order);
4  // 閱讀者只需追蹤 2 個概念
5}

數量少了，每個名稱也更清楚地說明了它代表什麼。

呼叫層級追蹤

追蹤呼叫鏈需要「堆疊」記憶，就像遞迴一樣，每深入一層就要把上一層的狀態記住。

當閱讀者必須追蹤 methodA -> methodB -> methodC -> methodD 四層呼叫才能理解一段邏輯時，工作記憶很快就到了極限。扁平化呼叫結構，讓邏輯盡量在同一個層次展開，能顯著減輕這種負擔。

命名品質

不佳的命名讓閱讀者需要做「翻譯」工作——先猜測 d 是什麼，再猜測 temp 指的是什麼，然後才能開始理解邏輯。

d 改成 discountAmount，process() 改成 calculateTotalPrice()，閱讀者可以節省的翻譯工夫，直接換成理解業務邏輯的空間。

條件分支複雜度

每一個巢狀的 if，都要求閱讀者同時記住所有外層條件。三層巢狀就是同時記住三個條件，並且理解它們的組合關係。

Guard Clause 是最直接的解法：把各種「不符合條件就提前返回」的情況放在函式開頭，讓主要邏輯只有一層縮排。

1// 提前返回，消除巢狀
2if (!condition1) return;
3if (!condition2) return;
4if (!condition3) return;
5
6// 主邏輯，思路清晰，只有一層縮排

隱藏的副作用

函式名稱說「取得」，但偷偷修改了資料庫；方法說「計算」，但同時更新了快取。這些隱藏的副作用強迫閱讀者不能只看名稱理解行為，必須讀進每一行實作，才能確保自己真的理解了這個函式做了什麼。

「命令與查詢分離」（Command-Query Separation）的原則在這裡特別有用：查詢只讀取狀態，命令只修改狀態，兩者不混用。

降低認知負擔的五個原則

單一責任。一個函式只做一件事。自我檢查方法：用一句話描述這個函式做什麼，句子裡出現「和」或「並且」，通常就代表它做了超過一件事。

自說明命名。名稱本身就是文件。理想的命名讓閱讀者不看實作也能理解函式的用途、變數的內容、類別的職責。isEmailFormatValid 比 isValid 好，onUserLoginSuccess 比 handle 好，calculateMonthlyRevenue 比 calc 好。

避免副作用。函式的行為應該和名稱一致、可以預測。修改輸入以外的任何東西——全域狀態、資料庫、快取——都應該在名稱中反映，或者提取為獨立的命令函式。

扁平化結構。巢狀深度每增加一層，都在要求閱讀者多記住一層上下文。1-2 層巢狀是優良的，3 層開始值得考慮是否能用 Guard Clause 或提取函式來簡化，超過 3 層通常就應該重構了。

資訊就近原則。理解一段程式碼時，如果需要跳到其他三個地方去查定義、查常數、查相關邏輯，認知負擔就在這些跳轉中累積。相關的資訊放在一起，讓閱讀者可以在同一個地方理解完整的概念。

SOLID 原則的另一種解讀

用認知負擔視角回頭看 SOLID，會發現它們有了更直覺的意義。

單一責任原則（SRP） 傳統解釋是「一個類別只有一個改變的原因」。認知負擔的版本是：一個類別只代表一個概念，閱讀者不需要建立多個心智模型。UserRepository 的認知負擔低，UserServiceAndValidatorAndNotifier 的認知負擔高——因為閱讀者必須同時掌握多個不同的概念。

開放封閉原則（OCP） 說對擴展開放、對修改封閉。認知負擔的版本是：新增功能時，不需要理解現有程式碼的全部細節。新增一種折扣類型，如果要讀懂 calculatePrice() 的所有邏輯和現有折扣的互動，認知負擔很高。如果只需要理解 Discount 介面的契約然後實作它，認知負擔就被控制在最小範圍。

介面隔離原則（ISP） 要求介面不應包含使用者不需要的方法。認知負擔的視角：一個胖介面迫使閱讀者掃描並判斷哪些方法與自己相關，這是純粹的額外負擔。

量化認知負擔

主觀感覺「這段程式碼很複雜」很難作為行動依據。我們引入了一個簡單的量化公式：

1認知負擔指數 = 變數數 + 分支數 + 巢狀深度 + 外部依賴數

1-5 分優良，6-10 分可接受，11-15 分需要重構，超過 15 分必須立即處理。

這個公式不是精確科學，但它提供了可以討論的共同語言。一個函式的指數算出來是 18，「這段程式碼太複雜」就不再是模糊的感覺，而是有數字支撐的判斷。

同樣的思路也用在任務規劃：一個任務需要同時追蹤超過 7 個概念、跨越 2 個以上的架構層、修改超過 5 個檔案，認知負擔就超標了，應該拆分，而不是強行一次完成。

為了讓人更容易讀

電腦不在意程式碼怎麼寫。一個八層巢狀的函式和一個 Guard Clause 寫法的函式，在機器眼中差異幾乎是零。真正在乎的，是接下來要讀這段程式碼的人——三個月後的自己，剛加入的新同事，凌晨三點在修 bug 的任何人。

把「降低閱讀者的認知負擔」作為首要目標，所有設計決策就有了一致的評估標準：這樣寫，閱讀者需要記住更多還是更少？這樣命名，不讀實作也能理解嗎？這樣拆分，每個部分的概念有沒有變得更單純？