從一個問題出發

試想這樣一張 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 的完整功能」（目標模糊）。

起初讓代理人完成後回報，但每次回報都消耗 context 空間，狀態散落在對話歷史裡，根本無法可靠查詢。

後來試過 CSV 追蹤表，但 Ticket 設計文件在一個地方、狀態在另一個地方，兩者很容易出現不一致。

最終答案：把狀態放進 Ticket 文件本身的 YAML Frontmatter 裡。

狀態與內容為什麼要分離？

一個 Ticket 天然包含兩種資訊：「要做什麼」和「做到哪裡了」。傳統做法把它們放在不同地方，製造了一個持續的維護負擔——查狀態要看兩個地方，兩個地方隨時可能不一致。

Markdown 的 YAML frontmatter 本來就是機器可解析的結構化資料，直接把狀態放進去，Ticket 就成了自給自足的單元：frontmatter 存設計決策和當前狀態，body 存執行日誌。

核心設計原則

Frontmatter 是唯一的狀態來源

主線程查進度時直接讀 frontmatter，不需要問代理人。代理人更新狀態時直接改 frontmatter，不需要回報主線程。兩端獨立操作，不需要等彼此。

單一文件原則

每個 Ticket 只有一個文件：frontmatter 放識別資訊、5W1H 設計、驗收條件、依賴關係和當前狀態；body 放執行日誌。一個文件說清楚一切。

查詢輸出最小化

summary 產出緊湊的一行式列表，query 只回傳單一 Ticket 的精簡資訊。查詢不應消耗 context，只應提供答案。

Frontmatter 的欄位設計

識別資訊：ticket_id、version、wave，確保每個 Ticket 有唯一且可解析的身份。

單一職責定義：action（有限動詞：Implement、Fix、Add、Refactor、Remove、Update）加 target（操作對象）。強制「動詞 + 單一目標」的格式，防止一個 Ticket 偷渡多個責任。

5W1H 設計：六個欄位確保 Ticket 在建立時就已經回答了誰來做、做什麼、什麼時機、在哪裡改、為什麼要做、怎麼做。

驗收條件：acceptance 列表，每個條目完成後勾選。「完成」的定義在建立時就講清楚，不留到最後才爭。

狀態追蹤：status（pending、in_progress、completed）、assigned（布林值）、started_at、completed_at。

操作流程

• ticket create：生成帶完整 frontmatter 的 Markdown 文件，初始狀態 pending、assigned: false
• ticket track claim：status 改為 in_progress、assigned: true、記錄 started_at
• ticket track complete：status 改為 completed、記錄 completed_at
• ticket track release：Ticket 退回 pending，可由其他人接手
• ticket track summary：輸出所有 Ticket 的緊湊一覽，幾秒掌握版本進度

與文件系統的整合

Ticket 是整個文件系統的最底層：CHANGELOG 的素材從 Ticket 記錄提取，版本收尾時從 Ticket 狀態確認所有任務完成。上面還有 worklog（版本目標）和 todolist（版本索引），各層各司其職，形成可追蹤的鏈條。

向後相容策略

遷移前已有一批 CSV 格式的舊 Ticket。策略是「新格式完整支援，舊格式唯讀查詢」：工具自動偵測，有 tickets/ 目錄就用新格式，只有 tickets.csv 就唯讀讀取。舊版本的 summary 和 list 仍可運作，只是不能執行狀態變更。不需要一次性轉換所有歷史記錄。

實踐中的行為規範

主線程不應該問代理人「你做完了嗎」。執行查詢命令，讀 frontmatter。

代理人完成後，詳細說明寫進 Ticket body（問題分析、解決方案、測試結果），不要輸出給主線程。主線程只需要知道一件事：Ticket 是否已完成。

執行日誌要記完整——不只是最終結果，還有過程中遇到的問題、嘗試的方案、最終選擇的原因。這讓 Ticket 成為可供日後回顧的執行記錄，而不只是一個狀態標記。

本質上解決的問題

