任務圖與依賴關係

你將學到什麼

第 3 堂課介紹了結構化 Task 工具。本堂課加入依賴邊，讓 Claude 能區分哪些工作已就緒、仍被封鎖，或適合平行處理。

你將學會：

• 任務如何形成有向無環圖（DAG）
• addBlockedBy 與 addBlocks 如何表達依賴邊
• 如何用 TaskList 找出 ready set，再用 TaskGet 查看細節
• 為什麼任務圖能支援平行工作，卻不會自動啟動 agents

為什麼平面清單不夠

思考以下五個任務：

□ 建立資料庫 migration
□ 新增 API routes
□ 新增授權 middleware
□ 更新 frontend
□ 執行 integration tests

平面清單隱藏了三項重要資訊：哪些任務現在能開始、哪些能一起執行，以及上游失敗時哪些任務必須停止。

把工作建模成 DAG

          ┌───────────────┐
          │   檢查系統     │
          └───────┬───────┘
                  │
          ┌───────┴────────┐
          ▼                ▼
   ┌────────────┐   ┌────────────┐
   │ DB migration│   │ API 設計    │
   └──────┬─────┘   └──────┬─────┘
          └───────┬─────────┘
                  ▼
          ┌───────────────┐
          │    授權層      │
          └───────┬───────┘
          ┌───────┴────────┐
          ▼                ▼
   ┌────────────┐   ┌────────────┐
   │ Frontend    │   │ Integration│
   │ 整合         │   │ tests      │
   └────────────┘   └────────────┘

當任務狀態為 pending，且 blockedBy 內所有任務都已完成，它就是 ready。多個 ready 任務可能彼此獨立，但平行執行仍需要 Claude 把它們指派給不同 subagents 或 teammates。Task 工具保存協調狀態，本身不是 scheduler。

使用現行工具建立依賴關係

先建立任務，並保留 TaskCreate 回傳的 ID：

{"tool": "TaskCreate", "subject": "建立 DB migration", "description": "新增 schema 與 rollback 測試"}
{"tool": "TaskCreate", "subject": "設計 API contract", "description": "定義 request、response 與 errors"}
{"tool": "TaskCreate", "subject": "新增授權", "description": "實作 policy 與 unit tests"}

假設回傳 ID 是 1、2、3。讓任務 3 等待兩個上游任務：

{
  "tool": "TaskUpdate",
  "taskId": "3",
  "addBlockedBy": ["1", "2"]
}

也可以從上游任務加入相反方向的關係：

{
  "tool": "TaskUpdate",
  "taskId": "1",
  "addBlocks": ["3"]
}

使用 TaskList 取得精簡快照；需要任務說明、blocks 與 blockedBy 時，再用 TaskGet：

{"tool": "TaskList"}
{"tool": "TaskGet", "taskId": "3"}

這些 payload 是給整合程式理解工具 contract 的。在一般 Claude Code 對話中，用自然語言描述依賴關係，讓 Claude 自行呼叫工具即可。

執行 Ready Set

每個排程節點都依照以下步驟：

1. 讀取目前任務清單。
2. 排除 completed、deleted 與已經 in-progress 的任務。
3. 排除 blockedBy 中仍有未完成項目的任務。
4. 選擇一個 ready 任務，或刻意把彼此獨立的 ready 任務平行指派。
5. 開始前先把選中的工作設為 in_progress。
6. 驗證成功後才設為 completed。
7. 重新讀取任務圖，因為 ready set 可能已經改變。

ready(task) = pending(task)
              AND blockedBy(task) 中每個依賴都已 completed

若上游任務失敗，讓下游保持 pending，並在失敗任務的說明中更新 blocker，或重新調整圖。不要為了讓清單全綠而把下游工作標記完成。

Prompt 模式

使用結構化 Task 工具實作這項功能。

1. 每個可獨立驗證的結果建立一個任務。
2. 使用 addBlockedBy 或 addBlocks 加入依賴邊。
3. 實作前先顯示初始 TaskList。
4. 只有在檔案與副作用不衝突時，才平行執行彼此獨立的 ready 任務。
5. 被封鎖的任務維持 pending。
6. 通過該任務的檢查後才標記完成。
7. 最後顯示任務圖與驗證證據。

常見錯誤

• **用 TodoWrite 表達依賴邊：**目前的依賴欄位屬於 TaskUpdate。
• **自行假造 task ID：**ID 由 TaskCreate 結果回傳。
• **把 ready 當成自動執行：**指派與執行是另一個決策。
• **建立 cycle：**若 A 等待 B、B 又等待 A，兩者永遠不會 ready。
• **把每個微小 edit 都建成任務：**任務應該具備獨立意義與驗證方式。

下一堂課

在第 8 堂課中，我們會研究前景與背景執行；同一張依賴圖可以協助判斷何時適合啟動背景工作。

官方依據

• 工具參考
• Agent SDK TypeScript 工具 schema
• 從 TodoWrite 遷移至 Task 工具

最後驗證：2026-07-20。