本文件定義 Ticket 從建立到完成的完整生命週期。這套系統是我在 AI 協作開發(Claude Code)過程中逐步建立的任務追蹤機制。

生命週期總覽

 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 狀態定義

狀態說明允許操作
pending等待處理claim
in_progress處理中complete, release
completed已完成-
blocked被阻塞claim(重新認領)

階段-標準流程對照表

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

建立階段

標準流程提示強度說明
SA 前置審查評估建議新功能/架構變更時需要 SA 審查
任務拆分評估建議認知負擔 > 10 時需要拆分
驗收條件 4V 檢查建議確保驗收條件可驗證、可量化、可追溯、可記錄
blockedBy 設定提示提醒設定依賴關係
decision_tree_path 填寫建議派發驗證必需

認領階段

標準流程提示強度說明
阻塞依賴檢查警告如有阻塞依賴,顯示警告
設計文件閱讀建議提醒閱讀相關規格和設計
驗收條件理解建議確保理解驗收標準
error-patterns 查詢建議IMP/ADJ 類型時建議查詢

執行階段

標準流程提示強度說明
問題派發 incident-responder強制遇到錯誤時強制派發
工作日誌更新建議執行過程記錄

完成階段

標準流程提示強度說明
驗收條件勾選確認建議所有條件必須勾選
建議處理確認建議無 pending 建議
派發 acceptance-auditor強制IMP/ADJ 類型必須執行驗收
任務鏈後續步驟建議提示分析並建議下一個 Ticket

驗收後階段

標準流程目的
技術債務記錄將執行過程中發現的技術債務正式記錄,避免遺忘
CHANGELOG 更新在版本發布時更新變更日誌,維護版本歷史的完整性
學習經驗記錄萃取任務中的學習經驗,建構團隊知識網絡
任務鏈進度更新追蹤整體任務鏈完成度,便於掌握專案整體進度

任務鏈後續步驟建議

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

分析優先級

優先級情境建議內容
1有子 Ticket 可開始「子 Ticket {id} 現在可以開始」
2有被解除阻塞的 Ticket「{id} 的阻塞已解除」
3有同層兄弟 Ticket「同層還有 {id} 待處理」
4同 Wave 有其他 pending「同 Wave 還有 N 個待處理」
5任務鏈全部完成「任務鏈 {root} 全部完成」

輸出範例

 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        # 文件更新
類型格式範例
根任務{版本}-W{波次}-{序號}0.31.0-W3-002
子任務{根ID}.{n}[.{n}...]0.31.0-W3-002.1.1

chain 欄位

欄位類型說明
rootstring任務鏈根 ID
parentstring/null直接父任務 ID
depthnumber深度(根=0)
sequencearray序號路徑陣列

根任務 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 時發現問題與任何執行中的 Ticket 無關
問題直接影響該 Ticket 的完成問題是系統性的獨立問題
「執行 X 時發現 Y 問題」「發現系統有 Z 問題」

核心判斷問題:「這個任務是在執行哪個 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., 2., …
必須有來源引用設計文件或需求SKILL.md L97
必須有確認方法定義如何驗證完成執行命令驗證輸出
禁止模糊詞彙不可用「完成」「正常」「適當」用具體描述取代

標準格式(表格式)

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

Ticket 有效性驗證

有效 Ticket 定義

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

條件說明驗證方式
決策樹欄位包含 decision_tree_path 欄位YAML frontmatter 檢查
或決策樹區段包含「## 決策樹路徑」Markdown 區段內容檢查

驗證時機

時機驗證者動作
建立 Ticket/ticket create自動要求填寫決策樹欄位
派發任務agent-ticket-validation-hook阻止使用無效 Ticket
認領 Ticket/ticket track claim確認 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
依賴檢查前置 Ticket 必須完成

Ticket 執行流程

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

完成檢查

檢查項目標準
驗收條件所有條件都已勾選
測試通過相關測試全部通過
文件更新相關文件已更新
工作日誌執行記錄完整

Ticket 釋放流程

釋放時機

時機說明
被阻塞依賴其他 Ticket 完成
超出範圍發現需要額外工作
技術限制當前無法解決
資訊不足需要更多資訊

Ticket 類型說明

類型代碼用途典型時長
ResearchRES探索未知領域1-2 小時
AnalysisANA理解現狀和問題30 分鐘 - 1 小時
ImplementationIMP執行具體任務1-4 小時
InvestigationINV深入追蹤問題根因1-2 小時
DocumentationDOC記錄和傳承經驗30 分鐘 - 1 小時

版本歷史

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