主線程不需要「知道」進度，它只需要「查詢」。狀態是持久化的、機器可讀的、時刻最新的。

這把進度追蹤從「溝通問題」變成了「查詢問題」。溝通依賴時機、依賴雙方都在場；查詢只依賴資料存在和工具可靠。從 CSV 到 Frontmatter，本質是從「狀態需要溝通」到「狀態需要持久化」的思維轉換。

這是系統性的問題。

建議為什麼會消失

調查代理人完成分析後，輸出三條行動建議。PM 認為都合理，但在轉換為 Ticket 的過程中，不知不覺只處理了第一條，後兩條就這樣掉落。

沒有人刻意忽略。問題在於缺乏機制：建議產生後，沒有任何地方強制追蹤它的狀態，也沒有把建議和驗收條件連結起來的橋樑。建議存在於報告裡，但沒有人對它的去向負責。

四種狀態，對應四種歸宿

每條建議都必須從「待決定」進入以下三種狀態之一，任務開始執行前不能還掛在待決定。

採納：決定實作。但採納不只是打個勾，必須把建議轉換為具體驗收條件，納入 Ticket 的 Acceptance Criteria，讓它在驗收時可以被明確確認。

拒絕：決定不做。拒絕是合理決策，但必須說明原因——範圍超出、成本太高、已有替代方案。沒有理由的拒絕等同於忽略。

延後：認可價值但現在不是時候。延後必須標註目標版本，否則和被遺忘沒有差別。

採納後的雙向連結

建議被採納後，在驗收條件中新增對應項目，並標註來源指回原始建議。建議追蹤表指向驗收條件編號，驗收條件表引用建議來源——雙向連結讓日後的審查可以追溯整個決策脈絡。

驗收時的強制檢查

Ticket 申請完成時，驗收者必須確認：所有建議都離開了待決定狀態、採納的建議已轉換為驗收條件並完成、拒絕的建議有明確理由、延後的建議有目標版本。任何一項未達成，驗收失敗。

這讓建議追蹤從「應該做」變成「必須做」，不再依賴個人記憶。

實際範例

調查報告提出兩個建議：建立專責驗收代理人，以及建立自動化驗收 Hook。

PM 採納第一個，對應驗收條件 AC-001。第二個因架構尚未支援，延後到 v0.32.0 並建立追蹤 Ticket。

驗收時，兩條建議都離開了待決定狀態，AC-001 對應的工作已完成，延後的建議有明確去處。驗收通過。

責任明確化

建議追蹤的本質是讓每條建議都有人負責。每個決策都有理由，每個採納都有對應的驗收條件，沒有任何建議可以在沒有決策的情況下消失。

引入這個機制後，不需要再追問「那個建議後來怎麼了」。答案永遠在追蹤表裡。

驗收條件（Acceptance Criteria）這個詞不陌生，但在實際流程中，它往往淪為形式：「功能實作完成」、「測試通過」、「文件更新」——三條模糊的描述，沒有人能在執行後說出「這確實通過了」的具體理由。

驗收條件是一份契約

核心定義：驗收條件是用戶和執行者之間的明確約定，雙方都能清楚判斷任務是否完成。

關鍵在「雙方都能清楚判斷」。不是執行者自己說「差不多了」，而是在撰寫驗收條件的當下，就預先定義好「怎樣算完成」的標準。

這延伸出 4V 原則：

可驗證（Verifiable）：每一條都要有具體的確認方法。執行什麼命令？看什麼輸出？要寫明。

可量化（Quantifiable）：「所有測試通過」不夠，要說「77/77 個測試通過」。量化讓驗收可以被計算，不是被感覺。

可追溯（Traceable）：每一條都應該引用來源——哪個設計文件的哪一行、哪個規格的哪個章節。來源讓驗收有根據。

可記錄（Documented）：驗收結果必須能寫入文件，留下狀態標記。三個月後翻開 Ticket，能看到每一條是否通過、通過的證據是什麼。

四種情境，四種確認方式

不同性質的驗收項目需要不同的確認方式，混在一起只會讓「怎麼確認」這件事也變模糊。

功能驗收：程式功能是否正確實作。確認方式是執行命令、看輸出是否符合預期。

流程驗收：開發流程品質關卡——測試全綠、靜態分析無錯誤。確認方式是執行測試套件和工具輸出狀態。

文件驗收：文件是否正確更新。確認方式是檢查特定檔案存在、特定內容在正確位置。

建議驗收：Ticket 執行過程中收到的建議，每一條都需要有明確的處置（採納、拒絕或延後），不能讓建議懸在半空中。

證據，不是感覺

每一條驗收項目通過後，要留下對應的紀錄：命令輸出留命令和輸出文字、測試通過留「77/77 tests passed」、靜態分析留「dart analyze: 0 issues」。

這看起來繁瑣，但意義在於：三個月後翻開這個 Ticket 的人，不需要重跑所有確認，就能看到當初怎麼通過的。

模糊詞彙是驗收條件的天敵

幾個最常出現的危險詞彙：

「完成」沒有說完成的標準是什麼。換成「某子命令可執行並顯示預期的樹狀結構」。

「正常」沒有定義什麼叫正常。換成「輸入無效 ID 時顯示特定錯誤訊息」。

「適當」最危險，因為每個人的感受不同。引用具體標準文件，說「符合品質基線文件的測試覆蓋率要求」。

「符合規範」不說是哪個規範。要把規範文件寫出來。

最低成本陷阱：一個真實的故事

我們曾遇到這樣的驗收條件：「SKILL.md 只列已實作指令，或實作缺失指令」。

這個「或」讓執行者面對兩個選項：刪除文件裡還沒實作的指令描述（省力），或去實作缺失的功能（耗時）。在沒有明確業務意圖的情況下，執行者幾乎必然選第一個。

結果是技術上正確、業務上損失慘重——那些「未實作的指令」其實是規劃中的功能，刪掉等於丟失了產品藍圖。

從那以後我們立下一條規則：驗收條件不可以用「或」連接不同方案，不可以讓執行者自行選擇最低成本的方向。

正確做法是在撰寫驗收條件前先確認業務意圖：這個任務要解決什麼問題？根本原因是什麼？理想結果是什麼？什麼結果不可接受？回答這四個問題後，方向才能確定，而且只有一個方向。

業務意圖的三個宣告

每個 Ticket 的驗收條件要包含三個業務層面的說明：業務目標（要達成什麼）、期望結果（完成後應該是什麼狀態）、禁止結果（完成後不應該是什麼狀態）。

「禁止結果」最常被忽略，但它往往是防止最低成本陷阱最有效的護欄。明確寫下「不可損失規劃中的功能」，執行者就沒辦法假裝「刪除文件」是合理的選擇。

類似地，當文件和實作不一致時，不能用「修正不一致」帶過。要先判斷這個不一致的性質：規劃中的功能（保留並建立實作 Ticket）、錯誤記錄（移除）、過時功能（標記 deprecated）、重命名移動（更新引用）——四種情況對應四種處理方式，一條模糊的驗收條件無法涵蓋。

格式的選擇

三種格式對應不同複雜度：

簡單任務（五條以下）用清單，粗體標記項目，括號標記來源，後面說明確認方法。

中型任務用表格，有編號、項目描述、來源引用、確認方法、完成狀態，按功能/流程/文件分類。

複雜任務用分類格式，每個類別獨立表格，加上驗收摘要區段：「功能驗收 0/N 完成」、「流程驗收 0/N 完成」。

選格式的關鍵是任務是否跨越多個類別。只要同時涵蓋功能實作、測試品質、文件更新，就應該用分類格式。

結語

驗收條件的本質是「事先定義完成的樣子」。這個過程強迫我們在任務開始前就把終點想清楚，而不是結束後才爭論「算不算完成」。

我們從這套方法論得到最大的收穫是一種心態的轉變：當你開始認真設計驗收條件，你其實是在認真思考這個任務究竟要達成什麼。

生命週期總覽

 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 前置審查流程版本